@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

Claude Code

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"
      }
    }
  }
}

Claude Desktop

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.

VS Code (GitHub Copilot)

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"
      }
    }
  }
}

Cursor

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"
      }
    }
  }
}

Windsurf

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"
      }
    }
  }
}

Cline

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.

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

License

MIT — Made by @ntatschner

@thecodesaiyan/tcs-n8n-mcp

Quick Install

@thecodesaiyan/tcs-n8n-mcp

Features

Prerequisites

Installation

Quick Start

Environment Variables

Authentication Types

Client Setup

Option A: Interactive wizard

Option B: CLI command

Option C: Manual config

Available Tools (22)

Workflows (8)

Executions (3)

Tags (4)

Variables (4)

Credentials (1)

Users (2)

Security

Development

Commands

Running locally

Project Structure

Contributing

License

Reviews