n8n MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with direct access to your n8n automation platform. This server enables seamless integration between AI tools (like Claude Desktop) and n8n workflows, variables, credentials, and executions.

🚀 Features

Complete n8n Integration (18 Tools)

• Workflow Management (7 tools)

  • list_workflows - List all workflows
  • get_workflow - Get workflow details by ID
  • create_workflow - Create new workflows
  • update_workflow - Update existing workflows
  • delete_workflow - Delete workflows
  • activate_workflow - Activate workflows
  • deactivate_workflow - Deactivate workflows

• Variable Management (5 tools)

  • list_variables - List all variables
  • get_variable - Get variable by key
  • create_variable - Create new variables
  • update_variable - Update existing variables
  • delete_variable - Delete variables

• Credential Management (3 tools)

  • list_credentials - List all credentials (sanitized)
  • create_credential - Create new credentials
  • delete_credential - Delete credentials

• Execution Management (2 tools)

  • list_executions - List workflow executions
  • get_execution - Get execution details by ID

• System Management (1 tool)

  • self_test - Test server connectivity and permissions

Hybrid Architecture

• MCP Protocol: Full JSON-RPC 2.0 compliance via stdio transport
• HTTP Bridge: Health checks and testing endpoints
• Auto-detection: Automatically switches between modes

📦 Installation

Prerequisites

• Node.js 18+
• n8n instance running and accessible
• n8n API key configured

Setup

1. Clone the repository

   git clone <repository-url>
   cd n8n-mcp
   

2. Install dependencies

   npm install
   

3. Configure environment

   cp .env.example .env
   # Edit .env with your settings:
   # N8N_API_KEY=your-api-key-here
   # N8N_BASE_URL=http://localhost:5678
   # MCP_PORT=3001
   

4. Test the installation

   # Test HTTP endpoints
   node index.js &
   curl http://localhost:3001/health
   
   # Test MCP protocol
   node test-all-tools.js
   

🔧 Usage

For MCP Clients (Claude Desktop, etc.)

The server runs as a stdio-based MCP server for AI clients:

node index.js

Claude Desktop Configuration (~/.claude_desktop_config.json):

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["index.js"],
      "cwd": "/path/to/n8n-mcp",
      "env": {
        "N8N_API_KEY": "your-n8n-api-key-here",
        "N8N_BASE_URL": "http://localhost:5678"
      }
    }
  }
}

For HTTP Monitoring

When run in a terminal (TTY), the server provides HTTP endpoints:

node index.js
# Server starts on http://localhost:3001

# Available endpoints:
# GET  /health - Health check
# POST /test   - Run self-test
# GET  /       - Usage instructions

Direct MCP Testing

Test the MCP protocol directly:

# Initialize connection
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node index.js

# Call a tool
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"self_test","arguments":{}}}' | node index.js

🧪 Testing

Comprehensive Test Suite

Run the complete test suite to validate all 18 tools:

node test-all-tools.js

This will:

• Test MCP protocol compliance
• Validate all tool definitions
• Check n8n API connectivity
• Verify error handling
• Provide detailed results

Manual Testing

# Health check
curl http://localhost:3001/health

# Quick self-test
curl -POST http://localhost:3001/test

# Individual tool test
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_workflows","arguments":{"limit":5}}}' | node index.js

🔒 Security

API Key Management

• Store API keys in environment variables
• Use .env files for local development
• Never commit API keys to version control

Credential Sanitization

• Credential data is automatically sanitized in responses
• Only metadata (ID, name, type) is exposed
• Sensitive credential data is never returned

Network Security

• HTTP server binds to localhost by default
• CORS headers configured for cross-origin requests
• No sensitive data exposed via HTTP endpoints

🐛 Troubleshooting

Common Issues

1. "N8N_API_TOKEN not configured"

# Solution: Set your API key
export N8N_API_KEY=your-api-key-here
# Or add to .env file

2. "Connection refused" errors

# Solution: Check n8n is running
curl http://localhost:5678/api/v1/workflows?limit=1 -H "X-N8N-API-KEY: your-key"

3. "License does not allow for feat:variables"

# This is expected for n8n Community Edition
# Variables require n8n Pro/Enterprise license
# The tool will still work but return license errors

4. "GET method not allowed" for credentials

# Some n8n configurations restrict credential access
# Check your n8n security settings

5. Port already in use (EADDRINUSE)

# Solution: Kill existing process or change port
pkill -f "node index.js"
# Or set different port: MCP_PORT=3002 node index.js

Debug Mode

Enable verbose logging:

DEBUG=1 node index.js

Validate Configuration

# Test n8n connectivity
curl -H "X-N8N-API-KEY: your-key" http://localhost:5678/api/v1/workflows?limit=1

# Test MCP server
node test-all-tools.js

📊 Monitoring

Health Checks

# Basic health
curl http://localhost:3001/health

# Detailed system test
curl -X POST http://localhost:3001/test | jq '.result.summary'

Performance Monitoring

The server logs all tool executions and provides timing information:

• Tool execution time
• n8n API response time
• Error rates and types

🤝 Contributing

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: node test-all-tools.js
5. Submit a pull request

Adding New Tools

1. Add tool definition in setupToolHandlers()
2. Implement the tool method
3. Add test case in test-all-tools.js
4. Update documentation

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

• n8n - Workflow automation platform
• Model Context Protocol - Protocol specification
• Claude Desktop - AI assistant with MCP support

📞 Support

• Issues: Use GitHub Issues for bug reports
• Discussions: Use GitHub Discussions for questions
• Documentation: Check this README and inline code comments

---

Ready to automate with AI? 🤖✨

Your n8n workflows are now accessible to AI assistants through the Model Context Protocol!