n8n-mcp-tools-expert

n8n MCP 工具专家

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

---

工具类别

n8n-mcp 提供 40 多种工具，分为以下类别：

1. 节点发现 → SEARCH_GUIDE.md
2. 配置验证 → VALIDATION_GUIDE.md
3. 工作流管理 → WORKFLOW_GUIDE.md
4. 模板库 - 搜索和访问 2,653 个真实工作流
5. 文档 - 获取工具和节点文档

---

快速参考

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

工具	使用场景	成功率	速度
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

---

工具选择指南

查找合适的节点

工作流：

1. search_nodes({query: "keyword"})
2. get_node_essentials({nodeType: "nodes-base.name"})
3. [Optional] get_node_documentation({nodeType: "nodes-base.name"})

示例：

// Step 1: Search
search_nodes({query: "slack"})
// Returns: nodes-base.slack

// Step 2: Get details (18s avg between steps)
get_node_essentials({nodeType: "nodes-base.slack"})
// Returns: operations, properties, examples

常见模式：搜索 → essentials（平均 18s）

验证配置

工作流：

1. validate_node_minimal({nodeType, config: {}}) - Check required fields
2. validate_node_operation({nodeType, config, profile: "runtime"}) - Full validation
3. [Repeat] Fix errors, validate again

常见模式：验证 → 修复 → 验证（每轮思考 23s，修复 58s）

管理工作流

工作流：

1. n8n_create_workflow({name, nodes, connections})
2. n8n_validate_workflow({id})
3. n8n_update_partial_workflow({id, operations: [...]})
4. n8n_validate_workflow({id}) again

常见模式：迭代更新（平均间隔 56s）

---

重要：nodeType 格式

不同工具使用两种不同格式！

格式 1：搜索/验证工具

// Use SHORT prefix
"nodes-base.slack"
"nodes-base.httpRequest"
"nodes-base.webhook"
"nodes-langchain.agent"

使用此格式的工具：

• search_nodes（返回此格式）
• get_node_essentials
• get_node_info
• validate_node_minimal
• validate_node_operation
• get_property_dependencies

格式 2：工作流工具

// Use FULL prefix
"n8n-nodes-base.slack"
"n8n-nodes-base.httpRequest"
"n8n-nodes-base.webhook"
"@n8n/n8n-nodes-langchain.agent"

使用此格式的工具：

• n8n_create_workflow
• n8n_update_partial_workflow
• list_node_templates

转换

// search_nodes returns BOTH formats
{
  "nodeType": "nodes-base.slack",          // For search/validate tools
  "workflowNodeType": "n8n-nodes-base.slack"  // For workflow tools
}

---

常见错误

❌ 错误 1：nodeType 格式错误

问题：“找不到节点”错误

❌ get_node_essentials({nodeType: "slack"})  // Missing prefix
❌ get_node_essentials({nodeType: "n8n-nodes-base.slack"})  // Wrong prefix

✅ get_node_essentials({nodeType: "nodes-base.slack"})  // Correct!

❌ 错误 2：使用 get_node_info 而非 get_node_essentials

问题：失败率为 20%，响应慢，负载过大

❌ get_node_info({nodeType: "nodes-base.slack"})
// Returns: 100KB+ data, 20% chance of failure

✅ get_node_essentials({nodeType: "nodes-base.slack"})
// Returns: 5KB focused data, 91.7% success, <10ms

何时使用 get_node_info：

• 调试复杂配置问题
• 需要完整的属性架构
• 探索高级功能

更好的替代方案：

1. get_node_essentials - 获取操作列表
2. get_node_documentation - 获取易读的文档
3. search_node_properties - 搜索特定属性

❌ 错误 3：未使用验证配置档

问题：误报太多，或者遗漏实际错误

配置档：

• minimal - 仅检查必填字段（快速、宽松）
• runtime - 检查值和类型（建议用于部署前）
• ai-friendly - 减少误报（用于 AI 配置）
• strict - 最严格的验证（用于生产环境）

❌ validate_node_operation({nodeType, config})  // Uses default

✅ validate_node_operation({nodeType, config, profile: "runtime"})  // Explicit

❌ 错误 4：忽略自动清理

会发生什么：任何工作流更新都会清理所有节点

自动修复：

• 二元运算符（equals、contains）→ 移除 singleValue
• 一元运算符（isEmpty、isNotEmpty）→ 添加 singleValue: true
• IF/Switch 节点 → 补充缺失的元数据

无法修复：

• 已损坏的连接
• 分支数量不匹配
• 自相矛盾的损坏状态

// After ANY update, auto-sanitization runs on ALL nodes
n8n_update_partial_workflow({id, operations: [...]})
// → Automatically fixes operator structures

❌ 错误 5：未使用智能参数

问题：多输出节点需要复杂地计算 sourceIndex

旧方法（手动）：

// IF node connection
{
  type: "addConnection",
  source: "IF",
  target: "Handler",
  sourceIndex: 0  // Which output? Hard to remember!
}

新方法（智能参数）：

// IF node - semantic branch names
{
  type: "addConnection",
  source: "IF",
  target: "True Handler",
  branch: "true"  // Clear and readable!
}

{
  type: "addConnection",
  source: "IF",
  target: "False Handler",
  branch: "false"
}

