n8n-mcp-tools-expert

n8n MCP 工具专家

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

---

工具类别

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

1. 节点发现 → SEARCH_GUIDE.md
2. 配置验证 → VALIDATION_GUIDE.md
3. 工作流管理 → WORKFLOW_GUIDE.md
4. 模板库 - 搜索和部署 2,700 多个真实工作流
5. 数据表 - 管理 n8n 数据表、行和列（n8n_manage_datatable）
6. 工作流文件夹 - 文件夹 CRUD + 工作流归类（n8n_manage_folders）
7. 凭据管理 - 完整的凭据 CRUD + 模式发现（n8n_manage_credentials）
8. 安全与审计 - 使用自定义深度扫描审计实例安全（n8n_audit_instance）
9. 文档与指南 - 工具文档、AI Agent 指南、Code 节点指南
10. Agent - 创建、配置、验证、运行和发布已持久化的 n8n Agent（n8n_manage_agents，需要 N8N_MCP_ACCESS_TOKEN）
11. 节点资源解析 - 使用真实凭据解析实时下拉菜单/资源定位器值（n8n_explore_node_resources，需要 N8N_MCP_ACCESS_TOKEN）
12. 实例目录 - 列出项目和标签（n8n_list_catalog）

---

快速参考

最常用工具（按成功率）

工具	使用场景	速度
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_folders	文件夹 CRUD + 整理工作流	100-500ms
n8n_manage_credentials	凭据 CRUD + 模式发现	50-500ms
n8n_audit_instance	安全审计（内置 + 自定义扫描）	500-5000ms
n8n_autofix_workflow	自动修复验证错误	200-1500ms
n8n_manage_agents	已持久化 n8n Agent 的 CRUD/验证/发布	150-400ms；call 操作：5-60s
n8n_explore_node_resources	解析实时 loadOptions/listSearch 值	200 ms - 5 s
n8n_list_catalog	列出项目或标签	50-300ms

---

工具选择指南

查找合适的节点

工作流：

1. search_nodes({query: "keyword"})
2. get_node({nodeType: "nodes-base.name"})
3. [Optional] get_node({nodeType: "nodes-base.name", mode: "docs"})

示例：

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

// Step 2: Get details
get_node({nodeType: "nodes-base.slack"})
// Returns: operations, properties, examples (standard detail)

// Step 3: Get readable documentation
get_node({nodeType: "nodes-base.slack", mode: "docs"})
// Returns: markdown documentation

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

验证配置

工作流：

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

常见模式：validate → fix → validate（每个周期思考 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
5. n8n_update_partial_workflow({id, operations: [{type: "activateWorkflow"}]})

常见模式：迭代更新（两次编辑之间平均 56s）

重要：创建工作流时保持节点 JSON 规范

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

1. 切勿使用占位符 ID 输出 credentials 块。 像 "id": "REPLACE_ME" 这样的虚假 ID 会导致凭据选择器永久禁用且无法点击，在 n8n UI 中显示“尚无凭据”——用户不得不从头重新创建节点。如果你不知道真实的凭据 ID，请完全省略 credentials 块；省略该块会显示一个正常的空下拉菜单，供用户点击。请先使用 n8n_manage_credentials({action: "list"}) 查找真实的凭据 ID。

// ❌ Breaks the credential selector
"credentials": {"httpHeaderAuth": {"id": "REPLACE_ME", "name": "My API Key"}}

// ✅ Unknown ID → omit credentials block; user picks in UI
// ✅ Known ID (from n8n_manage_credentials list) → use the real ID

2. 为节点 id 生成 UUID v4 值——不要使用 "http-list-node" 这样的易读字符串。n8n 前端使用节点 ID 进行表单绑定和凭据组件初始化；非 UUID ID 会造成不易察觉的 UI 问题。

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

---

重要：nodeType 格式

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

格式 1：搜索/验证工具

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

使用此格式的工具：

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

格式 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

转换

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

---

常见错误

有 8 个反复出现的错误。其中两个值得完整展示，因为它们会在不知不觉中破坏结构：

// nodeType prefix (search/validate tools want the SHORT form)
get_node({nodeType: "slack"})              // ❌ missing prefix → "Node not found"
get_node({nodeType: "n8n-nodes-base.slack"}) // ❌ FULL prefix is for workflow tools
get_node({nodeType: "nodes-base.slack"})     // ✅

// credentials must be nested by type with {id, name} — not a flat string
updates: {credentials: "myApiKey"}                              // ❌
updates: {credentials: {httpHeaderAuth: {id: "abc123", name: "My API Key"}}}  // ✅

