n8n-mcp-tools-expert

n8n MCP 工具专家

使用 n8n-mcp MCP 服务器工具构建工作流的主指南。

---

工具分类

n8n-mcp 提供的工具按类别组织：

1. 节点发现 → SEARCH_GUIDE.md
2. 配置验证 → VALIDATION_GUIDE.md
3. 工作流管理 → WORKFLOW_GUIDE.md
4. 模板库 - 搜索和部署 2700+ 真实工作流
5. 数据表 - 管理 n8n 数据表和行 (n8n_manage_datatable)
6. 凭据管理 - 完整的凭据 CRUD + 模式发现 (n8n_manage_credentials)
7. 安全与审计 - 实例安全审计，支持自定义深度扫描 (n8n_audit_instance)
8. 文档与指南 - 工具文档、AI 代理指南、代码节点指南

---

快速参考

最常用工具（按成功率排序）

工具	使用场景	速度
search_nodes	按关键词查找节点	<20ms
get_node	了解节点操作（detail="standard"）	<10ms
validate_node	检查配置（mode="full"）	<100ms
n8n_create_workflow	创建工作流	100-500ms
n8n_update_partial_workflow	编辑工作流（最常用！）	50-200ms
validate_workflow	检查完整工作流	100-500ms
n8n_deploy_template	将模板部署到 n8n 实例	200-500ms
n8n_manage_datatable	管理数据表和行	50-500ms
n8n_manage_credentials	凭据 CRUD + 模式发现	50-500ms
n8n_audit_instance	安全审计（内置 + 自定义扫描）	500-5000ms
n8n_autofix_workflow	自动修复验证错误	200-1500ms

---

工具选择指南

查找合适的节点

工作流：

1. search_nodes({query: "关键词"})
2. get_node({nodeType: "nodes-base.名称"})
3. [可选] get_node({nodeType: "nodes-base.名称", mode: "docs"})

示例：

// 步骤 1：搜索
search_nodes({query: "slack"})
// 返回：nodes-base.slack

// 步骤 2：获取详情
get_node({nodeType: "nodes-base.slack"})
// 返回：操作、属性、示例（标准详情）

// 步骤 3：获取可读文档
get_node({nodeType: "nodes-base.slack", mode: "docs"})
// 返回：markdown 文档

常见模式：search → get_node（平均 18 秒）

验证配置

工作流：

1. validate_node({nodeType, config: {}, mode: "minimal"}) - 检查必填字段
2. validate_node({nodeType, config, profile: "runtime"}) - 完整验证
3. [重复] 修复错误，再次验证

常见模式：validate → fix → validate（每个周期思考 23 秒，修复 58 秒）

管理工作流

工作流：

1. n8n_create_workflow({name, nodes, connections})
2. n8n_validate_workflow({id})
3. n8n_update_partial_workflow({id, operations: [...]})
4. n8n_validate_workflow({id}) 再次
5. n8n_update_partial_workflow({id, operations: [{type: "activateWorkflow"}]})

常见模式：迭代更新（平均每次编辑间隔 56 秒）

关键：创建工作流时的节点 JSON 规范

生成的节点 JSON 中的三个结构错误会破坏 n8n UI，即使工作流验证通过：

1. 切勿发出带有占位符 ID 的 credentials 块。 像 "id": "REPLACE_ME" 这样的假 ID 会使凭据选择器永久禁用且不可点击（显示“尚无凭据”）——用户必须从头重新创建节点。如果您不知道真实的凭据 ID，请完全省略 credentials 块；缺失的块会显示一个正常的空下拉菜单，用户可以点击。使用 n8n_manage_credentials({action: "list"}) 先发现真实的凭据 ID。

// ❌ 破坏凭据选择器
"credentials": {"httpHeaderAuth": {"id": "REPLACE_ME", "name": "我的 API 密钥"}}

// ✅ 未知 ID → 省略 credentials 块；用户在 UI 中选择
// ✅ 已知 ID（来自 n8n_manage_credentials 列表）→ 使用真实 ID

2. 为节点 id 生成 UUID v4 值——不要使用人类可读的字符串如 "http-list-node"。n8n 的前端使用节点 ID 进行表单绑定和凭据组件初始化；非 UUID 的 ID 会导致微妙的 UI 问题。

