# 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**
```bash
git clone <repository-url>
cd n8n-mcp
```
2. **Install dependencies**
```bash
npm install
```
3. **Configure environment**
```bash
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**
```bash
# 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:
```bash
node index.js
```
**Claude Desktop Configuration** (`~/.claude_desktop_config.json`):
```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:
```bash
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:
```bash
# 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:
```bash
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
```bash
# 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"**
```bash
# Solution: Set your API key
export N8N_API_KEY=your-api-key-here
# Or add to .env file
```
**2. "Connection refused" errors**
```bash
# 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"**
```bash
# 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**
```bash
# Some n8n configurations restrict credential access
# Check your n8n security settings
```
**5. Port already in use (EADDRINUSE)**
```bash
# 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:
```bash
DEBUG=1 node index.js
```
### Validate Configuration
```bash
# 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
```bash
# 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](https://n8n.io/) - Workflow automation platform
- [Model Context Protocol](https://github.com/anthropics/mcp) - Protocol specification
- [Claude Desktop](https://claude.ai/download) - 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!