#	错误	修正方法
1	nodeType 格式错误	搜索/验证使用 SHORT nodes-base.*；工作流工具使用 FULL n8n-nodes-base.*（见上文）
2	默认使用 detail: "full"	默认的 standard 已涵盖 95% 的需求；优先使用 docs/search_properties，而不是 full
3	未设置验证配置	明确传入 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 — 节点发现（步骤间平均 18s）：search_nodes({query}) → get_node({nodeType, includeExamples: true})。参见 SEARCH_GUIDE.md。
• 模式 2 — 验证循环（思考 23s，修复 58s）：validate_node({profile: "runtime"}) → 读取 errors → 修复配置 → 再次验证，直到通过。参见 VALIDATION_GUIDE.md。
• 模式 3 — 工作流编辑（成功率 99.0%，编辑间平均 56s）：迭代调用 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，了解：

• 验证配置详解
• validate_node 的模式（minimal、full）
• validate_workflow 的完整结构
• 自动清理系统
• 处理验证错误

工作流管理

参见 WORKFLOW_GUIDE.md，了解：

• n8n_create_workflow
• n8n_update_partial_workflow（21 种操作类型，包括 patchNodeField、setNodeGroups 和 moveToFolder！）
• 智能参数（branch、case）
• AI 连接类型（8 种）
• 工作流激活（activateWorkflow/deactivateWorkflow）
• n8n_deploy_template
• n8n_workflow_versions
• n8n_manage_folders（文件夹 CRUD + 工作流放置）
• 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

---

模板用法

这个包含 2,700 多个模板的库提供 3 个工具：search_templates（模式 query/by_nodes/by_task/by_metadata）、get_template（模式 structure/full）和 n8n_deploy_template（部署到你的实例，支持 autoFix/autoUpgradeVersions，并返回工作流 ID、所需凭据和已应用的修复）。

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

---

运行工作流

n8n_test_workflow 有一个必需参数（workflowId），并提供一个用于选择执行路径的 method：

method	后端	功能
auto（默认）	公共 API	检测 Webhook/表单/聊天触发器，并通过 HTTP 触发它——工作流必须处于激活状态。若没有此类触发器，则会报告无法触发该工作流，并列出下方的方法。auto 绝不会通过 n8n 的 MCP 服务运行任何内容。
trigger	公共 API	相同的 HTTP 路径，显式请求执行。
prepare	n8n 的 MCP 服务	只读：列出需要固定数据的节点。
pinned	n8n 的 MCP 服务	使用 pinData 代替触发器、带凭据的节点和 HTTP Request 节点来运行工作流，并等待执行完成。其他所有节点仍会运行。若运行以 error/crashed/canceled 状态结束，则会返回 EXECUTION_FAILED 和 executionId。
direct	n8n 的 MCP 服务	启动运行后立即返回；不会固定任何数据，因此所有节点都会运行。message 或 data/headers 会作为输入转发给触发器。

• 后 3 种方法需要 N8N_MCP_ACCESS_TOKEN（n8n 2.34+）以及工作流的 “Available in MCP” 设置。
• pinData 以节点名称为键，每个值都是一个由 {"json": {...}} 包装的项目数组——例如 {"Webhook": [{"json": {"id": "123"}}]}，不能是扁平对象。它不能为空。
• triggerNodeName 用于选择要从哪个触发器节点开始（默认为检测到的节点；只要提供了输入，n8n 就要求必须指定）。
• 这两种运行方法都会实际执行工作流节点。direct 会运行所有节点；pinned 只固定触发器节点、有凭据的节点和 HTTP Request 节点，因此 Code、Set、If 以及不需要凭据的 I/O（Execute Command、文件读写）仍会运行。运行会在任何位置写入数据的工作流前，请先向用户确认。
• executionMode 适用于 direct：manual（默认）或 production。它会更改执行上下文，但不会改变运行是否会产生副作用——生产运行会经过生产执行路径，并作为生产运行记录。仅在用户提出要求时传入。
• timeoutMs 是官方调用的客户端截止时间（5000-600000；prepare 默认 30000，pinned/direct 默认 300000）。
• direct 会在运行启动后立即返回，因此无论运行最终结果如何，都会报告成功并返回 executionId——请轮询 n8n_executions({action: "get", id: executionId}) 查询结果。若 n8n 完全拒绝执行请求，则会返回 OFFICIAL_MCP_ERROR，而不是 EXECUTION_FAILED。
• 如果工作流的 “Available in MCP” 设置处于关闭状态，则会返回 WORKFLOW_NOT_EXPOSED；exposeToMcp: true 会启用该设置并重试一次。这是可见且持久的更改——请先询问用户，并说明启用该设置本身会更新工作流，因此可能覆盖同时发生的 UI 编辑。

