n8n-mcp-server

jwjordan/n8n-mcp-server

3.2

If you are the rightful owner of n8n-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The n8n MCP Server is a Model Context Protocol server that provides tools for managing n8n workflows, allowing users to create, update, retrieve, and execute workflows through MCP-compatible clients like Claude.

Tools
7
Resources
0
Prompts
0

n8n MCP Server

A Model Context Protocol (MCP) server that provides tools for managing n8n workflows. This allows you to create, update, retrieve, and execute n8n workflows through Claude or other MCP-compatible clients.

Features

  • Create workflows: Build new n8n workflows with nodes and connections
  • Update workflows: Modify existing workflows
  • Retrieve workflows: Get workflow details and configurations
  • List workflows: Browse all available workflows with optional filtering
  • Get webhook URLs: Retrieve webhook URLs for triggering workflows
  • List executions: Browse workflow execution history with filtering options
  • Get execution details: Retrieve detailed execution results, including errors and node outputs

Setup

Prerequisites

  • Node.js 18 or higher
  • An n8n instance (local or remote)
  • n8n API key

Installation

  1. Clone or download this repository

  2. Install dependencies:

    npm install

  3. Set up environment variables:

    export N8N_BASE_URL="http://localhost:5678"  # Your n8n instance URL
export N8N_API_KEY="your_api_key_here"      # Your n8n API key

Getting an n8n API Key

  1. Open your n8n instance
  2. Go to Settings ā†’ Personal ā†’ API Keys
  3. Create a new API key
  4. Copy the key and set it as the N8N_API_KEY environment variable

Usage

Running the Server

npm start

The server will run on stdio and can be connected to by MCP clients like Claude.

Configuration with Claude Desktop

  1. Open Claude Desktop
  2. Go to Settings ā†’ Developer ā†’ "Edit Config"
  3. Add this server to your configuration:
{
  "mcpServers": {
    "n8n-mcp-server": {
      "command": "node",
      "args": ["/Users/jwjordan/Library/Mobile Documents/com~apple~CloudDocs/github/n8n-mcp-server/index.js"],
      "env": {
        "N8N_BASE_URL": "http://localhost:5678",
        "N8N_API_KEY": "your_api_key_here"
      }
    }
  }
}
  1. Save the configuration file
  2. Restart Claude Desktop

Available Tools

create_workflow

Creates a new n8n workflow.

Parameters:

  • name (required): Workflow name
  • nodes (required): Array of workflow nodes
  • connections: Node connections object
  • active: Whether workflow should be active (default: false)
  • settings: Workflow settings object

update_workflow

Updates an existing workflow.

Parameters:

  • id (required): Workflow ID to update
  • name: New workflow name
  • nodes: Updated nodes array
  • connections: Updated connections
  • active: Active status
  • settings: Updated settings

get_workflow

Retrieves a specific workflow.

Parameters:

  • id (required): Workflow ID to retrieve

list_workflows

Lists all workflows.

Parameters:

  • active: Filter by active status (optional)

get_workflow_webhook_urls

Gets webhook URLs for triggering a workflow. Note: workflows must use webhook triggers to be executable via API.

Parameters:

  • id (required): Workflow ID to get webhook URLs for

list_executions

Lists workflow executions with optional filtering.

Parameters:

  • workflowId: Filter executions by workflow ID (optional)
  • status: Filter by execution status - success, error, waiting, running (optional)
  • limit: Maximum number of executions to return (default: 20)
  • includeData: Include execution data in results (default: false)

get_execution

Gets detailed information about a specific execution, including results and errors.

Parameters:

  • id (required): Execution ID to retrieve (must be a number)
  • includeData: Include execution data in results (default: true)

Example Usage

Once connected to Claude, you can use natural language to manage your workflows:

  • "Create a new workflow that sends a Slack message when a webhook is triggered"
  • "Update workflow 123 to add an email notification step"
  • "Show me the details of workflow 456"
  • "List all active workflows"
  • "Get the webhook URLs for workflow 789 so I can trigger it"
  • "Show me the last 10 executions and their status"
  • "Get the detailed results of execution 116, including any errors"
  • "List all failed executions from the last week"

Workflow Execution

