n8n MCP Server

A Model Context Protocol (MCP) server for managing n8n workflows on your self-hosted n8n instance. This server enables AI assistants like Claude to interact with your n8n workflows through a standardized interface.

Features

• Workflow Management: List, create, update, and delete workflows
• Workflow Control: Activate, deactivate, and execute workflows
• Execution Monitoring: List and inspect workflow executions
• Credentials Access: View available credentials (without sensitive data)
• Full API Coverage: Comprehensive support for n8n API operations

Prerequisites

• Node.js 18 or higher
• A self-hosted n8n instance
• n8n API key (generated from your n8n instance)

Installation

1. Clone or download this repository
2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

The server requires two environment variables:

• N8N_BASE_URL: The base URL of your n8n instance (e.g., https://n8n.example.com/api/v1)
• N8N_API_KEY: Your n8n API key

Getting your n8n API Key

1. Log in to your n8n instance
2. Go to Settings → API
3. Click "Create API Key"
4. Copy the generated key

Usage with Claude Desktop

Add this to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/path/to/n8n-mcp-server/build/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com/api/v1",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage with Claude Code

To use this MCP server with Claude Code (the CLI tool), you can add it using the claude mcp add command.

Installation

First, install the package from npm:

npm install @davidfei/n8n-mcp

Or install globally:

npm install -g @davidfei/n8n-mcp

Adding to Claude Code

Use the claude mcp add command to register this MCP server with Claude Code:

claude mcp add n8n \
  --command node \
  --args "node_modules/@davidfei/n8n-mcp/build/index.js" \
  --env N8N_BASE_URL="https://your-n8n-instance.com/api/v1" \
  --env N8N_API_KEY="your-api-key-here"

Or if installed globally:

claude mcp add n8n \
  --command n8n-mcp-server \
  --env N8N_BASE_URL="https://your-n8n-instance.com/api/v1" \
  --env N8N_API_KEY="your-api-key-here"

Verifying Installation

Check that the MCP server was added successfully:

claude mcp list

You should see n8n in the list of available MCP servers.

Using with Claude Code

Once added, you can interact with your n8n workflows directly within Claude Code. Claude will automatically have access to all 13 tools provided by this MCP server:

• Workflow Management: List, create, update, and delete workflows
• Workflow Control: Activate, deactivate, and execute workflows
• Execution Monitoring: List and inspect workflow executions
• Credentials Access: View available credentials

For more information about managing MCP servers with Claude Code, see the Claude Code documentation.

Available Tools

Workflow Management

list_workflows

List all workflows in your n8n instance.

Parameters:

• active (optional): Filter by active status ("true" or "false")

Example:

List all active workflows

get_workflow

Get details of a specific workflow.

Parameters:

• workflow_id (required): The workflow ID

Example:

Show me workflow 123

create_workflow

Create a new workflow.

Parameters:

• name (required): Workflow name
• nodes (required): JSON string of workflow nodes
• connections (required): JSON string of workflow connections
• active (optional): Whether to activate immediately (default: false)
• settings (optional): JSON string of workflow settings

Example:

Create a new workflow called "Data Sync" with these nodes...

update_workflow

Update an existing workflow.

Parameters:

• workflow_id (required): The workflow ID
• name (optional): New workflow name
• nodes (optional): JSON string of updated nodes
• connections (optional): JSON string of updated connections
• active (optional): Activation status
• settings (optional): JSON string of workflow settings

Example:

Update workflow 123 to change its name to "New Name"

delete_workflow

Delete a workflow.

Parameters:

• workflow_id (required): The workflow ID

Example:

Delete workflow 123

Workflow Control

activate_workflow

Activate a workflow.

Parameters:

• workflow_id (required): The workflow ID

Example:

Activate workflow 123

deactivate_workflow

Deactivate a workflow.

Parameters:

• workflow_id (required): The workflow ID

Example:

Deactivate workflow 123

execute_workflow

Manually execute a workflow.

Parameters:

• workflow_id (required): The workflow ID
• data (optional): JSON string of input data

Example:

Execute workflow 123 with this data: {"name": "test"}

Execution Monitoring

list_executions

List workflow executions.

Parameters:

• workflow_id (optional): Filter by workflow ID
• status (optional): Filter by status ("success", "error", "waiting", "running")
• limit (optional): Maximum number of results (default: 20)

Example:

Show me the last 10 failed executions

get_execution

Get details of a specific execution.

Parameters:

• execution_id (required): The execution ID

Example:

Show me execution 456

delete_execution

Delete an execution.

Parameters:

• execution_id (required): The execution ID

Example:

Delete execution 456

Credentials

list_credentials

List all credentials (without sensitive data).

Example:

Show me all available credentials

Example Workflows

Simple HTTP Request Workflow

{
  "name": "Simple HTTP Request",
  "nodes": [
    {
      "parameters": {},
      "name": "Start",
      "type": "n8n-nodes-base.start",
      "typeVersion": 1,
      "position": [250, 300]
    },
    {
      "parameters": {
        "url": "https://api.example.com/data",
        "options": {}
      },
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 1,
      "position": [450, 300]
    }
  ],
  "connections": {
    "Start": {
      "main": [
        [
          {
            "node": "HTTP Request",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

Development

Watch Mode

For development with auto-rebuild:

npm run dev

Building

npm run build

Testing

You can test the server by running it directly:

N8N_BASE_URL=https://your-n8n-instance.com/api/v1 \
N8N_API_KEY=your-api-key \
npm start

Troubleshooting

Connection Issues

• Verify your N8N_BASE_URL includes the /api/v1 path
• Check that your API key is valid
• Ensure your n8n instance is accessible from the machine running the MCP server

Authentication Errors

• Regenerate your API key in n8n settings
• Verify the API key is correctly set in the environment variables

Workflow Execution Fails

• Check that the workflow is properly activated
• Verify all required credentials are configured in n8n
• Review execution logs using get_execution

Security Notes

• Keep your API key secure and never commit it to version control
• Use environment variables or secure secret management
• The list_credentials tool does not expose sensitive credential data
• Consider using n8n's permission system to limit API key access

API Documentation

For more information about the n8n API, see:

• n8n API Documentation

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.