成功响应和路由响应会指出 method 和 backend（public-api 或 official-mcp）；参数验证拒绝的信封可能不包含这两项。

各方法的可运行示例请参阅 WORKFLOW_GUIDE.md。

---

版本历史

n8n_workflow_versions 会读取两种彼此独立的历史记录，通过 source 选择：

• source: "local"（默认）——n8n-mcp 在更改工作流前创建的快照。适用于任何 n8n 版本，无需令牌，ID 为数字。无法看到在 n8n UI 中进行的编辑。唯一支持 delete 和 prune 的来源。
• source: "native"——n8n 自带的工作流历史记录，与 UI 显示的列表相同，包含其他人员所做的编辑。需要 N8N_MCP_ACCESS_TOKEN（n8n 2.34+；原生 diff 需要 n8n 2.36，该版本推出了 get_workflow_versions_diff），并且工作流的 "Available in MCP" 设置必须开启；ID 是不透明字符串；list 最多返回 50 条记录，并支持 offset；对于 delete 和 prune，系统会拒绝并返回 MODE_NOT_SUPPORTED_FOR_SOURCE（保留策略由 n8n 管理）。原生回滚不会预先验证——即使传入 validateBefore，也会被忽略。

mode: "diff" 用于比较两个版本（versionId 和 toVersionId，二者必须来自同一来源和工作流）。本地差异（data.format: "n8n-mcp"）会以节点 ID 报告新增、删除和修改的节点；原生差异（data.format: "n8n"）则使用 n8n 自己的负载格式，其中包含字段级的前后值。请根据 data.format 进行判断，不要假定字段名称固定不变。

原生模式与通过路由调用的运行方法使用相同的授权门槛：如果工作流的 "Available in MCP" 设置已关闭，系统会返回 WORKFLOW_NOT_EXPOSED；再次传入 exposeToMcp: true 会启用该设置并重试一次（此时响应会包含 exposedToMcp: true）。这会对工作流作出可见且持久的更改——传入该参数前请先征得用户同意。timeoutMs（5000-600000）是原生调用的客户端截止时间。

如需查看所有模式以及两种来源的可运行示例，请参阅 WORKFLOW_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。

列操作——addColumn、deleteColumn、renameColumn——用于更改现有数据表的列，而 Public API 不支持此操作；这些操作通过 n8n 的 MCP 服务执行，需要 N8N_MCP_ACCESS_TOKEN（n8n 2.34+）。addColumn 接受 column: {name, type}（名称必须以字母开头，且只能包含字母、数字和下划线，最多 63 个字符；类型为 string、number、boolean 或 date）；deleteColumn/renameColumn 接受从 getTable 获取的 columnId，而 renameColumn 将新列名放在 name 中。它们通过项目定位数据表：恰好有一个可访问项目时，projectId 会自动解析；否则调用会返回 PROJECT_REQUIRED 并列出候选项目——传入 projectId（通过 n8n_list_catalog({kind: "projects"}) 获取）即可跳过解析。重命名数据表不属于列操作：请通过 Public API 使用 updateTable。

deleteColumn 会连同列一起删除该列的所有值，而且无法撤销。 在最意想不到的情况下，这个问题尤其突出：列创建后无法更改类型，因此“将此列改为数字”实际上意味着删除后重新添加，这会丢弃该列中的所有数据。如果这些值很重要，请先用 getRows 读取，并在删除包含数据的列前征得用户同意。

如需查看所有操作、筛选条件和示例，请参阅 OPERATIONS_GUIDE.md。

---

工作流文件夹

n8n_manage_folders 用于将工作流整理到文件夹中（操作包括 create/list/get/rename/move/delete；n8n 2.19+，在免费 Community 级别及更高版本中注册）。projectId 默认为 'personal'。将工作流放入文件夹应使用 工作流 工具：在 n8n_create_workflow 中设置 parentFolderId，或使用 n8n_update_partial_workflow 的 moveToFolder 操作（两者均需 n8n 2.32+；null = 项目根目录）。有两点需要牢记：在 n8n 的 API 中，工作流所属文件夹是只写的（请通过文件夹的 get 计数确认位置，切勿通过读取工作流来确认）；不带 transferToFolderId 的 delete 操作会归档文件夹中的工作流（transferToFolderId: "0" 则会将其移至项目根目录并保持激活状态）。

请参阅 WORKFLOW_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 字段）。

