@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