using-n8n-mcp-skills

使用 n8n-mcp 技能

这是一个路由器，不是参考手册。它会告诉你接下来要做的事由哪个技能负责制定规则。技能正文包含实际指南——请使用 Skill 工具调用它们。如有疑问，多加载几个技能，而不是少加载。

社区的 n8n-mcp 服务和 n8n 本身的变化速度，比任何模型的训练截止时间都快。工具名称、参数、节点 typeVersion 和默认行为都会随版本变化。如果发现不一致——技能中提到的工具不存在、参数结构与 get_node 返回的内容不匹配，或实际行为与技能描述不同——请以实时工具为准，告知用户，并建议更新技能包和实例。

不容妥协的规则

三条规则，没有例外。每条规则都能避免一类看起来正确、却会在生产环境中出问题的工作流。

1. 执行任何 n8n 操作前，都要先调用相关技能——不只是调用 MCP 前。编写表达式、配置节点、设计工作流、连接节点或编写 Code 之前，都要调用匹配的技能。PreToolUse 钩子会在影响最大的工具调用前提醒你，但它们仅存在于 Claude Code 插件安装中。在其他所有环境中——Claude.ai 技能上传，以及任何将此技能包作为 Agent Plugin 加载的客户端（Codex、Cursor、Copilot 等）——都不会有任何提醒，这件事要由你负责。除非你在本次会话中看到钩子触发过，否则就假设自己没有钩子保护。
2. 激活前，先验证并核实。 激活前运行 validate_workflow（或按 ID 调用 n8n_validate_workflow），并在每次创建或更新后调用 n8n_get_workflow，检查 connections 对象。单靠验证无法发现静默丢弃的连线、Merge 索引偏一，以及未连接的错误输出。验证通过只表示 JSON 格式正确——不代表工作流正确。测试运行显示绿色也不能证明一切无误：{{ }} 中的 JS 错误会静默解析为 null（条件损坏的 Filter 会丢弃所有项目，但仍显示成功），因此要检查输出值。请参阅 n8n-expression-syntax。
3. 绝不要将密钥放在文本字段中。 令牌、API 密钥和密码始终要通过 n8n 凭据系统传递。如果没有原生节点，就使用 HTTP Request 节点和官方凭据类型。用 Set 节点存放令牌，再通过 {{ $json.token }} 引用，无异于多绕几步泄露密钥。请参阅 n8n-mcp-tools-expert。

依靠技能，而不是训练数据

n8n 不断变化。“记得的”参数名称经常悄悄出错——它们会作为普通字符串通过验证，运行时却不起作用。如果技能与记忆不一致，以技能为准。如果 get_node 与技能内容不一致，以工具为准，并指出这种差异。

强默认规则

这些是默认规则；下面的 Code 例外情况仅限所列内容。

优先使用原生节点，最后才用 Code。 按以下顺序选择：服务自带的节点（仅当没有节点涵盖该操作时才用 HTTP Request），然后是适用于该任务的原生节点，再然后是节点内的简短表达式，最后才是 Code。函数体或 {{ }} 内的多条语句都属于代码：应放在 Code 节点中。

任务	使用
仅选择路由的标记；丢弃项目	IF / Switch / Filter 中的条件
常量、错误或返回项目	Edit Fields (Set)
恢复较早的上下文	$('Node').item
Data Table get 后选取行	get 的排序依据 + 限制
分组并求和	Summarize
将项目合并为一个数组 / 将数组拆分为项目	Aggregate / Split Out
合并两个列表	Merge (combine by fields)
对比或同步两个列表	Compare Datasets
去重，包括跨运行去重	Remove Duplicates
前 N 项	Sort + Limit
日期	Date & Time，或一条 Luxon 表达式
XML / HTML / Markdown / CSV / XLSX	XML、HTML、Markdown、Extract From File / Convert To File
为 API 分页（无服务节点）	HTTP Request 的分页选项
限流调用	HTTP Request 的批处理选项，或 Loop + Wait
哈希、HMAC、UUID	Crypto（+ Webhook 原始请求体）

仅在以下情况使用 Code：没有节点能实现的循环或递归、跨运行状态、没有节点能处理的解析、队列模式工作节点上的大量项目处理（数千个项目，明确说明或测量得出），或用一个简短的 Code 节点（约 15 行）替代 4 个以上仅用于重塑数据的胶水节点。每个保留的 Code 或 HTTP Request 节点都必须添加备注 Why Code: <native node considered> — <reason>（或 Why HTTP:）。参见 n8n-node-configuration 和 n8n-code-javascript。