请参阅 WORKFLOW_GUIDE.md，了解所有操作、includeUsage 的数据结构、安全说明，以及安全删除或轮换凭据的工作流。

---

Agents

本节中的三个工具仅适用于 n8n 实例级 MCP 服务（与 Public API 使用不同的端点）。n8n_manage_agents 和 n8n_explore_node_resources 需要 N8N_MCP_ACCESS_TOKEN；n8n_list_catalog 无需该令牌，仅在回退到团队项目时使用。其他工具会通过同一服务路由各自的操作——例如 n8n_test_workflow 的 prepare/pinned/direct、n8n_workflow_versions 的 source: "native"，以及 n8n_manage_datatable 的列操作——具体说明见各自的章节；另请参阅下文的“Tool Availability”。

• n8n_manage_agents — 创建、配置、验证、运行和发布持久化的 n8n Agent（独立的助手构件：模型、指令、工具、技能、任务、记忆、渠道；不是 AI Agent 工作流节点）。操作包括：reference、search、get、create、mutate、validate、call、publish、unpublish、revert、versions、delete、discover_assets、verify_mcp_server、update_integration。请从 action: "reference" 开始，然后依次执行 discover_assets → create → mutate（每次只处理一个资源，并始终使用最新哈希——n8n 会将其作为 configHash 返回，并要求将其作为 args.baseConfigHash 传回；过期的哈希会返回 STALE_CONFIG）→ validate。仅在明确请求时执行 publish；call 会使用真实凭据和工具运行 Agent，并可能返回供人工决定的 approvals[]。timeoutMs 是顶层参数（默认值为 30000，call 的默认值为 180000），不属于 args。需要带有 agents 模块的 n8n 2.34+；在 2.36.x 上，agents 运行时会拒绝 azureOpenAiApi/aws 凭据。封套错误代码：NOT_CONFIGURED、INVALID_ARGS、STALE_CONFIG、AGENT_NOT_RUNNABLE、AGENT_TOOL_ERROR（自定义工具编译失败，或 agentId 未知），以及通用的 OFFICIAL_MCP_* 系列（AUTH_FAILED、NOT_ENABLED、RATE_LIMITED、TOOL_UNAVAILABLE、URL_REJECTED、TIMEOUT、TRANSPORT_ERROR、ERROR）。完整工作流请参阅 n8n-agents 技能中的“Persisted n8n Agents”章节。
• n8n_explore_node_resources — 使用实时凭据解析节点 loadOptions 下拉列表或 resource-locator listSearch 背后的实际值（Slack 频道、Google Sheets 工作表、模型列表），而不是猜测 ID。当 get_node（standard 详细程度）在某个属性中显示 dynamicOptions: {methodName, methodType, dependsOn} 时，请使用此工具。必须提供六个参数，且不会自动推断任何参数：nodeType（LONG 格式）、version（该方法所属节点的 typeVersion）、从 dynamicOptions 原样复制的 methodName 和 methodType，以及 credentialType 和该类型的 credentialId，后两者通过 n8n_manage_credentials({action: "list"}) 获取。将方法的 dependsOn 对应值放入 currentNodeParameters；resource-locator 值须保留 {__rl: true, mode: "id", value: "…"} 结构。每项结果中的 value 才是工作流参数应使用的值；name 仅用于显示。
• n8n_list_catalog — 列出实例级 projects（标明个人项目，并提供供 n8n_manage_agents/n8n_manage_datatable 使用的 projectId）或 tags。无需令牌即可通过 Public API 使用；若已配置令牌，当 Public API 的许可门控拒绝请求时，会回退到官方 MCP 服务以获取团队项目（teamProjectsEnabled 会报告相关状态）。

安全与审计

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() — 所有工具的概览（从 n8n-mcp 2.97.0 起，会先显示原生优先的节点选择步骤）；针对特定工具，可使用 tools_documentation({topic, depth: "full"})。expression_helpers（2.97.0+）列出 {{ }} 的辅助方法（.pluck()、.sum()、.unique()、.diffTo()、$ifEmpty()）：编写 Code 节点进行单行转换前，请先查看此文档。Code 节点指南可通过主题 javascript_code_node_guide / python_code_node_guide 获取。
• AI Agent 指南 — tools_documentation({topic: "ai_agents_guide", depth: "full"})（没有独立工具）；返回架构、连接、工具、验证和最佳实践。
• n8n_health_check() — 快速检查；n8n_health_check({mode: "diagnostic"}) 返回状态、环境变量、工具状态和 API 连通性。两种模式也都会返回 officialMcp 区块 — {configured, endpoint, reachable, toolCount, agentTools} — 用于预检所有依赖 N8N_MCP_ACCESS_TOKEN 的功能：Agent 工具、n8n_test_workflow 的路由方法、原生版本历史记录和数据表列操作。请先查看一次，再使用这些功能，以免在任务进行中才通过 NOT_CONFIGURED 响应发现配置缺失。

