# n8n MCP Server (Custom)

A lightweight MCP server for n8n API following the Hybrid MCP Light Blueprint pattern.

## Design Philosophy

This server implements the "Hybrid MCP Light" pattern:

1. **5 Curated Tools** - Most frequently used operations as dedicated tools
2. **API Pass-through** - Raw API access for complete coverage
3. **Embedded Documentation** - API reference as an MCP resource

This approach provides a clean tool surface for AI agents while ensuring 100% API capability coverage.

## Curated Tools

| Tool | Description |
|------|-------------|
| `list_workflows` | List all workflows with pagination |
| `get_workflow` | Get complete workflow by ID |
| `list_executions` | List execution history with filters |
| `get_execution` | Get execution details with optional data |
| `trigger_webhook` | Trigger workflow via webhook |
| `n8n_api_call` | Raw API pass-through for any operation |

## Configuration

| Variable | Required | Description |
|----------|----------|-------------|
| `N8N_URL` | Yes | n8n instance URL (without trailing slash) |
| `N8N_API_KEY` | Yes | API key from n8n Settings > API |
| `PORT` | No | Server port (default: 8000) |

## Quick Start

### Docker (Recommended)

```bash
docker run -d \
  -e N8N_URL=https://n8n.example.com \
  -e N8N_API_KEY=your-api-key \
  -p 8000:8000 \
  gitea.ext.ben.io/b3nw/n8n-mcp-custom:latest
```

### Docker Compose

```bash
cp .env.example .env
# Edit .env with your n8n credentials
docker-compose up -d
```

### Local Development

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Copy and configure environment
cp .env.example .env
# Edit .env with your credentials

# Run server
python server.py
```

## MCP Client Configuration

Configure your MCP client to connect to:

```
http://localhost:8000/mcp
```

For streamable HTTP transport (recommended):
```json
{
  "mcpServers": {
    "n8n": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

## API Reference

The server exposes an API reference resource at `n8n://api-reference` which documents all available n8n API endpoints for use with the `n8n_api_call` tool.

### Common Operations via API Pass-through

```python
# Create a workflow
n8n_api_call('/workflows', 'POST', body='{"name": "My Workflow", "nodes": [...], "connections": {...}}')

# Activate a workflow
n8n_api_call('/workflows/123/activate', 'POST')

# List credentials
n8n_api_call('/credentials')

# Create a tag
n8n_api_call('/tags', 'POST', body='{"name": "production"}')

# Delete an execution
n8n_api_call('/executions/456', 'DELETE')
```

## Health Check

The server provides a health check endpoint at `/health` that verifies:
- Server is running
- n8n instance is accessible

```bash
curl http://localhost:8000/health
```

## Architecture

```
n8n-mcp-custom/
├── server.py          # Main MCP server with tools and API client
├── pyproject.toml     # Python dependencies
├── Dockerfile         # Container build
├── docker-compose.yml # Local orchestration
├── .env.example       # Configuration template
└── README.md          # This file
```

## License

MIT