Overview

The N8n Workflow Execution Management MCP Server provides a small HTTP service that exposes n8n workflow and execution management operations in a machine-friendly way suitable for AI assistants and automation platforms. Implemented as a Model Context Protocol (MCP) server, it lets tools (AI agents, orchestration systems, or other services) list, create, update, delete and monitor n8n workflows and their executions through a consistent API and tool manifest.

This server is useful when you want programmatic control over an n8n environment from an AI agent or external automation layer: trigger workflows, inspect execution status, fetch execution logs, or modify workflow definitions without manual use of the n8n UI. By translating n8n operations into MCP-compatible endpoints, assistants can discover available workflow operations and call them safely with tooling-aware responses.

Features

List n8n workflows and metadata
Create new workflows or import JSON workflow definitions
Update existing workflows (activate/deactivate, edit nodes)
Delete workflows
Trigger workflow executions (manual run, execute with inputs)
List and inspect executions, including status and logs
Poll or stream execution status for long-running workflows
MCP-compatible tool manifest for AI assistant discovery
Simple authentication against n8n API key

Installation / Configuration

Clone the repository and run with Node.js or Docker.

Install and run locally (Node.js):

git clone https://github.com/leonardsellem/n8n-mcp-server.git
cd n8n-mcp-server
npm install
# Configure environment variables in .env
npm start

Docker (recommended for isolation):

Example Docker run:

docker run -d \
  -e N8N_URL="https://your-n8n-host" \
  -e N8N_API_KEY="your_n8n_api_key" \
  -e PORT=3000 \
  --name n8n-mcp-server \
  leonardsellem/n8n-mcp-server:latest

Example Docker Compose snippet:

version: "3.8"
services:
  n8n:
    image: n8nio/n8n:latest
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=user
      - N8N_BASIC_AUTH_PASSWORD=pass
    ports:
      - "5678:5678"

  n8n-mcp-server:
    image: leonardsellem/n8n-mcp-server:latest
    environment:
      - N8N_URL=http://n8n:5678
      - N8N_API_KEY=YOUR_N8N_API_KEY
      - PORT=3000
    ports:
      - "3000:3000"
    depends_on:
      - n8n

Environment variables (common):

N8N_URL — base URL of your n8n instance (e.g., http://localhost:5678)
N8N_API_KEY — API key or token to authenticate to n8n
PORT — port for MCP server (default 3000)
LOG_LEVEL — optional logging verbosity

Available Resources

The MCP server exposes a concise set of REST endpoints that represent tools usable by assistants. Typical endpoints:

Endpoint	Method	Description
/workflows	GET	List workflows (id, name, active, nodes summary)
/workflows	POST	Create/import a workflow from JSON
/workflows/:id	GET	Get full workflow definition
/workflows/:id	PUT	Update workflow definition or activation
/workflows/:id	DELETE	Delete a workflow
/executions	GET	List recent executions with status
/executions	POST	Start an execution for a workflow
/executions/:id	GET	Get execution status, node results and logs
/executions/:id/stop	POST	Stop/cancel a running execution
/mcp/manifest	GET	MCP tool manifest describing available tools

Authentication: Each request to the MCP server is proxied to n8n using the configured N8N_API_KEY. The MCP server itself should be placed behind your own authentication layer (API gateway, Basic Auth, or private network).

Sample curl — list workflows:

curl -s "http://localhost:3000/workflows" \
  -H "Accept: application/json"

Trigger an execution with input data:

curl -X POST "http://localhost:3000/executions" \
  -H "Content-Type: application/json" \
  -d '{"workflowId":"123","input":{"key":"value"}}'

Use Cases

AI-assisted workflow orchestration: An AI assistant can enumerate available workflows, decide which to trigger based on user intent, and start an execution with customized input data.
Monitoring long-running processes: Agents can poll /executions/:id to update users when a background data pipeline finishes or when human intervention is needed.
Dynamic workflow generation: Programmatically create or update workflows from templates generated by an assistant (for example, generate a new ETL workflow and activate it).
Incident response: On alerts, an automation platform can trigger remediation workflows and follow their execution logs to confirm completion.
Audit and visibility: Export workflow and execution metadata for analytics, compliance, and dashboards.

Example MCP Tool Manifest (excerpt)

A simple MCP manifest helps AI systems discover available operations:

{
  "name": "n8n-workflow-manager",
  "description": "Manage n8n workflows and executions",
  "tools": [
    {"id":"list_workflows","name":"List Workflows","endpoint":"/workflows","method":"GET"},
    {"id":"start_execution","name":"Start Execution","endpoint":"/executions","method":"POST"},
    {"id":"get_execution","name":"Get Execution","endpoint":"/executions/:id","method":"GET"}
  ]
}

Notes and Best Practices

Secure the MCP server: It proxies powerful operations. Run behind authentication and restrict network access.
Use API keys with least privilege on n8n.
Rate-limit calls from external agents to avoid overwhelming n8n.
For large log payloads or binary artifacts, prefer storing artifacts in external storage and returning references.

For code examples and the latest endpoint details, consult the project repository on GitHub: https://github.com/leonardsellem/n8n-mcp-server.