n8n MCP Server

An enterprise-grade Model Context Protocol (MCP) server that enables AI assistants like Claude to securely interact with n8n workflow automation platform.

Built for regulated industries including cryptocurrency, fintech, and enterprises requiring strict security controls.

Security Features

• TLS/SSL Enforcement: HTTPS required by default, certificate verification enabled
• Audit Logging: Comprehensive logging with correlation IDs for compliance
• Rate Limiting: Built-in protection against abuse
• Input Validation: Strict validation with injection pattern detection
• Sensitive Data Redaction: API keys and secrets never logged
• Request Tracing: Correlation IDs for debugging and forensics

See SECURITY.md for full security documentation.

Features

• Workflow Management: Create, read, update, delete, activate, and deactivate workflows
• Execution Control: Execute workflows manually and monitor execution history
• Credential Visibility: List available credentials (metadata only)
• Health Monitoring: Check connectivity and server status

Prerequisites

• Python 3.10 or higher
• An n8n instance with API access enabled
• n8n API key (How to generate)

Quick Start

1. Clone the repository

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

2. Install dependencies

pip install -r requirements.txt

3. Configure environment

# Copy the example environment file
cp .env.example .env

# IMPORTANT: Set secure permissions (Unix/Linux/macOS)
chmod 600 .env

# Edit .env with your n8n credentials

4. Configure Claude Code

Add to your Claude Code settings (~/.claude/settings.json):

Windows:

{
  "mcpServers": {
    "n8n": {
      "command": "py",
      "args": ["-3", "C:\\path\\to\\n8n-mcp-server\\server.py"]
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "n8n": {
      "command": "python3",
      "args": ["/path/to/n8n-mcp-server/server.py"]
    }
  }
}

Configuration

Required Variables

Variable	Description	Example
N8N_URL	n8n instance URL (HTTPS recommended)	https://n8n.example.com
N8N_API_KEY	n8n API key (min 32 chars)	eyJhbGciOiJIUzI1...

Security Variables

Variable	Description	Default
N8N_REQUIRE_HTTPS	Require HTTPS for non-localhost	true
N8N_VERIFY_TLS	Verify TLS certificates	true
AUDIT_LOG_ENABLED	Enable audit logging	true

Optional Variables

Variable	Description	Default
N8N_REQUEST_TIMEOUT	Request timeout (seconds)	30
N8N_MAX_PAYLOAD_SIZE	Max payload size (bytes)	10485760
LOG_LEVEL	Logging level	INFO

Available Tools

Workflow Management

Tool	Description
n8n_list_workflows	List all workflows with optional filtering
n8n_get_workflow	Get details of a specific workflow
n8n_create_workflow	Create a new workflow
n8n_update_workflow	Update an existing workflow
n8n_delete_workflow	Delete a workflow
n8n_activate_workflow	Activate a workflow (enable triggers)
n8n_deactivate_workflow	Deactivate a workflow (disable triggers)
n8n_import_workflow	Import a workflow from JSON

Execution Management

Tool	Description
n8n_execute_workflow	Manually execute a workflow
n8n_list_executions	List execution history with filters
n8n_get_execution	Get details of a specific execution

Other

Tool	Description
n8n_list_credentials	List available credentials (metadata only)
n8n_health_check	Check n8n connectivity and health

Example Usage

List all workflows:

"Show me all active workflows in n8n"

Create a workflow:

"Create a workflow that triggers daily at 8am and sends a Slack message"

Debug a failed execution:

"Why did my last workflow execution fail?"

Health check:

"Check if n8n is connected and working"

Audit Logging

When AUDIT_LOG_ENABLED=true, all operations are logged in JSON format:

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "correlation_id": "a1b2c3d4e5f6",
  "operation": "create_workflow",
  "success": true,
  "duration_ms": 125.5,
  "parameters": {"name": "My Workflow"}
}

Project Structure

n8n-mcp-server/
├── server.py          # Main MCP server (enterprise security)
├── requirements.txt   # Python dependencies
├── .env.example       # Configuration template
├── .env               # Your configuration (git-ignored)
├── .gitignore         # Git ignore rules
├── SECURITY.md        # Security policy and documentation
├── SPEC.md            # API specification
└── README.md          # This file

Troubleshooting

"HTTPS required" error

• Your n8n URL uses HTTP instead of HTTPS
• For development only: set N8N_REQUIRE_HTTPS=false

"TLS verification failed"

• Certificate issue with your n8n instance
• For self-signed certs in development: set N8N_VERIFY_TLS=false

"Rate limit exceeded"

• Too many requests in a short time
• Wait and retry, or check for loops in your usage

"Authentication failed"

• Check N8N_API_KEY is correct
• Verify API key hasn't expired
• Ensure API key has required permissions

Development

# Run with debug logging
LOG_LEVEL=DEBUG python server.py

# Run security scan
pip install bandit
bandit -r server.py

# Check dependencies for vulnerabilities
pip install safety
safety check -r requirements.txt

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes (security-impacting changes require review)
4. Submit a pull request

See SECURITY.md for security guidelines.

License

MIT License - see LICENSE for details.

Changelog

v2.0.0 (2024) - Enterprise Security Edition

• TLS/SSL enforcement by default
• Comprehensive audit logging with correlation IDs
• Rate limiting protection
• Enhanced input validation with injection detection
• Sensitive data redaction
• Security policy documentation
• .env file permission checking

v1.2.0

• Added .env file support
• Added health check tool
• Improved logging

v1.0.0

• Initial release