# n8n MCP Server

[![Security](https://img.shields.io/badge/security-enterprise--grade-green)](SECURITY.md)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

An enterprise-grade [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants like Claude to securely interact with [n8n](https://n8n.io/) 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](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](https://docs.n8n.io/api/authentication/))

## Quick Start

### 1. Clone the repository

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

### 2. Install dependencies

```bash
pip install -r requirements.txt
```

### 3. Configure environment

```bash
# 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:**
```json
{
  "mcpServers": {
    "n8n": {
      "command": "py",
      "args": ["-3", "C:\\path\\to\\n8n-mcp-server\\server.py"]
    }
  }
}
```

**macOS/Linux:**
```json
{
  "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:

```json
{
  "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

```bash
# 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](SECURITY.md) for security guidelines.

## License

MIT License - see [LICENSE](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