有关示例，请参阅 OPERATIONS_GUIDE.md。

---

工具可用性

始终可用（无需 n8n API）：

• search_nodes、get_node
• validate_node、validate_workflow
• search_templates、get_template
• tools_documentation（包含 ai_agents_guide，以及从 2.97.0 起提供的 expression_helpers 主题）

需要 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_evaluations（读取：n8n 2.30+，且 API 密钥需在 2.30+ 创建；运行／取消：n8n 2.32+，且密钥需在 2.32+ 创建 — 较早创建的密钥缺少 testRun 作用域）
• n8n_deploy_template
• n8n_workflow_versions
• n8n_autofix_workflow
• n8n_manage_datatable
• n8n_manage_folders（文件夹 CRUD：n8n 2.19+，已注册的 Community 级别及以上；通过 parentFolderId/moveToFolder 放置工作流：n8n 2.32+）
• n8n_manage_credentials
• n8n_audit_instance
• n8n_list_catalog（无需令牌即可使用；仅在回退到团队项目时需要令牌）

需要 N8N_MCP_ACCESS_TOKEN（在 n8n Settings → Instance-level MCP 中获取的独立令牌，此外还需提供上述 Public API 凭据）：

• n8n_manage_agents
• n8n_explore_node_resources
• n8n_test_workflow，使用 method: "prepare"/"pinned"/"direct" 时（还需要为工作流启用 “Available in MCP” 设置）
• n8n_workflow_versions，使用 source: "native" 时（还需要为工作流启用 “Available in MCP” 设置）
• n8n_manage_datatable，使用 addColumn/deleteColumn/renameColumn 时

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

---

统一工具参考

• get_node — 详细程度（minimal 约 200 个 token / standard 约 1–2K，推荐 / full 约 3–8K，请酌情使用）和模式（默认 info、docs、search_properties + propertyQuery、versions、compare、breaking、migrations）。详见 SEARCH_GUIDE.md。
• validate_node — 模式 full（默认，提供错误／警告／建议）和 minimal（检查必填字段）；配置文件 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_folders	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 工具，不要过度设计调查流程
• 对 Code 节点内容进行精细修改时，使用 patchNodeField，而不是替换整个节点
• 大多数情况下使用 get_node({detail: "standard"})
• 明确指定验证配置文件（profile: "runtime"）
• 使用智能参数（branch、case），让表达更清晰
• 在工作流更新中包含 intent 参数
• 遵循 search → get_node → validate 的流程
• 迭代工作流（平均每次编辑间隔 56 秒）
• 每次重大更改后都进行验证
• 使用 includeExamples: true 获取实际配置
• 使用 n8n_deploy_template 快速开始

不应该

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

---

摘要

最重要的内容：

1. 使用 get_node 并设置 detail: "standard"（默认值）——涵盖 95% 的使用场景
2. nodeType 格式有所不同：nodes-base.*（搜索/验证）与 n8n-nodes-base.*（工作流）
3. 指定验证配置文件（推荐使用 runtime）
4. 使用智能参数（branch="true"、case=0）
5. 更新工作流时包含 intent 参数
6. 更新期间会对所有节点运行自动清理
7. 可通过 API 激活工作流（activateWorkflow 操作）
8. 工作流以迭代方式构建（两次编辑间平均间隔 56 秒）
9. 使用 n8n_manage_datatable 管理数据表（CRUD + 筛选）
10. 使用 n8n_manage_folders 管理文件夹；工作流位置仅支持写入（请通过文件夹计数验证，而非查看工作流）
11. 使用 n8n_manage_credentials 管理凭据（CRUD + 架构发现）
12. 通过 n8n_audit_instance 执行安全审计（内置扫描 + 自定义深度扫描）
13. 可通过 tools_documentation({topic: "ai_agents_guide", depth: "full"}) 获取 AI Agent 指南

常见工作流：

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 Expression Syntax - 在工作流字段中编写表达式
• n8n Workflow Patterns - 模板中的架构模式
• n8n Validation Expert - 解读验证错误
• n8n Node Configuration - 特定操作的要求
• n8n Code JavaScript - 在 Code 节点中编写 JavaScript
• n8n Code Python - 在 Code 节点中编写 Python