• 仅为下一个节点重新映射字段的 Set 是反模式。 将这些表达式放入下一个节点。将 Edit Fields 作为命名步骤使用没有问题。参见 n8n-expression-syntax。
• 每项迭代会自动处理。 默认的逐项执行已能处理时，不要添加 Loop Over Items 节点来“让它循环”。
• 根据实时架构配置，切勿凭记忆配置。 设置参数前先调用 get_node。参见 n8n-node-configuration。

危险信号：「准备要 ___」→ 调用 ___

如果你发现自己在想下面这些事，请停下来，先调用指定的技能。

想法	调用
“这个工作流很简单，我直接搭建就行”	n8n-workflow-patterns — 大多数“简单”流程最终都会包含 10 个以上的节点
“我加个 Set 节点来映射这些字段”	n8n-expression-syntax — 如果 Set 节点只为后续节点重新映射字段，这就是反模式；使用命名步骤则没问题
“我直接用 Code 节点吧，这样更简单”	先查看上面的工作表，再调用 n8n-code-javascript — Code 仅用于限定列表中的情况，并附上 Why Code: 说明
“用户提到了数据，我来写 Python”	n8n-code-javascript — 默认使用 JS；只有明确要求时才用 Python（n8n-code-python）
“我正在编写 AI Agent 将调用的代码”	n8n-code-tool — 其运行时契约与 Code 节点不同
“我会用 HTTP Request 调用这个 API”	n8n-mcp-tools-expert — 先用 search_nodes 搜索该服务自己的节点；若保留 HTTP 节点，需附上 Why HTTP: 说明
“我会用 3 个来源连接一个 Merge”	n8n-node-configuration — Merge 默认只有 2 个输入（numberInputs）；第 3 个输入会被静默丢弃
“验证通过了，可以激活了”	n8n-validation-expert + n8n-workflow-patterns — 运行反模式扫描
“验证报了个我不理解的错误”	n8n-validation-expert — 了解每条错误和警告的含义，以及哪些必须修复、哪些属于最佳实践建议
“我会在这里引用 $json.x”	n8n-expression-syntax — 在包含分支的工作流中，优先使用 $('Node').item.json.x
“这个 Webhook／定时工作流只有顺利执行的路径”	n8n-error-handling — 为每个可能失败的节点连接错误分支；4xx 表示调用方错误，5xx 表示你的错误
“我会把这个文件／图像作为 JSON 传递”	n8n-binary-and-data — 文件内容存放在 $binary 中，无法跨越 Agent 工具边界
“我会连接一个 AI Agent，并给模型一些工具”	n8n-agents — 工具名称和描述就是提示词；记忆、结构化输出和拓扑都暗藏陷阱
“我会把这段逻辑复制到另一个工作流中”／“这越来越庞大了”	n8n-subworkflows — 提取为可复用的子工作流；构建前先搜索
“我会创建该凭据／打开该工作流”（账户中有多个实例）	n8n-multi-instance — 用 instance: "<name>" 指定目标；未命名的调用会命中默认实例，而其他聊天可能会更改该默认实例

技能索引