// Switch node - semantic case numbers
{
  type: "addConnection",
  source: "Switch",
  target: "Handler A",
  case: 0
}

---

工具使用模式

模式 1：节点发现（最常见）

常见工作流：步骤间平均间隔 18s

// Step 1: Search (fast!)
const results = await search_nodes({
  query: "slack",
  mode: "OR",  // Default: any word matches
  limit: 20
});
// → Returns: nodes-base.slack, nodes-base.slackTrigger

// Step 2: Get details (~18s later, user reviewing results)
const details = await get_node_essentials({
  nodeType: "nodes-base.slack",
  includeExamples: true  // Get real template configs
});
// → Returns: operations, properties, metadata

模式 2：验证循环

典型周期：思考 23s，修复 58s

// Step 1: Validate
const result = await validate_node_operation({
  nodeType: "nodes-base.slack",
  config: {
    resource: "channel",
    operation: "create"
  },
  profile: "runtime"
});

// Step 2: Check errors (~23s thinking)
if (!result.valid) {
  console.log(result.errors);  // "Missing required field: name"
}

// Step 3: Fix config (~58s fixing)
config.name = "general";

// Step 4: Validate again
await validate_node_operation({...});  // Repeat until clean

模式 3：工作流编辑

使用最多的更新工具：成功率 99.0%，编辑间平均间隔 56s

// Iterative workflow building (NOT one-shot!)
// Edit 1
await n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{type: "addNode", node: {...}}]
});

// ~56s later...

// Edit 2
await n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{type: "addConnection", source: "...", target: "..."}]
});

// ~56s later...

// Edit 3 (validation)
await n8n_validate_workflow({id: "workflow-id"});

---

详细指南

节点发现工具

请参阅 SEARCH_GUIDE.md，了解：

• search_nodes（成功率 99.9%）
• get_node_essentials 与 get_node_info 的区别
• 按类别列出节点
• 针对特定字段搜索节点属性

验证工具

请参阅 VALIDATION_GUIDE.md，了解：

• 验证配置说明
• validate_node_minimal 与 validate_node_operation 的区别
• validate_workflow 的完整结构
• 自动清理系统
• 处理验证错误

工作流管理

请参阅 WORKFLOW_GUIDE.md，了解：

• n8n_create_workflow
• n8n_update_partial_workflow（15 种操作类型！）
• 智能参数（branch、case）
• AI 连接类型（8 种）
• cleanStaleConnections 恢复

---

模板用法

搜索模板

// Search by keyword
search_templates({
  query: "webhook slack",
  limit: 20
});
// → Returns: 1,085 templates with metadata

// Get template details
get_template({
  templateId: 2947,  // Weather to Slack
  mode: "structure"  // or "full" for complete JSON
});

模板元数据

模板包括：

• 复杂度（简单、中等、复杂）
• 预计设置时间
• 所需服务
• 类别和用例
• 浏览量（受欢迎程度）

---

自助工具

获取工具文档

// List all tools
tools_documentation()

// Specific tool details
tools_documentation({
  topic: "search_nodes",
  depth: "full"
})

健康检查

// Verify MCP server connectivity
n8n_health_check()
// → Returns: status, features, API availability, version

数据库统计信息

get_database_statistics()
// → Returns: 537 nodes, 270 AI tools, 2,653 templates

---

工具可用性

始终可用（无需 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（91.7% 对比 80%）
• 明确指定验证配置
• 使用智能参数（branch、case）以提高清晰度
• 遵循 search → essentials → validate 工作流
• 迭代调整工作流（两次编辑之间平均间隔 56 秒）
• 每次重大更改后都进行验证
• 使用 includeExamples: true 获取实际配置

❌ 不要做

• 除非必要，否则不要使用 get_node_info（失败率高达 20%！）
• 不要忘记 nodeType 前缀（nodes-base.*）
• 不要跳过验证配置（使用 "runtime"）
• 不要试图一次性构建工作流（要迭代！）
• 不要忽略自动清理行为
• 不要在搜索工具中使用完整前缀（n8n-nodes-base.*）

摘要

最重要的事项：

1. 使用 get_node_essentials，而不是 get_node_info（5KB 对比 100KB，91.7% 对比 80%）
2. nodeType 格式有所不同：nodes-base.*（搜索）和 n8n-nodes-base.*（工作流）
3. 指定 validation profiles（推荐使用 runtime）
4. 使用 智能参数（branch="true"，case=0）
5. 更新期间会对所有节点运行 自动净化
6. 工作流以 迭代方式构建（两次编辑间平均间隔 56s）

常见工作流：

1. search_nodes → 查找节点
2. get_node_essentials → 了解配置
3. validate_node_operation → 检查配置
4. n8n_create_workflow → 构建
5. n8n_validate_workflow → 验证
6. n8n_update_partial_workflow → 迭代

详情请参阅：

• SEARCH_GUIDE.md - 节点发现
• VALIDATION_GUIDE.md - 配置验证
• WORKFLOW_GUIDE.md - 工作流管理

---

相关技能：

• n8n Expression Syntax - 在工作流字段中编写表达式
• n8n Workflow Patterns - 基于模板的架构模式
• n8n Validation Expert - 解读验证错误
• n8n Node Configuration - 特定操作的要求