3. 为每个节点使用当前的 typeVersion——通过 get_node 检查，而不是硬编码记忆的版本（例如 httpRequest 是 4.4+，不是 4.2）。

---

关键：nodeType 格式

两种不同的格式用于不同的工具！

格式 1：搜索/验证工具

// 使用短前缀
"nodes-base.slack"
"nodes-base.httpRequest"
"nodes-base.webhook"
"nodes-langchain.agent"

使用此格式的工具：

• search_nodes（返回此格式）
• get_node
• validate_node
• validate_workflow

格式 2：工作流工具

// 使用完整前缀
"n8n-nodes-base.slack"
"n8n-nodes-base.httpRequest"
"n8n-nodes-base.webhook"
"@n8n/n8n-nodes-langchain.agent"

使用此格式的工具：

• n8n_create_workflow
• n8n_update_partial_workflow

转换

// search_nodes 返回两种格式
{
  "nodeType": "nodes-base.slack",          // 用于搜索/验证工具
  "workflowNodeType": "n8n-nodes-base.slack"  // 用于工作流工具
}

---

常见错误

八个反复出现的错误。其中两个值得完整展示，因为它们会静默地破坏结构：

// nodeType 前缀（搜索/验证工具需要短格式）
get_node({nodeType: "slack"})              // ❌ 缺少前缀 → "节点未找到"
get_node({nodeType: "n8n-nodes-base.slack"}) // ❌ 完整前缀用于工作流工具
get_node({nodeType: "nodes-base.slack"})     // ✅

// credentials 必须按类型嵌套为 {id, name} — 而不是扁平字符串
updates: {credentials: "myApiKey"}                              // ❌
updates: {credentials: {httpHeaderAuth: {id: "abc123", name: "我的 API 密钥"}}}  // ✅

#	错误	修复
1	错误的 nodeType 格式	搜索/验证使用短格式 nodes-base.*；工作流工具使用完整格式 n8n-nodes-base.*（见上文）
2	默认使用 detail: "full"	默认 standard 覆盖 95%；使用 docs/search_properties 代替 full
3	未指定验证 profile	显式传递 profile: "runtime"（其他阶段使用 minimal/ai-friendly/strict）
4	忽略自动清理	所有节点在任何更新时都会被清理（操作符结构、IF/Switch 元数据）；它无法修复断开的连接或分支数量不匹配
5	未使用智能参数	使用 branch: "true" / case: 0 代替脆弱的 sourceIndex 计算
6	省略 intent	在 n8n_update_partial_workflow 上始终包含 intent 以获得更好的响应
7	使用 parameters 而不是 updates	updateNode 接受 updates: {...}，而不是 parameters: {...}
8	错误的凭据格式	按类型嵌套为 {id, name}（见上文）

每个错误的完整错误/正确示例：参见 VALIDATION_GUIDE.md → 常见错误。

---

工具使用模式

三种模式主导实际使用。每个模式的逐步工作示例在参考指南中。

• 模式 1 — 节点发现（平均步骤间隔 18 秒）：search_nodes({query}) → get_node({nodeType, includeExamples: true})。参见 SEARCH_GUIDE.md。
• 模式 2 — 验证循环（思考 23 秒，修复 58 秒）：validate_node({profile: "runtime"}) → 读取 errors → 修复配置 → 再次验证直到干净。参见 VALIDATION_GUIDE.md。
• 模式 3 — 工作流编辑（99.0% 成功率，平均编辑间隔 56 秒）：迭代 n8n_update_partial_workflow（带 intent）→ n8n_validate_workflow → 最后 activateWorkflow。迭代构建，不要一次性完成。参见 WORKFLOW_GUIDE.md。

---

详细指南

节点发现工具

参见 SEARCH_GUIDE.md 了解：

• search_nodes
• get_node 的详情级别（minimal, standard, full）
• get_node 的模式（info, docs, search_properties, versions）

验证工具

参见 VALIDATION_GUIDE.md 了解：

• 验证 profile 说明
• validate_node 的模式（minimal, full）
• validate_workflow 的完整结构
• 自动清理系统
• 处理验证错误

工作流管理

参见 WORKFLOW_GUIDE.md 了解：