技能	适用场景
using-n8n-mcp-skills	此路由器（自动加载）。指定负责处理任务的技能。
n8n-mcp-tools-expert	选择或调用任何 n8n-mcp 工具；节点发现；凭据；数据表；安全审计；模板
n8n-workflow-patterns	设计或构建工作流；选择架构（webhook / HTTP API / 数据库 / AI Agent / 定时 / 批处理）
n8n-node-configuration	配置任何节点；根据操作确定必填字段；属性依赖；精准编辑字段
n8n-expression-syntax	编写 {{ }}、$json/$node/$now；在节点间映射数据；转换把关；Set 节点规范
n8n-validation-expert	解读验证错误/警告；误报；验证循环；自动修复；审查现有工作流
n8n-code-javascript	任何 JavaScript Code 节点；数据访问；this.helpers；DateTime；SplitInBatches 循环模式
n8n-code-python	明确要求使用 Python 的 Code 节点；原生运行时（仅限 _items/_item，默认禁止导入，旧版 _input 代码会失败）
n8n-code-tool	可由 AI Agent 调用的 Custom Code Tool（toolCode）——返回字符串，不使用 $fromAI/$input
n8n-error-handling	Webhook/API 或无人值守工作流；连接错误输出；重试；4xx/5xx 响应格式；静默失败
n8n-binary-and-data	文件、图像、PDF、附件、上传/下载、视觉；向 Agent 工具传递文件或从中接收文件
n8n-subworkflows	可复用/多步骤构建；Execute Workflow；提取共享逻辑；Define-Below 输入；全部与逐项模式；将工作流公开为 Agent 工具
n8n-agents	AI Agent / 使用工具的大模型 / Text Classifier；工具设计与 $fromAI；系统提示词；结构化输出；记忆；RAG；人工审核；聊天机器人
n8n-multi-instance	具有多个实例的账户（存在 n8n_instances）；每次调用的 instance 参数；并行 Agent；switch；凭据写入；意外的 NOT_FOUND、读取错误/空结果、INSTANCE_* 错误
n8n-self-hosting	部署，而非工作流构建——在 VM 上自托管/安装/部署 n8n（Docker Compose + Caddy、单机与队列模式），或更新/备份/加固 n8n。会自行触发；不属于上述构建流程。

n8n-mcp 工具——从第一轮开始掌握的实用知识

限定名称的格式为 mcp__<server>__<tool>（<server> 通常是 n8n-mcp）。

两个层级，以及如何判断你拥有哪一层。 以下文档和验证工具可离线使用，始终可用。n8n_* 管理工具会连接到实时 n8n 实例，仅在实例连接后才会出现。如果这些工具不存在，并不代表出了问题，也不需要重试——请说明这一点，并告知用户如何修复其安装：

• 托管（https://api.n8n-mcp.com/mcp）——首次使用时通过客户端的 OAuth 提示登录，然后在控制面板中连接 n8n 实例。配置中无需环境变量或 API 密钥。
• 自托管（npx n8n-mcp、Docker）——服务器环境中需要设置 N8N_API_URL 和 N8N_API_KEY，并在客户端启动前导出这些变量。

n8n_health_check 用于确认连接正常，并返回解析出的实例。

发现与文档

• tools_documentation——所有工具的元文档；使用 {topic, depth:"full"}，并搭配 ai_agents_guide 或（n8n-mcp 2.97+）expression_helpers。
• search_nodes——按关键词查找节点。
• get_node——获取节点信息。接受一个简写格式的 nodeType（nodes-base.httpRequest、nodes-langchain.agent），以及 detail（minimal/standard/full）和 mode（info/docs/search_properties/versions）。
• validate_node——单独验证一个节点的配置（配置档：minimal/runtime/ai-friendly/strict）。
• search_templates / get_template——模板库（按关键词、节点、任务、元数据搜索）。 构建与编辑
• n8n_create_workflow — 从完整工作流 JSON 创建。
• n8n_update_partial_workflow — 增量差异操作（{id, operations:[…]}）：addNode、updateNode、patchNodeField、addConnection、setNodeGroups、activateWorkflow 等。编辑时优先使用。
• 画布分组（n8n 2.28+）会在编辑后保留；调整情况会显示在 details.warnings 中。使用 setNodeGroups 操作创建或更改分组。参见 n8n-mcp-tools-expert。
• n8n_update_full_workflow — 完整替换。
• n8n_autofix_workflow — 自动修复常见问题。
• n8n_deploy_template — 将模板部署到实例。

验证（必要但不充分——务必同时执行反模式扫描）

• validate_workflow — 输入完整 JSON，输出错误、警告和修复建议。此处的节点类型采用长格式（n8n-nodes-base.set）。
• n8n_validate_workflow — 通过 {id} 验证已部署的工作流（无需检查节点 JSON）。

检查与生命周期

• n8n_get_workflow — 获取工作流（完整／结构／活动／筛选／最简）。编辑后用它验证 connections；mode="filtered" + nodeNames 可读取单个大型节点，而不会拉取整个工作流，以免在客户端被截断。
• n8n_list_workflows — 列出／筛选（复制逻辑前先搜索）。
• n8n_delete_workflow；n8n_workflow_versions（历史记录／回滚／差异；source: "native" 包含 UI 编辑）；n8n_instances（仅适用于多实例账户；每个 n8n 工具也都接受单次调用的 instance 名称——参见 n8n-multi-instance）；n8n_health_check（已解析的 instanceName，以及 officialMcp：下方的实例级服务是否可访问）。

