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:

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

For HTTP Monitoring

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

Direct MCP Testing

Test the MCP protocol directly:

🧪 Testing

Comprehensive Test Suite

Run the complete test suite to validate all 18 tools:

This will:

• Test MCP protocol compliance

• Validate all tool definitions

• Check n8n API connectivity

• Verify error handling

• Provide detailed results

Manual Testing

🔒 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"

2. "Connection refused" errors

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

4. "GET method not allowed" for credentials

5. Port already in use (EADDRINUSE)

Debug Mode

Enable verbose logging:

Validate Configuration

📊 Monitoring

Health Checks

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!