Ben
37c301198b
All checks were successful
Build and Push n8n MCP Docker Image / build (push) Successful in 35s
Implements Hybrid MCP Light pattern with: - 5 curated tools: list_workflows, get_workflow, list_executions, get_execution, trigger_webhook - API pass-through tool: n8n_api_call for complete coverage - API reference resource: n8n://api-reference - Dockerfile and CI workflow for Gitea container registry
139 lines
3.1 KiB
Markdown
139 lines
3.1 KiB
Markdown
# 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
|