Files

Build and Push n8n MCP Docker Image / build (push) Successful in 35s

Details

Initial implementation of n8n MCP server

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

2025-12-26 18:49:11 +00:00

3.1 KiB

Raw Blame History

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:

5 Curated Tools - Most frequently used operations as dedicated tools
API Pass-through - Raw API access for complete coverage
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)

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

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

Local Development

# 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):

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

# 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

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

3.1 KiB Raw Blame History