n8n-mcp-server 0.1.12

MCP server for n8n workflow automation

n8n MCP Server

Connect your AI assistant to n8n workflow automation platform through the Model Context Protocol. This server provides direct access to n8n's entire REST API, enabling AI-powered workflow management, execution monitoring, and automation control.

Quick Start

1. Install with uvx: uvx n8n-mcp-server
2. Add to your Claude Desktop config:

{
  "mcpServers": {
    "n8n": {
      "command": "uvx",
      "args": ["n8n-mcp-server"],
      "env": {
        "N8N_HOST": "https://your-n8n.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

3. Restart Claude Desktop and start automating!

Features

• 40+ Auto-generated Tools - Full access to n8n's REST API
• Smart JSON Handling - Automatically fixes JSON serialization issues
• Custom Lightweight Tools - Optimized tools for working within token limits
• Full Authentication - Secure API key authentication
• Built with FastMCP - Reliable, high-performance MCP implementation

Custom Tools for Large Workflows

The server includes custom tools designed for handling large workflows that might exceed token limits:

• list_workflows_minimal - Lists workflows with only essential metadata (id, name, active, dates, tags)
• get_workflow_summary - Gets workflow info with node/connection counts instead of full data
• partial_update_workflow - Updates specific nodes without sending the entire workflow
• add_nodes_to_workflow - Adds new nodes and automatically handles connection rewiring

File-Based Workflow Management

For working with complete workflows, use these file-based tools:

• create_workflow_from_file - Create a new workflow from a JSON file
• update_workflow_from_file - Update an existing workflow from a JSON file
• export_workflow_to_file - Export a workflow to a JSON file for backup or sharing

These tools solve token limit issues by working with files instead of passing large JSON structures.

Prerequisites

• Python 3.8 or higher
• An n8n instance with API access enabled
• n8n API key

Installation

Using uvx (Recommended)

The easiest way to use n8n MCP Server is with uvx, which runs the server in an isolated environment:

{
  "mcpServers": {
    "n8n": {
      "command": "uvx",
      "args": ["n8n-mcp-server"],
      "env": {
        "N8N_HOST": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using pip

pip install n8n-mcp-server

From Source

1. Clone this repository:

git clone https://github.com/andrewlwn77/n8n-mcp-server.git
cd n8n-mcp-server

2. Install in development mode:

pip install -e .

Configuration

The server requires two environment variables:

• N8N_HOST: Your n8n instance URL (e.g., https://n8n.example.com)
• N8N_API_KEY: Your n8n API key

You can provide these through:

1. Environment variables in your MCP client configuration (recommended for uvx)
2. A .env file in your working directory:

N8N_HOST=https://your-n8n-instance.com
N8N_API_KEY=your-api-key-here

Usage

Running the Server

Start the MCP server:

n8n-mcp-server

Or if running from source:

python -m n8n_mcp

The server will:

1. Connect to your n8n instance
2. Fetch the OpenAPI specification
3. Generate MCP tools for all available endpoints
4. Start listening for MCP requests

What Can You Do?

With n8n MCP Server, your AI assistant can:

• Manage Workflows - Create, update, delete, and organize automation workflows
• Execute Workflows - Trigger workflow runs and pass custom data
• Monitor Executions - Check workflow status, review logs, and handle errors
• Work with Credentials - Safely manage authentication for external services
• Handle Large Workflows - Use optimized tools designed for token limits
• Update Specific Nodes - Modify individual workflow nodes without affecting others
• Add Nodes Dynamically - Insert new nodes and automatically rewire connections
• Import/Export Workflows - Work with workflow files for easy sharing and backup

Recommended Workflow Management: Use the file-based tools (create_workflow_from_file, update_workflow_from_file, export_workflow_to_file) for managing complete workflows. These tools avoid token limits by working with JSON files on your filesystem.

Example commands you can give your AI assistant:

• "List all my active workflows"
• "Execute the 'Daily Report' workflow with today's date"
• "Show me failed executions from the last 24 hours"
• "Create a new workflow from /path/to/workflow.json"
• "Export workflow abc123 to backup.json"
• "Update workflow xyz789 from updated-workflow.json"
• "Add a Slack notification node to my error handling workflow"
• "Update the schedule trigger to run every hour instead of daily"

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration:

Using uvx (Recommended)

{
  "mcpServers": {
    "n8n": {
      "command": "uvx",
      "args": ["n8n-mcp-server"],
      "env": {
        "N8N_HOST": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using pip installation

{
  "mcpServers": {
    "n8n": {
      "command": "n8n-mcp-server",
      "env": {
        "N8N_HOST": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using .env file

If you have a .env file in your working directory:

{
  "mcpServers": {
    "n8n": {
      "command": "n8n-mcp-server"
    }
  }
}

Security Notes

• Keep your .env file secure and never commit it to version control
• Use environment-specific API keys with minimal required permissions
• Consider using read-only API keys for development/testing

Troubleshooting

No Tools Showing in MCP Client

• Ensure the server started successfully
• Check that your n8n credentials are correct
• Verify the MCP client can connect to the server

Connection Failed

• Verify your n8n instance URL is correct and includes the protocol (https://)
• Check that your API key is valid and has the necessary permissions
• Ensure your n8n instance has API access enabled
• Make sure the n8n instance is accessible from your network

Missing Tools

• The available tools depend on your n8n instance version and configuration
• Some endpoints may require admin permissions
• Check the server logs for any errors during initialization

Related Documentation

• n8n API Documentation
• n8n Authentication
• Model Context Protocol
• FastMCP Framework

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.