n8n MCP Server

A Model Context Protocol (MCP) server that provides tools for managing n8n workflows. This allows you to interact with your n8n instance directly through Claude Code or any MCP-compatible client.

Features

Read Operations

• List Workflows - Get all workflows with optional filtering
• Get Workflow - Retrieve a specific workflow by ID
• Get Workflow by Name - Find and retrieve a workflow by name
• Health Check - Test n8n API connectivity

Write Operations

• Create Workflow - Create new workflows
• Update Workflow - Modify existing workflows
• Activate Workflow - Activate workflows to start execution
• Deactivate Workflow - Stop workflow execution
• Delete Workflow - Remove workflows from n8n

Installation

Option 1: NPX Package (Recommended)

Install globally via npm:

npm install -g n8n-mcp-server

Or use npx without installing:

npx n8n-mcp-server

Option 2: Local Development

1. Clone or create the MCP server directory:

   cd /path/to/your/glass-fruit-asmr-development
   cd n8n-mcp

2. Install dependencies:

   npm install

3. Build the TypeScript code:

   npm run build

Configuration

Environment Variables

Create a .env file or set these environment variables:

# Your n8n instance URL (without trailing slash)
N8N_URL=https://sharkscale.app.n8n.cloud

# Your n8n API key
N8N_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJlMTJiNzA4ZC03NTgzLTRlZmYtYThiNy00ODA5YmYzMWU5MmYiLCJpc3MiOiJuOG4iLCJhdWQiOiJwdWJsaWMtYXBpIiwiaWF0IjoxNzUwODkyMzM1fQ.WXCTYn5NEvu_PPtv3BpYYE467b6x5Ezm7zxtlXJjwec

Claude Code Configuration

Add this MCP server to your Claude Code configuration file (~/.claude/mcp.json):

For NPX Installation:

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["n8n-mcp-server"],
      "env": {
        "N8N_URL": "https://sharkscale.app.n8n.cloud",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

For Global Installation:

{
  "mcpServers": {
    "n8n": {
      "command": "n8n-mcp-server",
      "env": {
        "N8N_URL": "https://sharkscale.app.n8n.cloud",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

For Local Development:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/path/to/your/glass-fruit-asmr-development/n8n-mcp/dist/index.js"],
      "env": {
        "N8N_URL": "https://sharkscale.app.n8n.cloud",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage Examples

1. List All Workflows

// List all workflows
n8n_list_workflows({})

// List only active workflows
n8n_list_workflows({ active: true })

// List workflows with specific tags
n8n_list_workflows({ tags: "production,analytics" })

2. Get Specific Workflow

// Get workflow by ID
n8n_get_workflow({ id: "h9g2AcK6qSbAznmy" })

// Get workflow by name
n8n_get_workflow_by_name({ name: "Analytics workflow" })

3. Create New Workflow

n8n_create_workflow({
  name: "My New Workflow",
  nodes: [
    {
      id: "trigger-node",
      name: "Schedule Trigger",
      type: "n8n-nodes-base.scheduleTrigger",
      typeVersion: 1,
      position: [0, 0],
      parameters: {
        rule: {
          interval: [{ field: "hours", hoursInterval: 1 }]
        }
      }
    }
  ],
  connections: {},
  settings: {
    executionOrder: "v1"
  }
})

4. Update Existing Workflow

n8n_update_workflow({
  id: "workflow-id-here",
  name: "Updated Workflow Name",
  nodes: [...], // Updated nodes array
  connections: {...}, // Updated connections
  settings: {...} // Updated settings
})

5. Activate/Deactivate Workflows

// Activate workflow
n8n_activate_workflow({ id: "h9g2AcK6qSbAznmy" })

// Deactivate workflow
n8n_deactivate_workflow({ id: "h9g2AcK6qSbAznmy" })

6. Health Check

// Test API connectivity
n8n_health_check({})

Available Tools

| Tool Name | Description | Required Parameters | |-----------|-------------|-------------------| | n8n_list_workflows | List workflows with optional filters | None | | n8n_get_workflow | Get workflow by ID | id | | n8n_get_workflow_by_name | Get workflow by name | name | | n8n_create_workflow | Create new workflow | name, nodes, connections | | n8n_update_workflow | Update existing workflow | id, name, nodes, connections | | n8n_activate_workflow | Activate workflow | id | | n8n_deactivate_workflow | Deactivate workflow | id | | n8n_delete_workflow | Delete workflow | id | | n8n_health_check | Test API connectivity | None |

Development

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Watch mode for development
• npm start - Start the MCP server

Testing the Server

# Build the project
npm run build

# Test with environment variables
N8N_URL=https://sharkscale.app.n8n.cloud N8N_API_KEY=your-key npm start

Error Handling

The MCP server includes comprehensive error handling:

• API Errors - n8n API errors are properly formatted and returned
• Validation Errors - Input validation using Zod schemas
• Connection Errors - Network and timeout handling
• Authentication Errors - Invalid API key detection

Security Notes

• Keep your n8n API key secure and never commit it to version control
• The API key has full access to your n8n instance
• Use environment variables or Claude Code's secure environment configuration
• Consider using API key scoping if you're on an n8n Enterprise plan

Troubleshooting

Common Issues

1. "N8N_URL and N8N_API_KEY environment variables are required"

   • Ensure both environment variables are set correctly
   • Check that your API key is valid and not expired

2. "n8n API connection failed"

   • Verify your n8n instance URL is correct
   • Check that your API key has the necessary permissions
   • Ensure your n8n instance is accessible from your machine

3. "request/body must NOT have additional properties"

   • This occurs when trying to update workflows with read-only fields
   • The MCP server automatically filters these out

Getting Help

• Check the n8n API documentation: https://docs.n8n.io/api/
• Verify your API key in n8n: Settings > n8n API
• Test connectivity using the health check tool

License

MIT License - see LICENSE file for details.