• n8n_create_workflow
• n8n_update_partial_workflow（19 种操作类型，包括 patchNodeField！）
• 智能参数（branch, case）
• AI 连接类型（8 种）
• 工作流激活（activateWorkflow/deactivateWorkflow）
• n8n_deploy_template
• n8n_workflow_versions
• n8n_manage_credentials（凭据 CRUD + 模式发现）
• n8n_audit_instance（安全审计）

模板、数据表和自助工具

参见 OPERATIONS_GUIDE.md 了解：

• search_templates / get_template / n8n_deploy_template 示例
• n8n_manage_datatable（完整操作、过滤条件、示例）
• tools_documentation, ai_agents_guide, n8n_health_check

---

模板使用

2700+ 模板库有三个工具：search_templates（模式 query/by_nodes/by_task/by_metadata）、get_template（模式 structure/full）和 n8n_deploy_template（部署到您的实例，支持 autoFix/autoUpgradeVersions，返回工作流 ID + 所需凭据 + 应用的修复）。

完整的搜索/获取/部署示例参见 OPERATIONS_GUIDE.md。

---

数据表管理

n8n_manage_datatable 是用于从工作流外部管理数据表和行的 MCP 工具（表操作 createTable/listTables/getTable/updateTable/deleteTable；行操作 getRows/insertRows/updateRows/upsertRows/deleteRows，支持过滤、分页和 dryRun）。不要将其与工作流内的 nodes-base.dataTable 节点混淆，后者在执行期间读取/写入行（参见 n8n-node-configuration → OPERATION_PATTERNS.md）。经验法则：MCP 工具用于一次性设置表，工作流节点用于每次执行时读取/写入。deleteRows 需要过滤器；在批量更改前使用 dryRun: true。

所有操作、过滤条件和示例参见 OPERATIONS_GUIDE.md。

---

凭据管理

n8n_manage_credentials 是统一的凭据工具：操作 list、get、create、update、delete、getSchema。它从不返回秘密——get/create/update 会剥离 data 字段。在 create 之前使用 getSchema 发现必填字段。可选的 includeUsage: true 标志（在 list/get 上）会反向扫描工作流并附加 usedIn: [{id, name, active}] + usageCount——在删除或轮换凭据之前使用它来查看会破坏什么（它会触发完整的客户端扫描，上限为 5000 个工作流，排除已归档的，并在失败时降级为 usageScanError 字段）。

所有操作、includeUsage 形状、安全说明和安全删除/轮换工作流参见 WORKFLOW_GUIDE.md。

---

安全与审计

n8n_audit_instance 结合了 n8n 的内置审计（类别 credentials/database/nodes/instance/filesystem）和自定义深度扫描（hardcoded_secrets、unauthenticated_webhooks、error_handling、data_retention）。所有参数可选：categories、includeCustomScan（默认 true）、customChecks、daysAbandonedWorkflow。检测到的秘密会被掩码（前 6 个 + 后 4 个字符）。输出是可操作的 markdown 报告——摘要表、按工作流的发现以及修复手册，分为可自动修复/需要审查/需要用户操作。

两种扫描方法、示例和完整修复类型参见 WORKFLOW_GUIDE.md。

---

自助工具

• tools_documentation() — 所有工具的概述；tools_documentation({topic, depth: "full"}) 用于特定工具。代码节点指南通过主题 javascript_code_node_guide / python_code_node_guide 获取。
• AI 代理指南 — tools_documentation({topic: "ai_agents_guide", depth: "full"})（无独立工具）；返回架构、连接、工具、验证、最佳实践。
• n8n_health_check() — 快速检查；n8n_health_check({mode: "diagnostic"}) 返回状态、环境变量、工具状态、API 连接。

示例参见 OPERATIONS_GUIDE.md。

---

工具可用性

始终可用（无需 n8n API）：

• search_nodes, get_node
• validate_node, validate_workflow
• search_templates, get_template
• tools_documentation（包括 ai_agents_guide 主题）

需要 n8n API（N8N_API_URL + N8N_API_KEY）：

• n8n_create_workflow
• n8n_update_partial_workflow, n8n_update_full_workflow
• n8n_validate_workflow（按 ID）
• n8n_list_workflows, n8n_get_workflow, n8n_delete_workflow
• n8n_test_workflow
• n8n_executions
• n8n_deploy_template
• n8n_workflow_versions
• n8n_autofix_workflow
• n8n_manage_datatable
• n8n_manage_credentials
• n8n_audit_instance