n8n workflows cannot be executed directly via the REST API. Instead, workflows must be designed with webhook triggers to enable API-based execution:

  1. Add a Webhook Trigger: Use the "Webhook" node as your workflow trigger
  2. Configure the Webhook Path: Set a unique path like /my-workflow
  3. Activate the Workflow: Workflows must be active for webhooks to work
  4. Get Webhook URLs: Use the get_workflow_webhook_urls tool to retrieve the webhook URLs
  5. Trigger via HTTP: Make HTTP requests to the webhook URLs to execute the workflow

Example webhook URL: http://localhost:5678/webhook/my-workflow

To trigger the workflow, make a POST request to this URL with any required data in the request body.

Execution Monitoring

The MCP server provides comprehensive execution monitoring capabilities:

Viewing Execution History

  • Use list_executions to browse recent workflow executions
  • Filter by workflow ID, status, or limit results
  • Get quick overview of execution status and timing

Debugging Failed Executions

  • Use get_execution with a specific execution ID to get detailed results
  • View node-by-node execution status and outputs
  • Access error messages and stack traces for failed executions
  • Examine data flow between workflow nodes

Example Execution Workflow

  1. List recent executions: Find executions that need investigation
  2. Get execution details: Examine specific failed executions
  3. Identify issues: Review error messages and node outputs
  4. Fix workflow: Update workflow configuration based on findings
  5. Test and monitor: Re-run workflow and monitor new executions

Environment Variables

  • N8N_BASE_URL: Your n8n instance URL (default: http://localhost:5678)
  • N8N_API_KEY: Your n8n API key (required)
  • MCP_LOG_LEVEL: Logging verbosity - DEBUG, INFO, WARN, ERROR (default: INFO)
  • MCP_LOG_FILE: Path to log file (default: ./mcp-server.log)

Logging and Debugging

The MCP server includes comprehensive logging to help debug issues and monitor activity.

Log Levels

  • ERROR: Only errors and failures
  • WARN: Warnings and errors
  • INFO: General information, startup messages, tool calls
  • DEBUG: Detailed request/response data, full payloads

Configuration

Set the log level via environment variable:

# For development - see all activity
export MCP_LOG_LEVEL=DEBUG

# For production - minimal logging
export MCP_LOG_LEVEL=ERROR

Set a custom log file location:

export MCP_LOG_FILE="/path/to/your/n8n-mcp.log"

Monitoring Logs

View logs in real-time:

tail -f mcp-server.log

Search for specific activity:

grep "Tool called" mcp-server.log
grep "ERROR" mcp-server.log

What Gets Logged

  • Server startup and configuration
  • All incoming MCP requests (list tools, tool calls)
  • Tool execution details (arguments, responses)
  • n8n API calls and responses
  • Errors with stack traces
  • Webhook URL generation (localhost vs production)

Example DEBUG log output:

[2025-06-07T14:38:26.676Z] [DEBUG] === Tool Request Received ===
[2025-06-07T14:38:26.676Z] [DEBUG] Full request
{
  "method": "tools/call",
  "params": {
    "name": "list_workflows",
    "arguments": {}
  }
}
[2025-06-07T14:38:26.677Z] [INFO] Tool called: list_workflows

Testing the Server

Use the included test script to verify the server is working:

node test-mcp-client.js

This will test all tools and generate log entries for debugging.

Development

Project Structure

ā”œā”€ā”€ index.js              # Main MCP server
ā”œā”€ā”€ test-mcp-client.js    # Test script for debugging
ā”œā”€ā”€ test-mcp.js          # Additional test utilities
ā”œā”€ā”€ debug-n8n.js         # n8n API debugging script
ā”œā”€ā”€ package.json         # Dependencies and scripts
ā”œā”€ā”€ .env                 # Environment variables (create this)
ā””ā”€ā”€ mcp-server.log       # Log file (generated)

Environment Setup

Create a .env file:

N8N_BASE_URL=http://localhost:5678
N8N_API_KEY=your_api_key_here
MCP_LOG_LEVEL=DEBUG
MCP_LOG_FILE=./mcp-server.log

Webhook URL Handling

The server automatically detects localhost development vs production:

  • Localhost: Uses /webhook-test/ prefix for n8n self-hosted instances
  • Production: Uses /webhook/ prefix for n8n cloud instances

This is configured automatically based on your N8N_BASE_URL.

License

MIT