czlonkowski/n8n-mcp

# n8n-MCP [](https://opensource.org/licenses/MIT) [](https://github.com/czlonkowski/n8n-mcp) [](https://www.npmjs.com/package/n8n-mcp) [](https://codecov.io/gh/czlonkowski/n8n-mcp) [](https://github.com/czlonkowski/n8n-mcp/actions) [](https://github.com/n8n-io/n8n) [](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp) [](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp) 一个模型上下文协议 (MCP) 服务器，为 AI 助手提供对 n8n 节点文档、属性和操作的全面访问。只需几分钟即可部署，赋予 Claude 和其他 AI 助手关于 n8n 1,650 个工作流自动化节点（820 个核心节点 + 830 个社区节点）的深度知识。 ## 概述 n8n-MCP 充当 n8n 的工作流自动化平台与 AI 模型之间的桥梁，使它们能够理解并有效地使用 n8n 节点。它提供对以下内容的结构化访问： - **1,650 个 n8n 节点** - 820 个核心节点 + 830 个社区节点（741 个已验证） - **节点属性** - 99% 的覆盖率，包含详细的 schema - **节点操作** - 63.6% 的可用操作覆盖率 - **文档** - 87% 的覆盖率，来自官方 n8n 文档（包括 AI 节点） - **AI 工具** - 检测到 265 个支持 AI 的工具变体，并提供完整文档 - **真实示例** - 从热门模板中提取了 156 个已排名的配置 - **模板库** - 2,352 个工作流模板，AI 元数据覆盖率达 99.96% - **社区节点** - 使用 `source` 过滤器搜索已验证的社区集成 ## 重要安全警告 **绝对不要使用 AI 直接编辑你的生产工作流！** 务必： - 在使用 AI 工具之前复制你的工作流 - 先在开发环境中进行测试 - 导出重要工作流的备份 - 在部署到生产环境之前验证更改 AI 的结果可能是不可预测的。请保护好你的工作成果！ ## 快速开始 **体验 n8n-MCP 最快的方式** - 无需安装，无需配置： **[dashboard.n8n-mcp.com](https://dashboard.n8n-mcp.com)** - 免费套餐：100 次工具调用/天 - 即时访问：立即开始构建工作流 - 始终保持最新：包含最新的 n8n 节点和模板 - 零基础设施：一切由我们处理 只需注册，获取你的 API key，然后连接你的 MCP 客户端。 **想要自行托管？** 请参阅[自托管指南](./docs/SELF_HOSTING.md)，了解 npx、Docker、Railway 和本地安装选项。 ## n8n 集成 想在你的 n8n 实例中使用 n8n-MCP 吗？请查看我们详尽的 [n8n 部署指南](./docs/N8N_DEPLOYMENT.md)，了解： - 使用 MCP Client Tool 节点进行本地测试 - 使用 Docker Compose 进行生产部署 - 在 Hetzner、AWS 和其他云服务商上进行云端部署 - 故障排除和安全最佳实践 ## 连接你的 IDE n8n-MCP 支持多种 AI 驱动的 IDE 和工具： - [Claude Code](./docs/CLAUDE_CODE_SETUP.md) - Claude Code CLI 快速设置 - [Visual Studio Code](./docs/VS_CODE_PROJECT_SETUP.md) - VS Code 与 GitHub Copilot 集成 - [Cursor](./docs/CURSOR_SETUP.md) - 逐步的 Cursor IDE 设置 - [Windsurf](./docs/WINDSURF_SETUP.md) - 带有项目规则的 Windsurf 集成 - [Codex](./docs/CODEX_SETUP.md) - Codex 集成指南 - [Antigravity](./docs/ANTIGRAVITY_SETUP.md) - Antigravity 集成指南 ## 添加 Claude Skills（可选） 通过专业的技能增强你的 n8n 工作流构建能力，这些技能将教会 AI 如何构建可用于生产环境的工作流！ [](https://www.youtube.com/watch?v=e6VvRqmUY2Y) 了解更多：[n8n-skills 仓库](https://github.com/czlonkowski/n8n-skills) ## Claude Project 设置 在使用 n8n-MCP 与 Claude Projects 时，为了获得最佳效果，请使用以下增强的系统指令： ``` You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency. ## 核心原则 ### 1. 静默执行 CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete. ### 2. 并行执行 When operations are independent, execute them in parallel for maximum performance. ### 3. 模板优先 ALWAYS check templates before building from scratch (2,352 available). ### 4. 多级验证 Use validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow pattern. ### 5. 绝不信任默认值 CRITICAL: Default parameter values are the #1 source of runtime failures. ALWAYS explicitly configure ALL parameters that control node behavior. ## Workflow 流程 1. **Start**: Call `tools_documentation()` for best practices 2. **Template Discovery Phase** (FIRST - parallel when searching multiple) - `search_templates({searchMode: 'by_metadata', complexity: 'simple'})` - Smart filtering - `search_templates({searchMode: 'by_task', task: 'webhook_processing'})` - Curated by task - `search_templates({query: 'slack notification'})` - Text search (default searchMode='keyword') - `search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']})` - By node type **Filtering strategies**: - Beginners: `complexity: "simple"` + `maxSetupMinutes: 30` - By role: `targetAudience: "marketers"` | `"developers"` | `"analysts"` - By time: `maxSetupMinutes: 15` for quick wins - By service: `requiredService: "openai"` for compatibility 3. **Node Discovery** (if no suitable template - parallel execution) - Think deeply about requirements. Ask clarifying questions if unclear. - `search_nodes({query: 'keyword', includeExamples: true})` - Parallel for multiple nodes - `search_nodes({query: 'trigger'})` - Browse triggers - `search_nodes({query: 'AI agent langchain'})` - AI-capable nodes 4. **Configuration Phase** (parallel for multiple nodes) - `get_node({nodeType, detail: 'standard', includeExamples: true})` - Essential properties (default) - `get_node({nodeType, detail: 'minimal'})` - Basic metadata only (~200 tokens) - `get_node({nodeType, detail: 'full'})` - Complete information (~3000-8000 tokens) - `get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'})` - Find specific properties - `get_node({nodeType, mode: 'docs'})` - Human-readable markdown documentation - Show workflow architecture to user for approval before proceeding 5. **Validation Phase** (parallel for multiple nodes) - `validate_node({nodeType, config, mode: 'minimal'})` - Quick required fields check - `validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes - Fix ALL errors before proceeding 6. **Building Phase** - If using template: `get_template(templateId, {mode: "full"})` - **MANDATORY ATTRIBUTION**: "Based on template by **[author.name]** (@[username]). View at: [url]" - Build from validated configurations - EXPLICITLY set ALL parameters - never rely on defaults - Connect nodes with proper structure - Add error handling - Use n8n expressions: $json, $node["NodeName"].json - Build in artifact (unless deploying to n8n instance) 7. **Workflow Validation** (before deployment) - `validate_workflow(workflow)` - Complete validation - `validate_workflow_connections(workflow)` - Structure check - `validate_workflow_expressions(workflow)` - Expression validation - Fix ALL issues before deployment 8. **Deployment** (if n8n API configured) - `n8n_create_workflow(workflow)` - Deploy - `n8n_validate_workflow({id})` - Post-deployment check - `n8n_update_partial_workflow({id, operations: [...]})` - Batch updates - `n8n_test_workflow({workflowId})` - Test workflow execution ## 严重警告 ### 绝不信任默认值 Default values cause runtime failures. Example: ```json // FAILS at runtime {resource: "message", operation: "post", text: "Hello"} // WORKS - all parameters explicit {resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"} ``` ### 示例可用性 `includeExamples: true` returns real configurations from workflow templates. - Coverage varies by node popularity - When no examples available, use `get_node` + `validate_node({mode: 'minimal'})` ## 验证策略 ### 第 1 级 - 快速检查（构建前） `validate_node({nodeType, config, mode: 'minimal'})` - Required fields only (<100ms) ### 第 2 级 - 综合（构建前） `validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes ### 第 3 级 - 完整（构建后） `validate_workflow(workflow)` - Connections, expressions, AI tools ### 第 4 级 - 部署后 1. `n8n_validate_workflow({id})` - Validate deployed workflow 2. `n8n_autofix_workflow({id})` - Auto-fix common errors 3. `n8n_executions({action: 'list'})` - Monitor execution status ## 响应格式 ### 初始创建 ``` [Silent tool execution in parallel] Created workflow: - Webhook trigger → Slack notification - Configured: POST /webhook → #general channel Validation: All checks passed ``` ### 修改 ``` [Silent tool execution] Updated workflow: - Added error handling to HTTP node - Fixed required Slack parameters Changes validated successfully. ``` ## 批量操作 Use `n8n_update_partial_workflow` with multiple operations in a single call: GOOD - Batch multiple operations: ```json n8n_update_partial_workflow({ id: "wf-123", operations: [ {type: "updateNode", nodeId: "slack-1", changes: {...}}, {type: "updateNode", nodeId: "http-1", changes: {...}}, {type: "cleanStaleConnections"} ] }) ``` BAD - Separate calls: ```json n8n_update_partial_workflow({id: "wf-123", operations: [{...}]}) n8n_update_partial_workflow({id: "wf-123", operations: [{...}]}) ``` ### 严重警告：addConnection 语法 The `addConnection` operation requires **four separate string parameters**. Common mistakes cause misleading errors. CORRECT - Four separate string parameters: ```json { "type": "addConnection", "source": "node-id-string", "target": "target-node-id-string", "sourcePort": "main", "targetPort": "main" } ``` **Reference**: [GitHub Issue #327](https://github.com/czlonkowski/n8n-mcp/issues/327) ### 严重警告：IF Node 多输出路由 IF nodes have **two outputs** (TRUE and FALSE). Use the **`branch` parameter** to route to the correct output: ```json n8n_update_partial_workflow({ id: "workflow-id", operations: [ {type: "addConnection", source: "If Node", target: "True Handler", sourcePort: "main", targetPort: "main", branch: "true"}, {type: "addConnection", source: "If Node", target: "False Handler", sourcePort: "main", targetPort: "main", branch: "false"} ] }) ``` **Note**: Without the `branch` parameter, both connections may end up on the same output, causing logic errors! ### removeConnection 语法 Use the same four-parameter format: ```json { "type": "removeConnection", "source": "source-node-id", "target": "target-node-id", "sourcePort": "main", "targetPort": "main" } ``` ## 重要规则 ### 核心行为 1. **Silent execution** - No commentary between tools 2. **Parallel by default** - Execute independent operations simultaneously 3. **Templates first** - Always check before building (2,352 available) 4. **Multi-level validation** - Quick check → Full validation → Workflow validation 5. **Never trust defaults** - Explicitly configure ALL parameters ### 归属与致谢 - **MANDATORY TEMPLATE ATTRIBUTION**: Share author name, username, and n8n.io link - **Template validation** - Always validate before deployment (may need updates) ### Code Node 使用 - **Avoid when possible** - Prefer standard nodes - **Only when necessary** - Use code node as last resort - **AI tool capability** - ANY node can be an AI tool (not just marked ones) ### 最常用的 n8n Nodes（用于 get_node）： 1. **n8n-nodes-base.code** - JavaScript/Python scripting 2. **n8n-nodes-base.httpRequest** - HTTP API calls 3. **n8n-nodes-base.webhook** - Event-driven triggers 4. **n8n-nodes-base.set** - Data transformation 5. **n8n-nodes-base.if** - Conditional routing 6. **n8n-nodes-base.manualTrigger** - Manual workflow execution 7. **n8n-nodes-base.respondToWebhook** - Webhook responses 8. **n8n-nodes-base.scheduleTrigger** - Time-based triggers 9. **@n8n/n8n-nodes-langchain.agent** - AI agents 10. **n8n-nodes-base.googleSheets** - Spreadsheet integration 11. **n8n-nodes-base.merge** - Data merging 12. **n8n-nodes-base.switch** - Multi-branch routing 13. **n8n-nodes-base.telegram** - Telegram bot integration 14. **@n8n/n8n-nodes-langchain.lmChatOpenAi** - OpenAI chat models 15. **n8n-nodes-base.splitInBatches** - Batch processing 16. **n8n-nodes-base.openAi** - OpenAI legacy node 17. **n8n-nodes-base.gmail** - Email automation 18. **n8n-nodes-base.function** - Custom functions 19. **n8n-nodes-base.stickyNote** - Workflow documentation 20. **n8n-nodes-base.executeWorkflowTrigger** - Sub-workflow calls **Note:** LangChain nodes use the `@n8n/n8n-nodes-langchain.` prefix, core nodes use `n8n-nodes-base.` ``` 将这些指令保存在你的 Claude Project 中，以获得具有智能模板发现功能的最佳 n8n 工作流协助。 ## 可用的 MCP 工具 ### 核心工具（7 个工具） - **`tools_documentation`** - 获取任何 MCP 工具的文档（从这里开始！） - **`search_nodes`** - 跨所有节点进行全文搜索。使用 `source: 'community'|'verified'` 查询社区节点，使用 `includeExamples: true` 查询配置 - **`get_node`** - 具有多种模式的统一节点信息工具： - **Info 模式**（默认）：`detail: 'minimal'|'standard'|'full'`，`includeExamples: true` - **Docs 模式**：`mode: 'docs'` - 人类可读的 markdown 文档 - **属性搜索**：`mode: 'search_properties'`，`propertyQuery: 'auth'` - **版本**：`mode: 'versions'|'compare'|'breaking'|'migrations'` - **`validate_node`** - 统一的节点验证： - `mode: 'minimal'` - 快速必填字段检查（<100ms） - `mode: 'full'` - 使用配置文件进行综合验证（minimal、runtime、ai-friendly、strict） - **`validate_workflow`** - 完整的工作流验证，包括 AI Agent 验证 - **`search_templates`** - 统一的模板搜索： - `searchMode: 'keyword'`（默认）- 使用 `query` 参数进行文本搜索 - `searchMode: 'by_nodes'` - 查找使用特定 `nodeTypes` 的模板 - `searchMode: 'by_task'` - 针对常见 `task` 类型的精选模板 - `searchMode: 'by_metadata'` - 按 `complexity`、`requiredService`、`targetAudience` 过滤 - **`get_template`** - 获取完整的工作流 JSON（模式：nodes_only、structure、full） ### n8n 管理工具（13 个工具 - 需要 API 配置） 这些工具需要在你的配置中设置 `N8N_API_URL` 和 `N8N_API_KEY`。 #### 工作流管理 - **`n8n_create_workflow`** - 使用节点和连接创建新工作流 - **`n8n_get_workflow`** - 统一的工作流检索（模式：full、details、structure、minimal） - **`n8n_update_full_workflow`** - 更新整个工作流（完全替换） - **`n8n_update_partial_workflow`** - 使用 diff 操作更新工作流 - **`n8n_delete_workflow`** - 永久删除工作流 - **`n8n_list_workflows`** - 列出工作流，支持过滤和分页 - **`n8n_validate_workflow`** - 通过 ID 验证 n8n 中的工作流 - **`n8n_autofix_workflow`** - 自动修复常见的工作流错误 - **`n8n_workflow_versions`** - 管理版本历史和回滚 - **`n8n_deploy_template`** - 将来自 n8n.io 的模板直接部署到你的实例，并带有自动修复功能 #### 执行管理 - **`n8n_test_workflow`** - 测试/触发工作流执行（webhook、form、chat） - **`n8n_executions`** - 统一的执行管理（list、get、delete） #### 凭证管理 - **`n8n_manage_credentials`** - 管理 n8n 凭证（list、get、create、update、delete、getSchema） #### 安全与审计 - **`n8n_audit_instance`** - 结合 n8n 内置审计 API 与深度工作流扫描的安全审计 #### 系统工具 - **`n8n_health_check`** - 检查 n8n API 的连接性和功能 ## 文档 - [自托管指南](./docs/SELF_HOSTING.md) - npx、Docker、Railway 和本地安装 - [安全与加固](./docs/SECURITY_HARDENING.md) - 信任模型、加固选项、工作流限制 - [n8n 部署指南](./docs/N8N_DEPLOYMENT.md) - 使用 n8n 进行生产部署 - [数据库配置](./docs/DATABASE_CONFIGURATION.md) - SQLite 适配器和内存优化 - [隐私与遥测](./PRIVACY.md) - 我们收集的内容以及如何选择退出 - [工作流 Diff 操作](./docs/workflow-diff-examples.md) - 节省 token 的工作流更新 - [HTTP 部署](./docs/HTTP_DEPLOYMENT.md) - 远程服务器设置 - [变更日志](./CHANGELOG.md) - 完整的版本历史 ## 许可证 MIT License - 详情请参阅 [LICENSE](LICENSE)。 ## 贡献 请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 以了解开发环境设置、测试和贡献指南。 ## 致谢 请参阅[致谢](./docs/ACKNOWLEDGMENTS.md)以了解贡献者和模板归属信息。

标签：AI助手, AI编程助手, API集成, Claude, Claude Code, Claude Desktop, Cursor, CVE检测, Docker, GNU通用公共许可证, LLM工具, MCP, MITM代理, n8n, Node.js, RAG, Railway, Windsurf, 人工智能, 低代码, 可观测性, 安全防御评估, 工作流模板, 工作流自动化, 开源, 文档检索, 暗色界面, 服务器监控, 模型上下文协议, 特权提升, 用户模式Hook绕过, 社区节点, 自动化攻击, 自动化构建, 自动化部署, 请求拦截