Tcs N8n MCP README

Features

• 21 tools for common n8n public API operations
• Works everywhere — Claude Code, Claude Desktop, VS Code, Cursor, Windsurf, Cline
• Modern MCP responses — MCP SDK v2, structured content, output schemas, and tool safety annotations
• Secure by default — encoded resource IDs, sanitised errors, bounded responses, and request timeouts
• Flexible authentication — n8n API key (default), with Bearer and Basic modes for compatible proxies/deployments
• Zero config — just provide your n8n API key and go
• Focused dependencies — runtime dependencies are limited to the MCP server SDK and Zod

Prerequisites

• Node.js >= 22.14 (Node 24 LTS is recommended)
• An n8n instance (self-hosted or cloud)
• An n8n API key (how to create one)

Installation

Quick Start

npx @thecodesaiyan/tcs-n8n-mcp --setup

The setup wizard walks you through configuration, reads the API key or password without terminal echo, tests your connection, and configures detected clients. Printed fallback snippets use a <set-in-client-config> placeholder so credentials are not written to terminal logs.

Windows users: npx cannot resolve bin commands from scoped packages on Windows. Install globally instead:

TerminalCopy

npm install -g @thecodesaiyan/tcs-n8n-mcp
tcs-n8n-mcp --setup

Environment Variables

Authentication Types

• apikey (default) — Sends X-N8N-API-KEY header. This is n8n's standard API authentication.
• bearer — Sends Authorization: Bearer <token>, for deployments or reverse proxies that accept it.
• basic — Sends Authorization: Basic <base64>, for compatible deployments or reverse proxies. Requires N8N_API_USER.

N8N_API_URL must not contain embedded credentials, a query string, or a fragment. The server normalises the URL so /api/v1 is appended exactly once.

Client Setup

npx @thecodesaiyan/tcs-n8n-mcp --setup

claude mcp add n8n -e N8N_API_URL=http://localhost:5678 -e N8N_API_KEY=your-api-key -- npx -y @thecodesaiyan/tcs-n8n-mcp

npm install -g @thecodesaiyan/tcs-n8n-mcp
claude mcp add n8n -e N8N_API_URL=http://localhost:5678 -e N8N_API_KEY=your-api-key -- tcs-n8n-mcp

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@thecodesaiyan/tcs-n8n-mcp"],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

{
  "mcpServers": {
    "n8n": {
      "command": "tcs-n8n-mcp",
      "args": [],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@thecodesaiyan/tcs-n8n-mcp"],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

{
  "mcpServers": {
    "n8n": {
      "command": "tcs-n8n-mcp",
      "args": [],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

{
  "servers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@thecodesaiyan/tcs-n8n-mcp"],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

{
  "servers": {
    "n8n": {
      "command": "tcs-n8n-mcp",
      "args": [],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@thecodesaiyan/tcs-n8n-mcp"],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

{
  "mcpServers": {
    "n8n": {
      "command": "tcs-n8n-mcp",
      "args": [],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@thecodesaiyan/tcs-n8n-mcp"],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

{
  "mcpServers": {
    "n8n": {
      "command": "tcs-n8n-mcp",
      "args": [],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@thecodesaiyan/tcs-n8n-mcp"],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

{
  "mcpServers": {
    "n8n": {
      "command": "tcs-n8n-mcp",
      "args": [],
      "env": {
        "N8N_API_KEY": "your-api-key-here",
        "N8N_API_URL": "http://localhost:5678"
      }
    }
  }
}

Available Tools (21)

Workflows (7)

The n8n public API does not expose a portable POST /workflows/{id}/execute operation, so this package does not offer direct workflow execution. To run a workflow on demand, expose and call a webhook trigger or use an n8n-supported test/execution facility appropriate to your deployment.

Executions (3)

Tags (4)

Variables (4)

Credentials (1)

Users (2)

Security

MCP client configuration stores N8N_API_KEY (or the Basic password) in plaintext because stdio clients pass credentials through environment variables. Restrict access to these files. Automatic setup tightens the resulting file to 0600 on POSIX; Windows users should verify the file ACL. Printed manual snippets contain a credential placeholder, never the entered secret.

Tool results are bounded to protect the model context. Use pagination and request execution data only when needed. The server supports the documented tools above, not the entire n8n REST API; availability can also vary by n8n edition and version.

Development

git clone https://github.com/ntatschner/tcs-n8n-mcp.git
cd tcs-n8n-mcp
npm install

Commands

Running locally

# API key auth (default)
N8N_API_KEY=your-key N8N_API_URL=http://localhost:5678 npm start

# Bearer token auth
N8N_AUTH_TYPE=bearer N8N_API_KEY=your-token N8N_API_URL=http://localhost:5678 npm start

# Basic auth
N8N_AUTH_TYPE=basic N8N_API_USER=admin N8N_API_KEY=password N8N_API_URL=http://localhost:5678 npm start

Project Structure

src/
  index.ts              Thin CLI and stdio entry point
  server.ts             MCP server factory and tool registration
  client.ts             Normalised, timeout-aware n8n API client
  config.ts             Auth type parsing, header building, timeout, connection check
  types.ts              Shared types, response validation and bounded output helpers
  validation.ts         Zod schemas for input validation
  tools/
    workflows.ts        Workflow CRUD and activation
    executions.ts       Execution listing and management
    tags.ts             Tag CRUD operations
    variables.ts        Environment variable management
    credentials.ts      Credential metadata listing
    users.ts            User listing and details

Publishing

Releases are tag-driven. Set package.json to the intended version, then push the matching v<version> tag. CI verifies that the tag exactly matches package.json, runs the supported Node matrix, coverage, audit, pack, and installed-tarball smoke checks, publishes to npm, and only then creates the GitHub release.

The npm package must have a trusted publisher configured for this GitHub repository and .github/workflows/ci.yml. Publishing uses GitHub Actions OIDC with provenance and does not use a long-lived NPM_TOKEN.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/my-feature)
3. Run tests (npm test)
4. Commit your changes (git commit -m 'feat: add my feature')
5. Push to the branch (git push origin feat/my-feature)
6. Open a Pull Request

License

MIT — Made by @ntatschner