n8n-mcp-tools-expert

n8n-mcp-tools-expert 是一份用于高效使用 n8n-mcp MCP 服务器工具来构建工作流的专家指南。

工具类别 n8n-mcp 提供 40 多个工具，按类别组织：节点发现（SEARCH_GUIDE.md）、配置验证（VALIDATION_GUIDE.md）、工作流管理（WORKFLOW_GUIDE.md）、模板库（可搜索并访问 2,653 个真实工作流）、文档（获取工具与节点文档）。

快速参考（按成功率的常用工具）

• search_nodes：按关键词查找节点，成功率 99.9%，<20ms。
• get_node_essentials：理解节点操作，成功率 91.7%，<10ms。
• validate_node_operation：检查配置，速度 <100ms，成功率因情况而异。
• n8n_create_workflow：创建工作流，成功率 96.8%，100-500ms。
• n8n_update_partial_workflow：编辑工作流（最常用），成功率 99.0%，50-200ms。
• validate_workflow：检查完整工作流，成功率 95.5%，100-500ms。

工具选择指南 查找合适节点：search_nodes({query: "keyword"}) → get_node_essentials({nodeType: "nodes-base.name"}) →（可选）get_node_documentation({nodeType: "nodes-base.name"})。常见模式：search → essentials（平均间隔 18 秒）。

验证配置：validate_node_minimal({nodeType, config: {}}) 检查必填字段 → validate_node_operation({nodeType, config, profile: "runtime"}) 完整验证 → 修复错误后再次验证。常见模式：验证 → 修复 → 验证（每轮约 23 秒思考、58 秒修复）。

管理工作流：n8n_create_workflow({name, nodes, connections}) → n8n_validate_workflow({id}) → n8n_update_partial_workflow({id, operations: [...]}) → 再次 n8n_validate_workflow({id})。常见模式：迭代更新（编辑之间平均 56 秒）。

关键：nodeType 格式 搜索/验证类工具使用短前缀："nodes-base.slack"、"nodes-base.httpRequest"、"nodes-base.webhook"、"nodes-langchain.agent"。 工作流类工具使用完整前缀："n8n-nodes-base.slack"、"n8n-nodes-base.httpRequest"、"n8n-nodes-base.webhook"、"@n8n/n8n-nodes-langchain.agent"。 search_nodes 会同时返回两种格式：nodeType（供搜索/验证工具）与 workflowNodeType（供工作流工具）。

常见错误

1. nodeType 格式错误会导致 "Node not found"。应使用 get_node_essentials({nodeType: "nodes-base.slack"})。
2. 用 get_node_info 代替 get_node_essentials 会带来 20% 失败率、响应慢和超大载荷（100KB+）；get_node_essentials 返回约 5KB 聚焦数据，成功率 91.7%，<10ms。仅在调试复杂配置、需要完整属性 schema 或探索高级功能时使用 get_node_info。
3. 不使用验证 profile：minimal 只校验必填字段（快、宽松）；runtime 校验值+类型（推荐上线前）；ai-friendly 减少误报（AI 配置用）；strict 最大验证（生产用）。建议显式指定 profile: "runtime"。
4. 忽略自动清理：任何工作流更新都会对所有节点执行清理，自动修复二元运算符（equals、contains，移除 singleValue）、一元运算符（isEmpty、isNotEmpty，添加 singleValue: true）以及 IF/Switch 节点缺失的元数据；无法修复断开的连接、分支数量不匹配、自相矛盾的损坏状态。
5. 不使用智能参数：多输出节点可用语义化参数替代 sourceIndex，如 branch: "true"/"false"（IF 节点）、case: 0（Switch 节点）。

工具使用模式 模式 1 节点发现（最常见，步骤间平均 18 秒）：search_nodes({query: "slack", mode: "OR", limit: 20}) → get_node_essentials({nodeType: "nodes-base.slack", includeExamples: true}) 获取操作、属性、元数据。 模式 2 验证循环（典型周期 23 秒思考、58 秒修复）：validate_node_operation({nodeType, config, profile: "runtime"}) → 检查错误 → 修复配置 → 再次验证，循环直至通过。 模式 3 工作流编辑（最常用更新工具，成功率 99.0%，编辑间隔平均 56 秒）：迭代式构建，n8n_update_partial_workflow 添加节点、添加连接，再用 n8n_validate_workflow 验证。

模板使用 search_templates({query: "webhook slack", limit: 20}) 返回约 1,085 个带元数据的模板；get_template({templateId: 2947, mode: "structure" 或 "full"}) 获取模板详情。模板元数据包含复杂度（simple、medium、complex）、预估设置时间、所需服务、类别与用例、浏览量（热度）。

自助工具 tools_documentation() 列出所有工具，tools_documentation({topic: "search_nodes", depth: "full"}) 查看特定工具详情；n8n_health_check() 检查 MCP 服务器连通性（返回状态、功能、API 可用性、版本）；get_database_statistics() 返回 537 个节点、270 个 AI 工具、2,653 个模板。

工具可用性 始终可用（无需 n8n API）：search_nodes、list_nodes、get_node_essentials、validate_node_minimal、validate_node_operation、validate_workflow、get_property_dependencies、search_templates、get_template、list_tasks、tools_documentation、get_database_statistics。 需要 n8n API（N8N_API_URL + N8N_API_KEY）：n8n_create_workflow、n8n_update_partial_workflow、n8n_validate_workflow（按 ID）、n8n_list_workflows、n8n_get_workflow、n8n_trigger_webhook_workflow。若 API 工具不可用，可使用模板和仅验证工作流。

性能特征

• search_nodes：<20ms，小载荷，99.9%。
• list_nodes：<20ms，小载荷，99.6%。
• get_node_essentials：<10ms，约 5KB，91.7%。
• get_node_info：时延不定，100KB+，80%。
• validate_node_minimal：<100ms，小载荷，97.4%。
• validate_node_operation：<100ms，中载荷，成功率不定。
• validate_workflow：100-500ms，中载荷，95.5%。
• n8n_create_workflow：100-500ms，中载荷，96.8%。
• n8n_update_partial_workflow：50-200ms，小载荷，99.0%。

最佳实践 建议：优先用 get_node_essentials 而非 get_node_info；显式指定验证 profile；使用智能参数（branch、case）；遵循 search → essentials → validate 流程；迭代式构建工作流（编辑间隔平均 56 秒）；每次重大修改后验证；用 includeExamples: true 获取真实配置。 避免：非必要使用 get_node_info（20% 失败率）；忘记 nodeType 前缀（nodes-base.）；跳过验证 profile（建议用 runtime）；试图一次构建完成（应迭代）；忽略自动清理行为；在搜索工具中使用完整前缀（n8n-nodes-base.）。

核心流程 search_nodes 查找节点 → get_node_essentials 理解配置 → validate_node_operation 检查配置 → n8n_create_workflow 构建 → n8n_validate_workflow 验证 → n8n_update_partial_workflow 迭代。

详细说明见 SEARCH_GUIDE.md（节点发现）、VALIDATION_GUIDE.md（配置验证）、WORKFLOW_GUIDE.md（工作流管理）。相关技能包括：n8n 表达式语法、n8n 工作流模式、n8n 验证专家、n8n 节点配置。