@thecodesaiyan/tcs-n8n-mcp

Manage your n8n workflows through AI assistants

An MCP server that gives AI assistants full control over your n8n workflow automation platform. List, create, update, execute, and manage workflows, executions, tags, variables, credentials, and users — all through natural language.

Installation · Tools · Security · Development

Features

• 22 tools covering the full n8n REST API
• Works everywhere — Claude Code, Claude Desktop, VS Code, Cursor, Windsurf, Cline
• Secure by default — ID validation, sanitised errors, masked secrets, request timeouts
• Flexible authentication — API key (default), Bearer token, or Basic Auth
• Zero config — just provide your n8n API key and go
• Lightweight — under 30KB, no runtime dependencies beyond the MCP SDK and Zod

Prerequisites

• Node.js >= 18
• 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, tests your connection, and outputs ready-to-paste config for your MCP client.

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

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

Environment Variables

| Variable | Required | Default | Description | |----------|:--------:|---------|-------------| | N8N_API_KEY | Yes | — | Your n8n API key (or password for basic auth) | | N8N_API_URL | No | http://localhost:5678 | Base URL of your n8n instance | | N8N_AUTH_TYPE | No | apikey | Authentication method: apikey, bearer, or basic | | N8N_API_USER | Only for basic | — | Username for basic authentication | | N8N_TIMEOUT_MS | No | 30000 | Request timeout in milliseconds |

Authentication Types

• apikey (default) — Sends X-N8N-API-KEY header. This is n8n's standard API authentication.
• bearer — Sends Authorization: Bearer <token> header.
• basic — Sends Authorization: Basic <base64> header. Requires N8N_API_USER to be set.

Client Setup

Option A: Interactive wizard

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

Option B: CLI command

macOS / Linux:

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

Windows (install globally first):

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

Option C: Manual config

Add to ~/.claude.json:

macOS / Linux:

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

Windows:

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

Add to your Claude Desktop config file:

| OS | Path | |----|------| | Windows | %APPDATA%\Claude\claude_desktop_config.json | | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

macOS / Linux:

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

Windows (run npm install -g @thecodesaiyan/tcs-n8n-mcp first):

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

Restart Claude Desktop after saving.

Add to .vscode/mcp.json in your project, or use Command Palette > MCP: Open User Configuration:

macOS / Linux:

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

Windows (run npm install -g @thecodesaiyan/tcs-n8n-mcp first):

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

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-level):

macOS / Linux:

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

Windows (run npm install -g @thecodesaiyan/tcs-n8n-mcp first):

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

Add to your Windsurf config file:

| OS | Path | |----|------| | Windows | %USERPROFILE%\.codeium\windsurf\mcp_config.json | | macOS / Linux | ~/.codeium/windsurf/mcp_config.json |

macOS / Linux:

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

Windows (run npm install -g @thecodesaiyan/tcs-n8n-mcp first):

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

Open MCP Servers > Configure > Advanced MCP Settings and add:

macOS / Linux:

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

Windows (run npm install -g @thecodesaiyan/tcs-n8n-mcp first):

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

Available Tools (22)

Workflows (8)

| Tool | Description | |:-----|:------------| | list_workflows | List all workflows with pagination | | get_workflow | Get full workflow details including nodes, connections, and settings | | create_workflow | Create a new workflow with optional nodes and connections | | update_workflow | Update an existing workflow's name, nodes, connections, or settings | | delete_workflow | Permanently delete a workflow | | activate_workflow | Activate a workflow so it runs on its configured triggers | | deactivate_workflow | Deactivate a workflow to stop trigger-based execution | | execute_workflow | Execute a workflow immediately and return the execution ID |

Executions (3)

| Tool | Description | |:-----|:------------| | list_executions | List executions with optional filters for workflow ID and status | | get_execution | Get full execution details including per-node results and errors | | delete_execution | Delete an execution record |

Tags (4)

| Tool | Description | |:-----|:------------| | list_tags | List all tags used for organising workflows | | create_tag | Create a new tag | | update_tag | Rename an existing tag | | delete_tag | Delete a tag |

Variables (4)

| Tool | Description | |:-----|:------------| | list_variables | List all environment variables (values are masked for security) | | create_variable | Create a new key-value environment variable | | update_variable | Update an existing variable's key or value | | delete_variable | Delete an environment variable |

Credentials (1)

| Tool | Description | |:-----|:------------| | list_credentials | List all credentials (metadata only — secrets are never exposed) |

Users (2)

| Tool | Description | |:-----|:------------| | list_users | List all users with their roles and status | | get_user | Get full details of a user by ID |

Security

| Protection | Description | |:-----------|:------------| | ID Validation | All resource IDs are validated as numeric strings to prevent path traversal attacks | | Error Sanitisation | API error responses only return HTTP status codes, never raw response bodies | | Secret Masking | Variable values are hidden in list output to prevent accidental secret exposure | | Request Timeout | All API calls have a configurable timeout (default 30s) to prevent hanging connections | | No Key Logging | API keys are never logged, echoed, or included in tool output | | Credential Safety | The credentials tool only returns metadata — secrets are never exposed | | Startup Validation | Credentials and connectivity are verified on startup before accepting any requests | | Header Injection Prevention | Basic auth credentials are validated to reject control characters |

Development

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

Commands

| Command | Description | |:--------|:------------| | npm run build | Compile TypeScript to build/ | | npm test | Run test suite | | npm run test:coverage | Run tests with coverage report | | npm start | Start the MCP server |

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              Entry point, fetch wrapper, server setup
  config.ts             Auth type parsing, header building, timeout, connection check
  types.ts              Shared types, interfaces, response helpers
  validation.ts         Zod schemas for input validation
  tools/
    workflows.ts        Workflow CRUD, activation, execution
    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

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