如果 API 工具不可用，请使用模板和仅验证的工作流。

---

统一工具参考

• get_node — 详情级别（minimal ~200 tok / standard ~1-2K，推荐 / full ~3-8K，谨慎使用）和模式（info 默认，docs，search_properties + propertyQuery，versions，compare，breaking，migrations）。深入参见 SEARCH_GUIDE.md。
• validate_node — 模式 full（默认，错误/警告/建议）和 minimal（必填字段检查）；profile minimal/runtime（默认，推荐）/ai-friendly/strict。深入参见 VALIDATION_GUIDE.md。

---

性能特征

工具	响应时间	负载大小
search_nodes	<20ms	小
get_node (standard)	<10ms	~1-2KB
get_node (full)	<100ms	3-8KB
validate_node (minimal)	<50ms	小
validate_node (full)	<100ms	中
validate_workflow	100-500ms	中
n8n_manage_credentials	50-500ms	小-中
n8n_audit_instance	500-5000ms	大
n8n_create_workflow	100-500ms	中
n8n_update_partial_workflow	50-200ms	小
n8n_deploy_template	200-500ms	中

---

最佳实践

应该做

• 对于简单工作流（<=5 个节点），直接使用 MCP 工具——不要过度设计调查
• 使用 patchNodeField 对 Code 节点内容进行精确编辑，而不是替换整个节点
• 大多数情况下使用 get_node({detail: "standard"})
• 显式指定验证 profile（profile: "runtime"）
• 使用智能参数（branch, case）提高清晰度
• 在工作流更新中包含 intent 参数
• 遵循 search → get_node → validate 工作流
• 迭代工作流（平均编辑间隔 56 秒）
• 每次重大更改后验证
• 使用 includeExamples: true 获取真实配置
• 使用 n8n_deploy_template 快速启动

不要做

• 除非必要，不要使用 detail: "full"（浪费 token）
• 不要忘记 nodeType 前缀（nodes-base.*）
• 不要跳过验证 profile
• 不要试图一次性构建工作流（迭代！）
• 不要忽略自动清理行为
• 不要在搜索/验证工具中使用完整前缀（n8n-nodes-base.*）
• 不要忘记在构建后激活工作流

---

总结

最重要：

1. 使用 get_node 并设置 detail: "standard"（默认）——覆盖 95% 的用例
2. nodeType 格式不同：nodes-base.*（搜索/验证）vs n8n-nodes-base.*（工作流）
3. 指定 验证 profile（推荐 runtime）
4. 使用 智能参数（branch="true", case=0）
5. 在工作流更新中包含 intent 参数
6. 自动清理 在更新期间对所有节点运行
7. 工作流可以通过 API 激活（activateWorkflow 操作）
8. 工作流是 迭代构建 的（平均编辑间隔 56 秒）
9. 数据表 使用 n8n_manage_datatable 管理（CRUD + 过滤）
10. 凭据 使用 n8n_manage_credentials 管理（CRUD + 模式发现）
11. 安全审计 通过 n8n_audit_instance（内置 + 自定义深度扫描）
12. AI 代理指南 可通过 tools_documentation({topic: "ai_agents_guide", depth: "full"}) 获取

常见工作流：

1. search_nodes → 查找节点
2. get_node → 了解配置
3. validate_node → 检查配置
4. n8n_create_workflow → 构建
5. n8n_validate_workflow → 验证
6. n8n_update_partial_workflow → 迭代
7. activateWorkflow → 上线！

详情请参见：

• SEARCH_GUIDE.md - 节点发现
• VALIDATION_GUIDE.md - 配置验证 + 常见错误
• WORKFLOW_GUIDE.md - 工作流管理
• OPERATIONS_GUIDE.md - 模板、数据表、自助工具

---

相关技能：

• n8n 表达式语法 - 在工作流字段中编写表达式
• n8n 工作流模式 - 来自模板的架构模式
• n8n 验证专家 - 解释验证错误
• n8n 节点配置 - 操作特定要求
• n8n Code JavaScript - 在 Code 节点中编写 JavaScript
• n8n Code Python - 在 Code 节点中编写 Python