{
  "markdown": "# MCP n8n Server\n\n[![npm version](https://img.shields.io/npm/v/mcp-n8n.svg)](https://www.npmjs.com/package/mcp-n8n)\n[![npm downloads](https://img.shields.io/npm/dm/mcp-n8n.svg)](https://www.npmjs.com/package/mcp-n8n)\n[![CI](https://github.com/leonardosepulvedat/mcp-n8n/actions/workflows/ci.yml/badge.svg)](https://github.com/leonardosepulvedat/mcp-n8n/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)\n[![n8n](https://img.shields.io/badge/n8n-compatible-orange.svg)](https://n8n.io)\n\n**Operate and build n8n from Cursor or Claude** — administration of your instance (users, projects, executions, audit) **and** a full builder loop: a catalog of **560 nodes with real parameter schemas** extracted from the official n8n packages, validation before saving, automatic repair, snapshots with rollback and diff, per-node execution debugging, health reports, and full-instance backup.\n\nTwo env vars. Runs on your machine (stdio) or as a remote HTTP server. No hosted account.\n\n---\n\n## 🎯 Token Optimization\n\n**This server is optimized to minimize token consumption**, addressing one of the biggest issues with MCP servers - excessive API token usage.\n\n### What We've Optimized:\n- **90% reduction** in tokens for workflow listing with new `n8n_list_workflows_summary` endpoint\n- **Field filtering** - request only the data you need\n- **Smart defaults** - reduced from 100 to 10-20 results per query\n- **Intelligent warnings** - alerts when operations will consume significant tokens\n\n**See [TOKEN_OPTIMIZATION.md](./TOKEN_OPTIMIZATION.md) for detailed usage guide.**\n\n---\n\n## ✨ Features\n\n### 🔄 Workflow Management\n- **Create & Deploy**: Build workflows with natural language descriptions\n- **CRUD Operations**: Full lifecycle management (Create, Read, Update, Delete)\n- **Activation Control**: Enable/disable workflows on demand\n- **Project Transfer**: Move workflows between projects seamlessly\n- **Tag Management**: Organize workflows with custom tags\n\n### 📊 Execution Monitoring\n- **Real-time Tracking**: Monitor workflow executions with advanced filters\n- **Detailed Insights**: Access full execution data and logs\n- **Error Recovery**: Retry failed executions automatically\n- **Cleanup Tools**: Manage execution history efficiently\n\n### 🔐 Credential Management\n- **Secure Creation**: Add credentials for any service\n- **Schema Discovery**: Auto-discover required fields for credential types\n- **Project Isolation**: Transfer credentials between projects safely\n- **Type Support**: Compatible with all n8n credential types\n\n### 🧱 Workflow Builder\n- **Full node catalog — 560 nodes with real schemas**: extracted directly from `n8n-nodes-base` and `@n8n/n8n-nodes-langchain` (parameters with types, allowed options, display conditions, credentials, latest typeVersion), regenerated weekly by CI. Search with `n8n_search_nodes`, inspect with `n8n_get_node`\n- **Real validation**: `n8n_validate_workflow` checks against the real schemas — nonexistent node types, missing required params (including conditionally required ones), invalid option values, wrong typeVersion, broken connections — *before* save/activate\n- **Expression linting**: detects `{{ }}` expressions missing the `=` prefix and references to nodes that don't exist in the workflow\n- **Automatic repair**: `n8n_autofix_workflow` fixes missing typeVersion/positions, duplicate names, dangling connections and expression prefixes — preview first, apply with a snapshot\n- **Surgical edits**: `n8n_update_workflow_partial` adds/removes nodes and connections without rewriting the whole flow\n- **Public templates**: search and import from n8n.io (`n8n_search_public_templates`, `n8n_import_public_template`) plus 100 bundled templates as a fallback\n- **Guided prompts**: MCP prompts `build-workflow` and `fix-workflow` walk any agent through the full build/validate/test/repair loop\n\n### 🔬 Deep Debugging & Health\n- **Per-node execution data**: `n8n_get_node_execution_data` shows exactly what data flowed through one node (status, item counts, output samples, error details) without downloading the whole execution\n- **Debug loop**: `n8n_debug_last_error` returns the failing node and message from the last error\n- **Health reports**: `n8n_workflow_health` computes success rate, failure count, average duration and last failure per workflow from recent executions, sorted worst-first\n\n### 🛡️ Safety Net & Real Testing\n- **Automatic snapshots**: before every update, partial edit, autofix, or delete, the previous state is saved locally (`~/.mcp-n8n/snapshots`, configurable with `N8N_SNAPSHOT_DIR`)\n- **Rollback**: `n8n_rollback_workflow` restores any snapshot — even recreates a deleted workflow (`recreate=true`)\n- **Diff**: `n8n_diff_workflow_snapshot` compares a snapshot against the current state (nodes added/removed/modified, changed parameters, connection changes) before deciding to roll back\n- **Full-instance backup**: `n8n_export_all_workflows` saves every workflow as JSON files; `n8n_import_workflows` restores them\n- **End-to-end testing**: `n8n_trigger_webhook` calls a Webhook-trigger workflow on the instance and returns the real HTTP response, so the agent can verify the flow actually works\n\n### 🎯 Bundled Templates\n- 100 local starting points with keyword matching, if you prefer not to hit n8n.io\n\n### 🏗️ Organization & Administration\n- **Tags**: Categorize and organize resources\n- **Variables**: Centralized environment variable management\n- **Projects**: Multi-tenant project support\n- **Users & Permissions**: Complete access control management\n- **Audit Logs**: Generate security and compliance reports\n\n---\n\n## 🚀 Quick Start\n\n### Installation via npm (Recommended)\n\nThis is the easiest way to get started:\n\n```bash\nnpm install -g mcp-n8n\n```\n\n### Configuration\n\n1. **Get your n8n API credentials**:\n   - Navigate to your n8n instance → Settings → n8n API\n   - Generate a new API key\n\n2. **Configure Claude Desktop**:\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac/Linux) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n**Option A - Using global installation (if you ran `npm install -g mcp-n8n`):**\n```json\n{\n  \"mcpServers\": {\n    \"n8n\": {\n      \"command\": \"mcp-n8n\",\n      \"env\": {\n        \"N8N_BASE_URL\": \"https://your-n8n-instance.com\",\n        \"N8N_API_KEY\": \"your-api-key-here\",\n        \"N8N_TOOLSETS\": \"all\"\n      }\n    }\n  }\n}\n```\n\n`N8N_TOOLSETS` is optional (`all` by default). Use `core,builder` if you want operations + creation without user/project admin tools. Use `admin` only for instance administration.\n\n### Remote HTTP mode (optional)\n\nBy default the server communicates over stdio (local). To run it as a shared remote server (e.g. in Docker or on a VPS), set a port:\n\n```bash\nN8N_BASE_URL=https://your-n8n-instance.com \\\nN8N_API_KEY=your-api-key \\\nN8N_MCP_HTTP_PORT=3000 \\\nN8N_MCP_HTTP_TOKEN=some-strong-secret \\\nmcp-n8n\n```\n\nThis exposes the MCP protocol over streamable HTTP on port 3000 plus a `GET /health` endpoint. `N8N_MCP_HTTP_TOKEN` is strongly recommended: when set, every request must include `Authorization: Bearer <token>`. Point any MCP client that supports streamable HTTP at `http://your-host:3000` with that header.\n\n**Option B - Using npx (no installation needed, always latest version):**\n```json\n{\n  \"mcpServers\": {\n    \"n8n\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-n8n\"],\n      \"env\": {\n        \"N8N_BASE_URL\": \"https://your-n8n-instance.com\",\n        \"N8N_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n3. **Configure Cursor**:\n\nAdd to Cursor MCP settings (Settings → Extensions → MCP):\n\n**Recommended - Using npx (always uses latest version):**\n```json\n{\n  \"mcpServers\": {\n    \"n8n\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-n8n\"],\n      \"env\": {\n        \"N8N_BASE_URL\": \"https://your-n8n-instance.com\",\n        \"N8N_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n> **Note**: Cursor requires using `npx` for MCP servers. The `-y` flag automatically installs/updates the package without prompting.\n\n**Option C - Docker:**\n\n```bash\ndocker build -t mcp-n8n .\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"n8n\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-e\", \"N8N_BASE_URL\", \"-e\", \"N8N_API_KEY\",\n        \"-v\", \"mcp-n8n-data:/data\",\n        \"mcp-n8n\"\n      ],\n      \"env\": {\n        \"N8N_BASE_URL\": \"https://your-n8n-instance.com\",\n        \"N8N_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\nThe `/data` volume persists workflow snapshots between runs.\n\n4. **Restart Claude Desktop or Cursor**\n\n---\n\n## 💬 Usage Examples\n\nOnce configured, interact with n8n using natural language:\n\n### Creating Workflows\n\n```plaintext\n\"Create a workflow that monitors my Gmail inbox and sends\nSlack notifications for important emails\"\n```\n\n```plaintext\n\"Build a daily report workflow that pulls data from my database,\ngenerates charts, and emails them to my team\"\n```\n\n### Using Templates\n\n```plaintext\n\"I need a WhatsApp chatbot with AI for customer support\"\n→ Automatically creates workflow from \"WhatsApp AI Response Bot\" template\n```\n\n```plaintext\n\"Create an automated stock analysis workflow\"\n→ Uses \"Automated Stock Analysis with GPT-4\" template\n```\n\n### Managing Workflows\n\n```plaintext\n\"Show me all active workflows in the production project\"\n→ Uses n8n_list_workflows_summary for efficient token usage\n```\n\n```plaintext\n\"Show me the details of workflow abc123\"\n→ Uses n8n_get_workflow to fetch complete details only when needed\n```\n\n```plaintext\n\"Deactivate the 'Daily Backup' workflow\"\n```\n\n```plaintext\n\"What went wrong with execution abc123?\"\n```\n\n### Monitoring & Debugging\n\n```plaintext\n\"Show me the last 10 failed executions\"\n```\n\n```plaintext\n\"Retry all failed executions from workflow xyz456\"\n```\n\n```plaintext\n\"Delete all successful executions older than 30 days\"\n```\n\n---\n\n## 🛠️ Available Tools\n\n<details>\n<summary><strong>Workflows</strong></summary>\n\n- `n8n_create_workflow` - Create new workflows (validate first)\n- `n8n_list_workflows_summary` - Token-efficient listing\n- `n8n_list_workflows` - Full details with optional field filtering\n- `n8n_get_workflow` - Full workflow JSON\n- `n8n_update_workflow` - Replace fields (omitted fields keep current values)\n- `n8n_update_workflow_partial` - Surgical edits: add/remove nodes and connections\n- `n8n_delete_workflow` - Remove workflows permanently\n- `n8n_activate_workflow` / `n8n_deactivate_workflow`\n- `n8n_transfer_workflow` / tags tools\n\n</details>\n\n<details>\n<summary><strong>Safety & Testing</strong></summary>\n\n- `n8n_list_workflow_snapshots` - Local history of every change made through this server\n- `n8n_rollback_workflow` - Restore a previous version, or recreate a deleted workflow\n- `n8n_diff_workflow_snapshot` - Compare a snapshot against the current state before rolling back\n- `n8n_trigger_webhook` - Call a webhook workflow and get the real response\n- `n8n_export_all_workflows` / `n8n_import_workflows` - Full-instance backup and restore\n\n</details>\n\n<details>\n<summary><strong>Builder</strong></summary>\n\n- `n8n_search_nodes` / `n8n_get_node` - Full catalog: 560 nodes with real parameter schemas\n- `n8n_validate_workflow` - Check JSON against real schemas before save/activate\n- `n8n_autofix_workflow` - Mechanical repairs: typeVersion, positions, duplicates, dangling connections, expression prefixes\n- `n8n_search_public_templates` / `n8n_import_public_template` - Official n8n.io library\n- `n8n_list_workflow_templates` / `n8n_get_workflow_template` / `n8n_create_workflow_from_template` - Bundled templates\n\n**100 Included Templates across 13 categories**:\n- E-commerce: Shopify automation, WooCommerce support agents\n- Social Media: Instagram, TikTok, LinkedIn, Twitter automation\n- AI/Chat: Chatbots, AI agents, voice assistants\n- Communication: WhatsApp, Telegram, Email automation\n- Content: Blog automation, video generation, SEO optimization\n- HR/Recruitment: Resume screening, candidate sourcing\n- Sales/CRM: Lead generation, cold calling pipelines\n- Finance: Stock analysis, invoice extraction\n- Data Scraping: Google Maps, LinkedIn, Amazon, TikTok\n- Monitoring: Website uptime, competitor tracking\n- Productivity: Calendar, Notion, scheduling automation\n\n</details>\n\n<details>\n<summary><strong>Executions (4 tools)</strong></summary>\n\n- `n8n_list_executions` - Filter by status, workflow, project\n- `n8n_get_execution` - Detailed execution data\n- `n8n_delete_execution` - Remove execution records\n- `n8n_retry_execution` - Retry failed executions\n- `n8n_debug_last_error` - Failing node + message from the last error\n- `n8n_get_node_execution_data` - Data that flowed through one specific node\n- `n8n_workflow_health` - Success rate, failures and duration per workflow\n\n</details>\n\n<details>\n<summary><strong>Credentials (4 tools)</strong></summary>\n\n- `n8n_create_credential` - Add new credentials\n- `n8n_delete_credential` - Remove credentials (owner only)\n- `n8n_get_credential_schema` - Discover required fields\n- `n8n_transfer_credential` - Move between projects\n\n</details>\n\n<details>\n<summary><strong>Organization (19 tools)</strong></summary>\n\n**Tags**: Create, list, get, update, delete\n**Variables**: Create, list, update, delete\n**Users**: List, create, get, delete, change role\n**Projects**: Create, list, update, delete, manage users\n\n</details>\n\n<details>\n<summary><strong>Advanced (2 tools)</strong></summary>\n\n- `n8n_generate_audit` - Security audit reports\n- `n8n_pull_source_control` - Version control integration\n\n</details>\n\n**61 tools** by default (`N8N_TOOLSETS=all`). `core,builder` exposes 28. Plus 2 MCP prompts (`build-workflow`, `fix-workflow`).\n\n---\n\n## 📚 Documentation\n\n- **[Quick Start Guide](QUICKSTART.md)** - Get up and running in 5 minutes\n- **[Examples & Use Cases](EXAMPLES.md)** - Real-world automation examples\n- **[Node Reference](NODE_REFERENCE.md)** - Detailed tool documentation\n- **[Changelog](CHANGELOG.md)** - Version history and updates\n\n---\n\n## 🏗️ Project Structure\n\n```\nmcp-n8n/\n├── src/\n│   ├── index.ts          # MCP server implementation\n│   ├── n8n-client.ts     # n8n API client\n│   └── types.ts          # TypeScript definitions\n├── examples/\n│   ├── templates-metadata.json\n│   └── *.json            # Pre-built workflow templates\n├── dist/                 # Compiled output\n├── QUICKSTART.md         # Quick start guide\n├── EXAMPLES.md           # Usage examples\n├── NODE_REFERENCE.md     # API documentation\n└── package.json\n```\n\n---\n\n## 🔧 Development\n\n### Local Installation (For Development)\n\nIf you want to contribute or test local changes:\n\n#### 1. Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/leonardosepulvedat/mcp-n8n.git\ncd mcp-n8n\n\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Development with auto-rebuild\nnpm run watch\n```\n\n#### 2. Configure with Local Build\n\n**For Claude Desktop**, add to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"n8n\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/mcp-n8n/dist/index.js\"],\n      \"env\": {\n        \"N8N_BASE_URL\": \"https://your-n8n-instance.com\",\n        \"N8N_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n**For Cursor**, add to MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"n8n\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/mcp-n8n/dist/index.js\"],\n      \"env\": {\n        \"N8N_BASE_URL\": \"https://your-n8n-instance.com\",\n        \"N8N_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n**Important**: Replace `/absolute/path/to/mcp-n8n/` with the actual absolute path to your cloned repository (e.g., `/Users/yourname/projects/mcp-n8n/`).\n\n#### 3. Testing\n\n```bash\n# Set environment variables\ncp .env.example .env\n# Edit .env with your credentials\n\n# Build and test\nnpm run build\nnode dist/index.js\n```\n\n---\n\n## How to Run\n\nTo run the main script, execute:\n\n```bash\npython main.py\n```\n\n## How to Test\n\nTo run the tests, execute:\n\n```bash\npytest test_main.py\n```\n\n---\n\n## 📋 Requirements\n\n- **Node.js**: 20 or higher\n- **n8n Instance**: Self-hosted or n8n Cloud (paid plan)\n- **n8n API Key**: Required for authentication\n- **AI IDE**: Claude Desktop or Cursor with MCP support\n\n### n8n Requirements\n\n- **Self-hosted**: Full API access ✅\n- **n8n Cloud**: Requires paid plan for API access\n- **Version**: Compatible with n8n v1.0.0+\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n---\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- **[n8n](https://n8n.io)** - The workflow automation platform\n- **[Anthropic](https://anthropic.com)** - Claude and Model Context Protocol\n- **[Cursor](https://cursor.sh)** - AI-powered code editor\n\n---\n\n## 🔗 Resources\n\n- [n8n API Documentation](https://docs.n8n.io/api/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [n8n Community](https://community.n8n.io/)\n- [MCP Servers Registry](https://github.com/modelcontextprotocol/servers)\n\n---\n\n## ⚠️ Important Notes\n\n### API Access\n- n8n Cloud requires a **paid plan** to access the API\n- Self-hosted n8n has **full API access** on all plans\n- Some operations require **owner/admin permissions**\n\n### Security\n- Never commit `.env` files with credentials\n- Use environment variables for sensitive data\n- API keys grant full access to your n8n instance\n- Regularly rotate API keys for security\n\n### Rate Limiting\n- Respect n8n API rate limits\n- Use pagination for large result sets\n- Implement error handling for rate limit responses\n\n---\n\n## 🐛 Troubleshooting\n\n### Connection Issues\n\n**Problem**: \"Cannot connect to n8n API\"\n- Verify `N8N_BASE_URL` is correct and accessible\n- Check that API key is valid\n- Ensure n8n instance is running\n\n### Permission Errors\n\n**Problem**: \"Insufficient permissions\"\n- Some operations require owner/admin role\n- Verify your user has appropriate permissions\n- Check project-level access rights\n\n### Template Issues\n\n**Problem**: \"Template not found\"\n- Ensure `examples/` directory is present\n- Verify `templates-metadata.json` exists\n- Check template file references are correct\n\n---\n\n## 💡 Tips & Best Practices\n\n1. **Start with Templates**: Use pre-built templates as starting points\n2. **Use Tags**: Organize workflows with tags for easy management\n3. **Monitor Executions**: Regularly check failed executions\n4. **Clean Up**: Remove old execution data to save space\n5. **Version Control**: Use n8n's built-in version control features\n6. **Test First**: Test workflows before activating in production\n\n---\n\n## 📧 Support\n\n- **Issues**: [GitHub Issues](https://github.com/leonardosepulvedat/mcp-n8n/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/leonardosepulvedat/mcp-n8n/discussions)\n- **n8n Community**: [community.n8n.io](https://community.n8n.io/)\n\n---\n\n<div align=\"center\">\n\n**[⬆ Back to Top](#mcp-n8n-server)**\n\n\n</div>\n",
  "bytes": 19354,
  "sha": "b9577356ecf0c8229c6fc6aaa8edd284a86410ae69328b7265dba2f9c1974ef5",
  "repo_slug": "leonardosepulvedat/mcp-n8n",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_leonardosepulvedat_mcp_n8n_55882ee9/readme"
}