<div align="center">

⚡ n8n Automation MCP Server

Enterprise-Grade Model Context Protocol (MCP) Server for Complete n8n Instance Automation

<p align="center"> <a href="#-key-features">Key Features</a> • <a href="#-architecture">Architecture</a> • <a href="#-quick-start">Quick Start</a> • <a href="#-tool-reference-34-tools">Tool Reference</a> • <a href="#-claude-desktop--cursor-setup">Client Setup</a> • <a href="#-example-ai-prompts">Use Cases</a> </p>

---

</div>

n8n Automation MCP Server turns Large Language Models (LLMs) in Claude Desktop, Cursor AI, Windsurf, and VS Code into full-stack n8n automation engineers.

With 34 production-ready tools, this MCP server empowers AI agents to autonomously build workflows, debug failed executions, manage credentials, configure environment variables, manage tags, and monitor self-hosted or cloud n8n instances in real time.

---

🎯 High-Rank Keywords & SEO Overview

Keywords: n8n MCP server, n8n REST API automation, Model Context Protocol, Claude Desktop n8n tool, Cursor AI n8n workflow builder, n8n execution debugger, AI workflow orchestrator, self-hosted n8n management, n8n credential manager, n8n workflow export import.

---

✨ Key Features

Feature	Description
🤖 34 Dedicated MCP Tools	Complete coverage of the n8n REST API v1 for Workflows, Executions, Credentials, Tags, Variables, and Users.
💡 Node Templates & Snippets	Built-in list_common_nodes provides instant JSON templates for OpenAI, Slack, Webhooks, Schedules, Code, HTTP Requests, and Switch nodes.
📦 Export & Import Workflows	Backup, share, or version-control workflows seamlessly between local and cloud n8n instances.
⚡ Execution Diagnostics & Retries	Filter error logs, inspect node input/output payloads, stop stuck runs, or trigger single-click execution retries (retry_execution).
🔒 Enterprise Security & Clean Logs	Sensitive credential payloads are automatically masked in responses. Zero unhandled server crashes on startup.
🚀 Lightning-Fast Builds	Built with esbuild for instant compilation (<100ms) with zero TypeScript memory leaks.

---

📐 Architecture

flowchart LR
    subgraph AI Clients
        A[Claude Desktop]
        B[Cursor AI]
        C[Windsurf / VS Code]
    end

    subgraph MCP Protocol
        D[n8n Automation MCP Server]
    end

    subgraph n8n Ecosystem
        E[(n8n Self-Hosted / Cloud)]
        F[Workflows Engine]
        G[Executions Log]
        H[Credentials Store]
        I[Instance Variables]
    end

    A <-->|stdio Transport| D
    B <-->|stdio Transport| D
    C <-->|stdio Transport| D

    D <-->|n8n v1 REST API / X-N8N-API-KEY| E
    E --> F
    E --> G
    E --> H
    E --> I

---

🚀 Quick Start

1. Prerequisites

• Node.js: v18.0.0 or higher
• n8n Instance: Self-hosted (http://localhost:5678) or n8n Cloud (https://your-instance.app.n8n.cloud)
• n8n API Key: Get it from n8n > Settings > API > Create API Key

2. Clone & Install

git clone https://github.com/SohailShabbir867/n8n_mcp.git
cd n8n_mcp
npm install

3. Environment Setup

Create a .env file in the project root:

N8N_BASE_URL=http://localhost:5678
N8N_API_KEY=your_n8n_api_key_here

4. Build

npm run build

---

💻 Claude Desktop & Cursor Setup

⚙️ Claude Desktop Configuration

Add the server entry to your %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "n8n-automation": {
      "command": "node",
      "args": ["C:/path/to/n8n_mcp/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "http://localhost:5678",
        "N8N_API_KEY": "your_n8n_api_key_here"
      }
    }
  }
}

⚡ Cursor / Windsurf Configuration

Navigate to Cursor Settings > Features > MCP Servers and click Add New MCP Server:

• Name: n8n-automation
• Type: command
• Command: node C:/path/to/n8n_mcp/dist/index.js

---

🛠️ Tool Reference (34 Complete Tools)

📦 Workflows (11 Tools)

Tool Name	Description	Key Parameters
list_workflows	List workflows with filtering by status, name, tags	active, tags, name, limit
get_workflow	Get node graph, connections, and settings by ID	id
create_workflow	Create a new workflow graph with nodes	name, nodes, connections, settings, activate
update_workflow	Update workflow graph, nodes, tags, or settings	id, name, nodes, connections, active
delete_workflow	Permanently delete a workflow	id
activate_workflow	Enable auto-trigger execution	id
deactivate_workflow	Pause auto-trigger execution	id
duplicate_workflow	Create an exact copy of a workflow	id, name
export_workflow	Export workflow as formatted JSON structure	id
import_workflow	Import workflow graph from JSON definition	workflowJson, activate
list_common_nodes	Get JSON templates for Webhook, OpenAI, Slack, etc.	category

⚡ Executions (6 Tools)

Tool Name	Description	Key Parameters
list_executions	Search execution logs by status & workflow ID	workflowId, status, limit
get_execution	Inspect node-by-node payload inputs & outputs	id, includeData
delete_execution	Remove an execution record	id
run_workflow	Manually trigger execution with payload	id, data
retry_execution	Retry a failed execution run	id, loadWorkflowFromDb
stop_execution	Stop or cancel an active running execution	id

🔑 Credentials (6 Tools)

Tool Name	Description	Key Parameters
list_credentials	List saved auth credential metadata	name, limit
get_credential	Inspect credential type & dates (secrets masked)	id
create_credential	Save a new credential object	name, type, data
update_credential	Update name, type, or data of a credential	id, name, type, data
delete_credential	Delete a saved credential	id
list_credential_types	Search available credential types (openAiApi, etc.)	search

🌐 Instance Variables (4 Tools)

Tool Name	Description	Key Parameters
list_variables	List custom environment variables	limit
create_variable	Create a key-value instance variable	key, value
update_variable	Update variable key or value	id, key, value
delete_variable	Delete an environment variable	id

🏷️ Tags (4 Tools)

Tool Name	Description	Key Parameters
list_tags	List all workflow tags	limit
create_tag	Create a new tag	name
update_tag	Rename an existing tag	id, name
delete_tag	Delete a tag	id

🛡️ System & Users (3 Tools)

Tool Name	Description	Key Parameters
test_connection	Test connection latency & API authentication	None
list_users	List registered n8n users	limit
get_user	View user profile details by ID	id

---

💡 Example AI Prompts

Try asking Claude or Cursor AI these automation tasks:

"Test connection to my n8n server and report API latency."

"Create an active workflow named 'Daily AI Summary' with a Schedule Trigger running at 9am and an OpenAI node."

"Find all failed executions from today, inspect node errors, and retry the failed run."

"Export workflow ID 'wK82x9L' to a JSON string so I can save it."

"Create an n8n variable named 'ENVIRONMENT' with value 'production'."

---

🔍 Troubleshooting & FAQ

<details> <summary><b>Q: Server output says "N8N_API_KEY environment variable is missing"?</b></summary> <br> Ensure you have created a <code>.env</code> file in the root folder with <code>N8N_API_KEY=your_key</code> or passed the key directly in your <code>claude_desktop_config.json</code> under the <code>env</code> object. </details>

<details> <summary><b>Q: Can I use this with n8n Cloud?</b></summary> <br> Yes! Set <code>N8N_BASE_URL=https://your-instance.app.n8n.cloud</code> and pass your Cloud API key. </details>

<details> <summary><b>Q: How do I test the build locally?</b></summary> <br> Run <code>npm run build</code> followed by <code>npm start</code>. </details>

---

🤝 Contributing

Contributions, feature suggestions, and pull requests are warmly welcome!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

---

<div align="center">

Made with ❤️ by Sohail Shabbir

⭐ Star this repository if you find it helpful!

</div>