测试与运行

• n8n_test_workflow — 运行真实节点（Code、HTTP、数据库写入、发送操作都会实际执行）。存在副作用时，运行前先询问用户。method 用于选择执行路径：auto（默认）和 trigger 会通过 HTTP 触发活动工作流中的 webhook／表单／聊天触发器；prepare／pinned／direct 会通过 n8n 自身的 MCP 服务运行工作流，无需 HTTP 触发器（Manual、Schedule、子工作流）——参见 n8n-mcp-tools-expert。
• n8n_executions — 列出／检查执行记录。没有 execute_workflow 工具。
• n8n_evaluations — 评估运行、指标和逐个案例结果（n8n ≥ 2.30）；run／cancel（≥ 2.32）。run 会在整个数据集上运行真实节点，因此请先询问用户。遇到 403 时，参见 n8n-mcp-tools-expert。

数据、文件夹、凭据、审计

• n8n_manage_datatable — Data Table 的 CRUD、筛选和试运行。addColumn／deleteColumn／renameColumn 可通过 n8n 的 MCP 服务更改现有表的列（Public API 无法做到）；deleteColumn 会同时删除该列中的值。
• n8n_manage_folders — 文件夹 CRUD（n8n ≥ 2.19）。使用 parentFolderId 或 moveToFolder 操作放置工作流；通过文件夹的 get 计数进行验证，而不是通过工作流。若 delete 不带 transferToFolderId，文件夹中的工作流将被归档。参见 n8n-mcp-tools-expert。
• n8n_manage_credentials — 凭据 CRUD + getSchema 发现。
• n8n_audit_instance — 安全审计（硬编码密钥、未经身份验证的 webhook、错误处理缺失）。 实例级 MCP 服务 — Public API 旁边的第二个端点，由 N8N_MCP_ACCESS_TOKEN 控制访问权限（n8n 2.34+）。n8n_health_check 会报告它是否可访问；如果未配置，此处的调用会返回 NOT_CONFIGURED。
• n8n_manage_agents — 已持久化的 n8n Agents：具有独立生命周期（模型、指令、技能、任务、记忆、频道）的独立助手实体，不是 AI Agent 工作流节点。call 会使用真实凭据实时运行它，并可能返回 approvals[]；只有用户提出要求时才使用 publish。请参阅 n8n-agents。
• n8n_explore_node_resources — 通过真实凭据解析节点的实时下拉列表／资源定位器值，而不是猜测 ID。请参阅 n8n-node-configuration。
• n8n_list_catalog — 列出 projects（以获取 projectId）或 tags。这是此处唯一无需令牌也能使用的工具。
• 同一服务还支持 n8n_test_workflow 的 prepare／pinned／direct、source: "native" 版本以及 Data Table 列操作，并按工作流控制访问：WORKFLOW_NOT_EXPOSED 表示“Available in MCP”已关闭；开启它（exposeToMcp: true）会产生持久性更改——请先询问用户。

节点类型格式陷阱：get_node／validate_node 使用短格式（nodes-base.set）； validate_workflow／n8n_create_workflow 中的工作流 JSON 使用长格式 （n8n-nodes-base.set）。混用是常见且不易察觉的错误——请参阅 n8n-mcp-tools-expert。

协议步骤

1. 从索引中找到匹配的技能，并在首次 MCP 调用前调用该技能。
2. 每个会话开始时浏览一次 tools_documentation，如果不确定工具范围，就借此更新了解。
3. 配置任何节点前先调用 get_node——读取实时架构，不要想当然。
4. 构建／编辑后，激活前先调用 validate_workflow，然后调用 n8n_get_workflow 检查 connections。
5. 指出你发现的任何差异（缺少的工具、变更的参数、行为不一致）。

不确定时

• 找不到用户在 UI 中创建的工作流？ 最常见的原因是该工作流的 MCP 访问权限已关闭。请让用户在 n8n 中打开该工作流，进入 Settings，并启用 MCP 访问权限。
• 用户说有问题？ 相信他们。根据 get_node 重新检查参数、追踪数据引用，并检查执行情况。请参阅 n8n-validation-expert。
• 没有适用的技能，且任务并非简单任务？ 先询问，不要猜测。

这些是有主见的最佳实践，并非铁律。不同意某项调用？这都是 Markdown——编辑该技能即可。