n8nctrl

<p align="center"> <img src="docs/assets/n8nctrl-social-preview.jpg" alt="n8nctrl banner" width="900"> </p> <h1 align="center">n8nctrl</h1> <p align="center"> <strong>适用于 n8n 的操作员控制命令行界面，带有用于 AI 客户端的 MCP 适配器。</strong> </p> <p align="center"> <a href="https://lidless.dev/n8n-ops-mcp"><strong>网站和文档 &rarr; lidless.dev/n8n-ops-mcp</strong></a> </p> <p align="center"> <img src="https://shieldcn.dev/github/ci/lidless-labs/n8nctrl.svg?branch=main&workflow=ci.yml" alt="CI"> <img src="https://shieldcn.dev/npm/v/n8n-ops-mcp.svg" alt="npm 版本"> <img src="https://shieldcn.dev/github/license/lidless-labs/n8nctrl.svg" alt="许可证"> </p> **n8nctrl 是适用于 [n8n](https://n8n.io) 工作流自动化的操作员控制命令行界面。** 它通过 n8n 公共 API 列出、检查、验证、审计和报告您的 n8n 工作流和执行情况，以便您可以询问“今天我的 n8n 出现了什么问题？”并根据终端、cron、CI 或代理的答案采取行动。与编目/文档工具不同，这些工具索引 n8n 的节点库以构建流程，而 n8nctrl 旨在用于操作您已经运行的流程：处理失败的执行、查找偏移、扫描安全风险以及检查实时计划、Webhook、凭据元数据和标签。 MCP 接口是适配器层：运行 `n8nctrl mcp` 以获取标准输入/输出 MCP，或者在现有的启动器中使用兼容的 `n8n-ops-mcp` 二进制文件。同一软件包还附带了一个一流的 [OpenClaw](https://github.com/openclaw/openclaw) 插件。它与 Claude Desktop、Claude Code、Codex CLI、Cursor、Windsurf 或任何其他 MCP 主机配合使用，对特定的模型或代理程序没有硬依赖。 ## 它能做什么 n8nctrl 将操作员和代理连接到正在运行的 n8n 实例，以实现 **工作流自动化运维**：它通过 n8n 公共 API 显示您的 n8n 工作流、执行、计划、Webhook、标签和凭据。从命令行界面，您可以获得用于 shell、cron 和 CI 的可脚本化读取/报告命令。通过 `n8nctrl mcp` 或兼容的 `n8n-ops-mcp` 二进制文件，您的代理可以本地感知您的 n8n 运行状况，因此它可以回答“我的 n8n 出现了什么问题？”，从聊天中触发工作流，审计安全风险，或在不离开客户端的情况下清理旧执行。 读取工具始终可用。写入工具（创建、保存、存档、删除、触发、重试、标签 CRUD、固定数据）除非 `N8N_ENABLE_EDIT=true`，否则隐藏，凭据写入位于第二个门后。破坏性操作由确认门控，并首先快照到备份目录。请参阅 [安全模型](#security-model)。 ## 安装 ```bash npm install -g n8n-ops-mcp ``` npm 软件包名称仍为 `n8n-ops-mcp` 以保持兼容性。全局安装后，使用标准命令行界面作为 `n8nctrl`。现有的 `n8n-ops` 和 `n8n-ops-mcp` 启动器仍作为兼容别名受支持。 对于 MCP 启动器，您可以通过 `npx -y n8n-ops-mcp` 按需运行它（无需全局安装），这是以下 MCP 客户端配置所使用的。 ## 试用：MCP 客户端配置 将以下内容放入您的 MCP 客户端配置中（以 Claude Desktop 为例）。二进制文件直接从 npm 运行，因此无需事先安装： ```json { "mcpServers": { "n8n": { "command": "npx", "args": ["-y", "n8n-ops-mcp"], "env": { "N8N_BASE_URL": "https://n8n.example.com", "N8N_API_KEY": "your-n8n-api-key" } } } } ``` 在 n8n 的 **设置 &rarr; API** 下生成 API 密钥。将 `N8N_BASE_URL` 指向您的 n8n 实例。这就是整个只读设置。要解锁写入工具，请在 `env` 中添加 `"N8N_ENABLE_EDIT": "true"`。 然后询问您的代理： > 今天有哪些 n8n 工作流出现了问题？ 它调用 `n8n_list_executions` 并带有 `status=error`，然后在失败的运行中调用 `n8n_get_execution` 以获取每个节点的日志和原始错误。 ## 工具 40种工具涵盖只读操作、工作流 + 执行生命周期、标签和凭证。写入工具（标记为✓）默认隐藏，除非设置`N8N_ENABLE_EDIT=true`；凭证写入（标记为✓✓）需要第二重确认。 | 工具 | 用途 | 写入 | |---|---|---| | `n8n_list_workflows` | 列出工作流，按 `active` / `tags` / `name` 过滤 | | | `n8n_get_workflow` | 获取一个工作流，可选地获取完整的节点图 | | | `n8n_list_executions` | 列出最近的执行记录，按工作流 / 状态过滤 | | | `n8n_get_execution` | 获取一个执行记录，包含每个节点的运行日志和原始错误信息 | | | `n8n_search_executions` | 文本搜索最近的执行记录，查找错误片段 | | | `n8n_list_webhooks` | 列出 webhook 和表单触发器的 URL | | | `n8n_validate_workflow` | 静态检查：废弃的节点、旧版 Code 节点 API、孤立节点 | | | `n8n_diff_workflow` | 比较工作流与快照文件或内联对象 - 语义差异（添加/删除/修改的节点及其字段路径） | | | `n8n_list_schedules` | 列出每个工作流中的计划触发器，附带人类可读的描述 | | | `n8n_audit_browser_bridge_usage` | 查找调用 `browser-bridge` CLI 的工作流 | | | `n8n_scaffold_browser_bridge_node` | 生成一个可粘贴的 n8n 节点，调用 `browser-bridge <platform> <action>` | | | `n8n_run_audit` | 运行 n8n 内置的安全审计（凭证、数据库、节点、文件系统、实例） | | | `n8n_find_workflows_using_node_type` | 查找使用给定节点类型的所有工作流 | | | `n8n_execution_stats` | 工作流的最近窗口统计：计数、失败率、平均和 95% 运行时间、最后失败 | | | `n8n_list_tags` | 列出工作流标签，包含 `id`、`name`、`createdAt`、`updatedAt` | | | `n8n_get_workflow_tags` | 读取当前附加到工作流的标签 | | | `n8n_list_credentials` | 列出凭证（仅限元数据 - 绝密不回显；需要管理员/所有者密钥） | | | `n8n_get_credential_schema` | 获取凭证类型的 JSON 模式 | | | `n8n_find_workflows_using_credential` | 查找引用凭证的工作流节点 | | | `n8n_check_disabled_nodes` | 扫描工作流中的 `disabled: true` 节点 | | | `n8n_trigger` | 通过 webhook 或工作流 ID 运行工作流 | ✓ | | `n8n_create_workflow` | 创建工作流（写入确认；支持 dry-run 预览） | ✓ | | `n8n_activate` | 启用工作流的触发器 | ✓ | | `n8n_deactivate` | 禁用工作流的触发器 | ✓ | | `n8n_save_workflow` | 覆盖工作流，自动备份和确认 | ✓ | | `n8n_archive_workflow` | 软删除工作流（确认；可逆） | ✓ | | `n8n_unarchive_workflow` | 恢复已归档的工作流（不重新激活） | ✓ | | `n8n_delete_workflow` | 永久删除工作流（确认；快照删除） | ✓ | | `n8n_cancel_execution` | 通过 ID 停止正在运行或等待的执行 | ✓ | | `n8n_retry_execution` | 重试失败的执行（返回新的执行） | ✓ | | `n8n_delete_execution` | 永久删除执行记录（确认；不可逆） | ✓ | | `n8n_delete_executions` | 批量删除执行记录（确认；不可逆） | ✓ | | `n8n_pin_node_data` | 将样本数据固定到节点，使下游节点在测试期间使用它 | ✓ | | `n8n_unpin_node_data` | 清除节点上固定的数据 | ✓ | | `n8n_create_tag` | 创建工作流标签（确认；可逆） | ✓ | | `n8n_delete_tag` | 永久删除标签（确认；级联删除） | ✓ | | `n8n_set_workflow_tags` | 替换工作流上的标签集 | ✓ | | `n8n_retry_executions` | 批量重试执行（确认；最多 50 个 ID） | ✓ | | `n8n_create_credential` | 创建凭证（确认；**双重确认**） | ✓✓ | | `n8n_delete_credential` | 永久删除凭证（确认；**双重确认**） | ✓✓ | 写入工具默认隐藏，除非设置`N8N_ENABLE_EDIT=true`。 <details> <summary><b>详细工具参考</b></summary> **`n8n_list_workflows`** - 按 `active`、`tags`、`name`（子字符串）、`limit` 过滤。返回 `id`、`name`、`active` 状态、`tags`、`updatedAt`。 **`n8n_get_workflow`** - 通过 `id` 获取。默认返回元数据，传递 `includeDefinition: true` 获取完整的节点图和连接。 **`n8n_list_executions`** - 按 `workflowId`、`status`（成功/错误/运行中/等待中/取消）、`limit` 过滤。返回 `id`、`workflowId`、`workflowName`、`status`、`mode`、`startedAt`、`stoppedAt`。 **`n8n_get_execution`** - 包含每个节点的运行日志（截断为 `maxExecutionLogBytes`，默认为 64 KB）和原始错误对象。传递 `includeRunData: false` 跳过运行日志。 **`n8n_search_executions`** - 默认扫描 `status=error` 执行记录的 `query` 片段（例如 `ECONNREFUSED`），返回匹配项及其工作流上下文和每个命中周围的片段。`scope: "error"`（默认）仅 grep 错误负载；`scope: "all"` 还 grep 完整的节点运行数据（较慢，可能返回节点输出 - 将片段视为敏感信息）。可选 `workflowId`、`status`、`limit`（默认 50，最大 250）、`maxMatches`（默认 20）、`snippetChars`（默认 160）。返回 `matches` 和 `skipped` 数组。 **`n8n_list_webhooks`** - 扫描工作流中的 webhook 和表单触发节点，返回其路径和完全形成的 `triggerUrl`。与 `n8n_trigger` 模式 `webhook` 配对。可选 `workflowId`、`activeOnly`（默认 `true`）、`limit`（默认 50）。 **`n8n_validate_workflow`** - 检查废弃的节点类型、旧版 Code 节点 API、`$node[]`、`items` 全局变量、`require()`、孤立节点、禁用节点、缺失触发器。返回问题及其严重性（错误/警告/信息）以及汇总计数。 **`n8n_list_schedules`** - 扫描 `n8n-nodes-base.scheduleTrigger` 和旧版 `n8n-nodes-base.cron` 节点，跨工作流解码每个间隔规则为人类可读的字符串。回答“什么在 3 点运行？”而无需点击 n8n UI。支持规则字段：`seconds` / `minutes` / `hours` / `days` / `weeks` / `months`（带有 `triggerAtHour`、`triggerAtMinute`、`triggerAtDay`、`triggerAtDayOfMonth`）和原始 `cronExpression`。每个间隔有一条记录 - 多间隔规则发出多行。每行包括 `workflowId`、`workflowName`、`active`、`nodeName`、`nodeType`、`schedule`、`field`，可选 `cronExpression` 和原始 `raw` 规则以供进一步检查。可选 `workflowId`（单个工作流扫描）、`activeOnly`（默认 `true` - 非活动计划不会触发）、`limit`（默认 100，最大 250）。 **`n8n_diff_workflow`** - 比较工作流的当前状态与快照。传递 `id` 和 `snapshotPath` 或 `snapshot`（内联对象）。`snapshotPath` **仅限于配置的 `backupDir`**（默认 `~/.n8n-backups`）：可以相对或绝对给出路径，但任何解析到 `backupDir` 外部的路径（包括 `..` 遍历）都会被拒绝。 这可以防止该工具被用作任意文件读取原始工具，即使它在没有 `enableEdit` 的情况下可用。快照接受两种格式：`n8n_save_workflow` / `n8n_delete_workflow` 编写的平面备份和嵌套的 `n8n_get_workflow(includeDefinition=true)` 形状（图数据在 `definition` 下）。返回 `summary`（计数：添加/删除/修改/名称更改/连接更改/设置更改）和 `diff`，包含每个节点的 `fieldsChanged` 路径（例如 `parameters.command`、`parameters.url`、`disabled`）。节点匹配分为两步：首先按 `id`，然后按名称回退以匹配未匹配的节点 - 处理旧版/手动编辑的快照。默认情况下，抑制 космети 更改（`position`、`webhookId`）；传递 `ignoreCosmetic: false` 以显示它们。每个节点的详细信息上限为 `maxModifiedDetails`（默认 50，最大 500）；`summary.nodesModified` 计数器无上限，`diff.nodesModifiedTruncated: true` 标志显示何时剪辑了详细信息。只读。 **`n8n_audit_browser_bridge_usage`** - 扫描每个工作流中调用 `browser-bridge` CLI 的节点。检查 `command`（执行命令 + SSH 节点）和 `jsCode` / `pythonCode` / `functionCode`（代码 + 旧版函数节点）。启发式：`\bbrowser-bridge\.[cm]?js` 后跟两个 kebab-slug 参数；裸二进制形式不被检测以避免类似 `cd /opt/browser-bridge` 的路径提及。返回每个 `(workflowId, nodeName, platform, action)` 的一个发现结果 + 平台×操作计数。可选 `platform`、`action`、`activeOnly`（默认 `false`）、`includeArchived`（默认 `false`）、`maxWorkflows`（默认 250，最大 1000）、`concurrency`（默认 3，最大 8）。只读。与 `n8n_scaffold_browser_bridge_node` 配对使用时，您需要添加另一个调用。配套仓库：[browser-bridge](https://github.com/lidless-labs/browser-bridge). **`n8n_scaffold_browser_bridge_node`** - 纯本地生成器（无需 n8n API 调用）。给定 `platform`、`action`、可选 `input` JSON 和 `mode: "code-node" | "execute-command"`（默认 `code-node`），会发出一个可粘贴的 n8n 节点 JSON，它镜像 `browser-bridge` 的 `docs/n8n-usage.md` 模式。代码节点使用 `spawnSync` 带有 stdin JSON 并显示 `payload.exitCode` + `stderr`，以便下游节点可以分支 `ok`。执行命令节点使用引用的 `<<'JSON'` heredoc，以便输入数据不被破坏。可选 `bridgeDir`、`nodeName`、`position`。平台/操作被验证为 kebab-slug - 保持它们安全地插值到 shell 命令中。当使用非空 `input` 使用 `execute-command` 时发出警告（heredoc 构建 JSON；没有每个项目上游线路）。 **`n8n_trigger`** - **写入工具**（除非启用 `enableEdit` 否则隐藏）；需要 `confirm: true`。触发运行工作流的节点（代码 / 执行命令 / HTTP 等）并 POST 到 webhook，所有这些都可能产生任意的现实世界副作用，因此它与所有写入工具一样位于同一个编辑门后，并且如果没有 `confirm: true` 则拒绝。`webhookPath` 在客户端验证：它必须解析到 `/webhook`、`/webhook-test` 或 `/form` 下的路径，没有 `..` 遍历或方案相对 `//host` 形式，因此混淆的代理无法将调用重定向到基本 URL 之外。两种模式： - `mode: "webhook"` + `webhookPath` - POST（或 GET/PUT/DELETE）到配置的基本 URL + 路径，并带有可选的 JSON `payload`。这是可靠的路径。 - `mode: "workflow"` + `workflowId` - 尝试 `POST /api/v1/workflows/:id/execute`。预检查工作流是活动状态并且有 webhook / 手动 / 表单触发。大多数 n8n 构建此端点不公开且会 405；该工具显示提示切换到 webhook 模式。 **`n8n_create_workflow`** - `POST /workflows`。从结构化工作流 JSON 创建：`name`、`nodes`、`connections`，可选 `settings` / `staticData`。还接受 `n8n_get_workflow`（带有 `includeDefinition=true`）和备份快照的完整输出。剥离只读字段（`id`、`active`、`createdAt`、`updatedAt`、`isArchived`、`versionId`、`triggerCount`、`tags`、`shared`、`meta`、`pinData`）后 POST - n8n 强制执行 `additionalProperties: false` 工作流模式， 400时会报错。运行 `n8n_validate_workflow` 作为预检查；错误阻止，警告通过（传递 `skipValidation: true` 跳过）。可选 `dryRun:true` 返回清理后的 POST 正文和验证问题，无需写入（无需 `confirm` 写入）。可选 `projectId` 和 `folderId` 作为创建目标查询参数。需要 `confirm: true` 实际写入 - 工具接受任意 `nodes` 图表将在服务器上生效，因此未经确认的调用（无 `dryRun`）返回 `ok: false` 且永远不会触及 API。新工作流创建后为 INACTIVE；调用 `n8n_activate` 之后如果您想要触发器运行。这是 `n8n_delete_workflow` 快照的主要恢复路径：读取备份文件到 `definition` 并调用此工具。恢复的工作流获得新的 ID。 **`n8n_activate`** / **`n8n_deactivate`** - 幂等；两者都需要 `confirm: true`。激活使工作流的触发器生效，因此其节点可以自动运行（有效地启用任意代码执行）；停用会阻止自动化。停用不会取消正在运行的执行。 **`n8n_save_workflow`** - 写入之前：获取当前版本，将快照写入 `backupDir` 为 `<id>-<timestamp>.json`（模式 0600），对建议的状态运行 `validateWorkflow`，在错误严重问题时中止（传递 `skipValidation: true` 跳过）。需要 `confirm: true` 实际 PUT；调用 `confirm: false` 返回 `ok: false` 且永远不会触及 API（省略 `confirm` 在 MCP 模式层被拒绝）。响应包括备份路径和 `restoreHint`。 **`n8n_archive_workflow`** - `POST /workflows/{id}/archive`。软删除工作流：触发器停止触发，工作流从默认 UI 列表中消失，但定义和执行历史记录被保留。幂等（归档已归档的工作流返回当前状态）。需要 `confirm: true`（它停活和删除工作流）。停用会使触发器停止触发。 **`n8n_unarchive_workflow`** - `POST /workflows/{id}/unarchive`。恢复已归档的工作流。不会重新激活 - 触发器保持关闭，直到您显式调用 `n8n_activate`。返回 `ok: false` 与 `reason: "not_found"` 在 404。 **`n8n_delete_workflow`** - `DELETE /workflows/{id}`。永久的，不可逆转的。删除前：获取当前工作流并将其快照到 `backupDir` 为 `<id>-DELETED-<timestamp>.json`（模式 0600）。如果无法写入快照，DELETE 操作将被中止 - 没有不安全保护的路径。需要 `confirm: true`；省略它或传递 `false` 返回 `ok: false` 且永远不会触及 API。返回 `ok: false` 带有 `reason: "not_found"` 在 404（删除前后）。 **请通过 `n8n_create_workflow` 快照内容恢复**；恢复的工作流获得新的 ID 且被创建为非活动状态。删除 **不会** 取消正在运行的执行 - 如果需要，请先使用 `n8n_list_executions(workflowId, status='running')` + `n8n_cancel_execution`. **`n8n_cancel_execution`** - `POST /executions/{id}/stop`。在 `n8n_search_executions` 定位卡住的运行后关闭诊断循环。返回执行最终状态的成功摘要，或如果 ID 不再匹配正在运行的执行（404），则返回 `ok: false` 带有 `reason: "not_found_or_finished"`。 **`n8n_retry_execution`** - `POST /executions/{id}/retry`。创建一个新的执行 - 响应显示 `originalExecutionId` 和 `newExecutionId`，以便代理可以使用 `n8n_get_execution` 跟进重试。可选 `loadWorkflow: true` 重试针对当前保存的工作流，而不是在原始执行时间捕获的版本。返回 `ok: false` 带有 `reason: "not_found"` 在 404 或 `reason: "not_retryable"` 在 409（例如仍在运行）；所有其他 API 错误都会重新抛出。 **`n8n_delete_execution`** - `DELETE /executions/{id}`。永久删除执行记录：日志、每个节点的运行数据和错误有效载荷将从 n8n 中删除。需要 `confirm: true` 实际删除；调用 `confirm: false` 返回 `ok: false` 且永远不会触及 API（省略 `confirm` 在 MCP 模式层被拒绝）。返回 `ok: false` 带有 `reason: "not_found"` 在 404；所有其他 API 错误都会重新抛出。 从代理的角度来看，这不是幂等的：记录在第一次成功调用后消失，因此如果您稍后可能需要它，请先获取 `n8n_get_execution`. **`n8n_pin_node_data`** - 将样本数据固定到节点，以便下游节点在测试/开发期间使用它而无需重新运行上游节点。自然与 `n8n_scaffold_browser_bridge_node` 配对：搭建 browser-bridge 调用，运行一次，捕获输出，固定它，然后在下游节点上迭代，而无需重新生成 browser。可输入：`id`、`nodeName`（区分大小写，必须匹配现有节点）、`data`（1-50 项；原始对象自动包装成 `{json: <object>`，已经 `{json: ..., binary?: ...}` 形状的项不做修改）、可选 `merge: true` 追加现有固定数据而不是替换（合并仍限制在 50 项）。`confirm: true`。PUT `/workflows/{id}` 问题带有合并的 `pinData` 加上现有的节点/连接/设置/静态数据（因此 PUT 不会清除它们）。固定的数据在执行之间持续存在，直到清除 - 容易忘记；响应包含一个 `unpinHint`. </details> 以下是翻译后的文档： **`n8n_unpin_node_data`** - 清除一个节点（当提供 `nodeName` 时）或整个工作流（当省略时）中固定的数据。幂等：清除未固定的节点会返回 `ok: true` 和 `noop: true`，并且永远不会触及 API。当清除实际发生时，PUT 包含工作流体的其余部分，因此其他字段不会被清空。需要 `confirm: true`。 **`n8n_delete_executions`** - 批量删除表单。客户端分发到 `DELETE /executions/{id}`，具有有限的并发性（默认为 3，最大 10）。接受一个 `ids` 数组（在分发前去重，最大 50），需要 `confirm: true`。响应包括 `requested`/`attempted`/`deleted`/`alreadyDeleted`/`failed`/`skipped`/`aborted` 计数器，以及一个 `results: Array<{id, ok, reason?, message?}>` - 顺序是完成顺序，而不是输入顺序，因此按 ID 查找。404 被视为 `already_deleted`（幂等）。任何 ID 上的 5xx 错误都会通过 `AbortController` 终止批次：不再领取新的 ID，并且任何已经在进行的 `fetch` 操作都会在客户端取消。在并发性 N 下，可能已经有高达 N-1 个删除操作已经到达服务器，然后再观察到 5xx 错误，因此批次是尽力而为的，而不是事务性的 - 清除信号服务器有问题；不要盲目重试。每个 ID 的错误消息都通过 API 密钥过滤器传递。 与 `n8n_search_executions` 组合，删除已知的一组嘈杂运行。 **`n8n_retry_executions`** - 重试的批量表单。与 `n8n_delete_executions` 具有相同的分发形状：有限的并发性（默认为 3，最大 10），最大 50 个 ID，5xx 错误时 `AbortController`，结果按完成顺序排列。 **区别在于两种方式：** 404 对于每个 ID 都是 `{ ok: false, reason: "not_found" }`（非幂等 - 缺失的执行是一个需要暴露的真正故障），并且每个成功的重试都会创建一个新的执行，其 ID 在每一行中作为 `newExecutionId` 返回。计数器：`requested`/`attempted`/`retried`/`notFound`/`failed`/`skipped`/`aborted`。可选 `loadWorkflow: true` 重试每个 ID 针对当前保存的工作流，而不是捕获的版本。确认门控 - 每个重试都会再次运行工作流，并可能重新触发副作用（HTTP 调用，DB 写入）；在确认之前验证工作流是否安全重新运行。 **`n8n_run_audit`** - `POST /audit`。运行 n8n 内置的安全审计，并为每个请求的类别返回一份风险报告： **credentials** （未使用/废弃）， **database** （查询节点中容易受到 SQL 注入攻击的表达式）， **nodes** （社区/非官方节点）， **filesystem** （节点访问主机文件系统）， **instance** （不安全的服务器设置）。每个报告都有 `risk`，`sections` （带有 `title`/`description`/`recommendation`/`location`）。该工具还会显示一个扁平的 `reports` 数组，包含每个报告的 `sectionCount`/`locationCount`，以便代理可以决定深入检查哪些内容。可选 `categories` （省略所有五个）和 `daysAbandonedWorkflow` （n8n 默认 90）。只读 - n8n 只检查，从不修改。 **需要 API 用户是实例管理员或所有者** （n8n 的审计端点强制执行此操作）。 **`n8n_find_workflows_using_node_type`** - 组合只读扫描器。遍历每个工作流（分页，最大 `maxWorkflows`，默认为 250，最大 1000），并为匹配请求类型的节点发出一个匹配结果。`match: "exact"` （默认）是 `node.type` 的完整字符串相等；`match: "contains"` 是不区分大小写的子字符串（适用于“基本包和社区包中的所有 Slack 节点”）。可选 `activeOnly` （默认 false），`includeArchived` （默认 false），`includeDisabledNodes` （默认 true - 禁用节点是常见的漂移信号，值得暴露），`concurrency` （默认 3，最大 8）。返回每个节点的 `findings` 和每个工作流的 `summary`，按匹配计数降序排列。每个工作流的获取错误放在 `fetchErrors` 中，而不是使整个扫描失败。与 `n8n_audit_browser_bridge_usage` （调度驱动浏览器桥调用？）和 `n8n_run_audit` （哪些废弃节点需要替换？）配对。 **`n8n_execution_stats`** - 组合只读聚合器，基于 `n8n_list_executions`。每个工作流的计数（总/成功/错误/取消/运行/等待/其他），故障率（`error / (success + error + canceled)`），已完成执行的平均 + p95 运行时，以及 `lastFailureAt` / `lastSuccessAt`。可选 `workflowId` （单个工作流统计），`sinceHours` （默认 24，最大 168 = 7d），`maxExecutions` （默认 1000，最大 5000），`pageSize` （默认 250）。分页在第一个执行时间超过窗口或达到 `maxExecutions` 时停止；`stoppedReason` 是以下之一：`"window"`，`"cap"`，`"exhausted"`。如果 `truncated: true`，增加 `maxExecutions` 或缩小 `sinceHours`。`totals` 对象包括与所有工作流在窗口中滚动的相同计数 + `failureRate`。有助于回答“哪些工作流容易出错？”和“什么运行时间长？”。 **`n8n_list_tags`** - `GET /tags`。返回 `{ data: [{id, name, createdAt, updatedAt}], nextCursor }`。可选 `limit` （默认 100，最大 250）和 `cursor` （来自先前调用的 `nextCursor`）。只读。 **`n8n_get_workflow_tags`** - `GET /workflows/{id}/tags`。返回当前附加的工作流的标签数组。与 `n8n_set_workflow_tags` 配对，进行差异和重新连接流程。 **`n8n_create_tag`** - `POST /tags`。需要 `confirm: true`（与其他修改标签的工具一致）；可以通过 `n8n_delete_tag` 逆转。名称在发送前被修剪。如果 409（已存在此名称的标签），则返回 `ok: false` 和 `reason: "conflict"`；使用 `n8n_list_tags` 查找现有的 ID。 **`n8n_delete_tag`** - `DELETE /tags/{id}`。确认门控。 **级联**：n8n 从它附加到的每个工作流中删除标签。工作流本身不会被删除，只有关联的标签。404 返回 `reason: "not_found"`。要事先查找受影响的工作流，请使用 `n8n_list_workflows(tags=<name>)` 或扫描 `n8n_get_workflow_tags`。 **`n8n_set_workflow_tags`** - `PUT /workflows/{id}/tags`。 **替换** 工作流的标签集（不是追加）- 传送完整所需列表。空 `tagIds: []` 清除所有标签。标签 ID 在发送前被去重。需要 `confirm: true`（可逆）。404 返回 `reason: "not_found"`（工作流 ID 或标签 ID 不存在；验证两者与 `n8n_list_workflows` 和 `n8n_list_tags`）。 **`n8n_list_credentials`** - `GET /credentials`。仅返回元数据 - n8n 的 API 显式排除 `data` 字段（加密机密）从列表响应中，并且工具层在未来回归的情况下防御性地剥离 `data`。每一行： `{id, name, type, createdAt, updatedAt, shared[]}`。可选 `limit` （默认 100，最大 250）和 `cursor`。需要 API 密钥属于实例所有者或管理员 - 非管理员密钥获取 `ok: false, reason: "unauthorized"`，并带有明确的提示。 **`n8n_get_credential_schema`** - `GET /credentials/schema/{credentialTypeName}`。返回描述凭证类型所需 `data` 形状的原始 JSON 架构（例如 `freshdeskApi` → `{ apiKey, domain }` 要求）。在调用 `n8n_create_credential` 之前使用此操作，以便了解要填充哪些字段。404 返回 `reason: "not_found"`；401 返回 `reason: "unauthorized"`。 **`n8n_find_workflows_using_credential`** - 组合扫描器（无直接 n8n 端点）。遍历工作流并检查每个节点的 `credentials` 字段。传递 `credentialId` （确切，首选）或 `credentialName` （不区分大小写的子字符串备用）。为每个 `(workflowId, nodeName, credentialType)` 返回一个匹配结果，以及每个工作流的汇总计数。与 `n8n_audit_browser_bridge_usage` 具有相同的分发形状（有限并发，`fetchErrors` 表示每个工作流的失败，`truncated` 标志，`maxWorkflows` 默认 250）。“我正在轮换 Slack 凭证，我需要在哪些地方更新？” - 在 `n8n_delete_credential` 之前运行此操作以查看影响范围。 **`n8n_check_disabled_nodes`** - 组合扫描器。显示最近工作流中所有 `disabled: true` 的节点。每个 `(workflowId, nodeName, nodeType)` 的一个匹配结果，以及每个工作流的禁用计数，按降序排列。禁用节点是常见的漂移信号（冻结调试，遗忘清理），并且 n8n UI 没有在明显的位置列出它们。与其他扫描器具有相同的分发 + 过滤形状。 **`n8n_create_credential`** - `POST /credentials`。 **双重门控**：需要 `enableEdit` 和 `enableCredentialsWrite`（默认 false）。确认门控。`data` 携带明文机密到 n8n；工具层 **从不** 回显 `data`，即使在错误时 - n8n 400s 带有正文内容被包装成仅状态错误，然后再显示，因此机密不能通过验证消息泄漏。在调用之前：使用 `n8n_get_credential_schema` 学习所需的 `data` 形状。调用后：响应包括 `id`，`name`，`type`，时间戳；无 `data`。 **非幂等** - 调用两次具有相同名称会创建两个凭证。 **`n8n_delete_credential`** - `DELETE /credentials/{id}`。 **双重门控** + 确认门控。 **级联**：引用此凭证的每个工作流将在下一次运行失败 - 先调用 `n8n_find_workflows_using_credential` 以枚举影响范围。404 返回 `reason: "not_found"`。已删除凭证的有效载荷通过工具层回显时，已剥离 `data`。 ## 配置 在 n8n 下生成 API 密钥 **Settings → API**，然后在 MCP 客户端配置中设置这些环境变量： | 变量 | 必需 | 默认值 | 描述 | | --- | --- | --- | --- | | `N8N_BASE_URL` | 是 | - | n8n 基本 URL，例如 `https://n8n.example.com` | | `N8N_API_KEY` | 是 | - | n8n 公共 API 密钥 (`X-N8N-API-KEY`) | | `N8N_ENABLE_EDIT` | 否 | `false` | 暴露写入工具 | | `N8N_ENABLE_CREDENTIALS_WRITE` | 否 | `false` | 第二个门控（在 `N8N_ENABLE_EDIT` 之上）用于 `n8n_create_credential` 和 `n8n_delete_credential`。参见 [安全模型](#security-model)。 | | `N8N_BACKUP_DIR` | 否 | `~/.n8n-backups` | `n8n_save_workflow` 写入预保存快照的位置 | | `N8N_MAX_EXECUTION_LOG_BYTES` | 否 | `65536` | 内联执行日志字节上限 | | `N8N_REQUEST_TIMEOUT_MS` | 否 | `15000` | n8n API 调用的 HTTP 超时 | ## 命令行界面 `n8nctrl` 是标准的只读 **操作控制命令行界面**，适用于 shell、cron 和 CI。它与 MCP 服务器使用相同的 n8n 公共 API，并共享相同的客户端核心，因此代理可以读取的内容，您可以从终端读取。它仅公开只读/报告工具 - 没有创建、保存、存档、删除、取消、重试或触发。 ```bash # 全局安装，标准二进制文件是 `n8nctrl`： n8nctrl workflows list --active n8nctrl workflows get <id> --full n8nctrl workflows validate <id> n8nctrl executions list --status error --since 24 n8nctrl executions search "ECONNREFUSED" --scope all n8nctrl executions stats --since 48 n8nctrl webhooks list n8nctrl schedules list n8nctrl tags list n8nctrl credentials find-usage <credentialId> n8nctrl nodes find n8n-nodes-base.slack --contains n8nctrl nodes check-disabled n8nctrl audit run # 如果后端无法访问，则退出 1（适用于 cron） n8nctrl audit browser-bridge n8nctrl --json tags list # 原始 JSON 用于管道传输 ``` 运行 `n8nctrl help` 获取完整的命令和标志列表。 使用与 MCP 服务器相同的 `N8N_BASE_URL` / `N8N_API_KEY` 环境变量进行配置（参见上表）。退出代码：`0` 成功，`1` 运行时错误（后端无法访问或调用失败），`2` 用法错误（未知命令/标志或错误值）。 ### 启动 MCP 适配器 `n8nctrl mcp` 启动标准输入/输出 MCP 适配器。`n8n-ops-mcp` 二进制文件保留对现有 MCP 客户端配置和软件包启动器的支持。如果启动器直接引用构建文件路径 `dist/mcp-server.js`，请指向 `dist/mcp-bin.js`（或 `dist/cli.js mcp`）；使用 `n8n-ops-mcp` 二进制文件名的启动器无需更改。 ### 克劳德桌面 添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `%APPDATA%\Claude\claude_desktop_config.json` （Windows）： ```json { "mcpServers": { "n8n": { "command": "npx", "args": ["-y", "n8n-ops-mcp"], "env": { "N8N_BASE_URL": "https://n8n.example.com", "N8N_API_KEY": "your-api-key-here" } } } } ``` ### 克劳德代码 ```bash claude mcp add n8n \ --env N8N_BASE_URL=https://n8n.example.com \ --env N8N_API_KEY=your-api-key-here \ -- npx -y n8n-ops-mcp ``` 添加 `--scope user` 以使其在任何目录中可用，而不仅仅是当前项目。 ### Codex CLI ```bash codex mcp add n8n \ --env N8N_BASE_URL=https://n8n.example.com \ --env N8N_API_KEY=your-api-key-here \ -- npx -y n8n-ops-mcp ``` 写入条目到 `~/.codex/config.toml` 下的 `[mcp_servers.n8n]`。使用 `codex mcp list` 验证。 ### 曲线/风潮/其他MCP主机 任何接受stdio命令 + 环境变量的MCP兼容客户端都可以工作。将它指向 `npx -y n8n-ops-mcp`（或全局安装的 `n8n-ops-mcp`二进制文件）以及环境中的 `N8N_BASE_URL` 和 `N8N_API_KEY`。 <details> <summary><b>赫尔墨斯代理</b></summary> [赫尔墨斯代理](https://github.com/NousResearch/hermes-agent) 从 `~/.hermes/config.yaml` 读取MCP配置： ```yaml mcp_servers: n8n: command: "npx" args: ["-y", "n8n-ops-mcp"] env: N8N_BASE_URL: "https://n8n.example.com" N8N_API_KEY: "your-api-key-here" ``` 然后从会话内重新加载： ``` /reload-mcp ``` </details> ### 开放利爪（第一类插件） n8nctrl 作为 `n8n-ops-mcp` 包的第一类 OpenClaw 插件提供 - 不是 MCP 桥接器，因此它与网关共享进程、身份验证配置文件和钩子。 ```bash openclaw plugins install clawhub:n8n-ops-mcp ``` 将配置块添加到 `~/.openclaw/openclaw.json`： ```json { "plugins": { "entries": { "n8n": { "enabled": true, "config": { "baseUrl": "https://n8n.example.com", "enableEdit": false } } } } } ``` 将 API 密钥放入 OpenClaw 工作区环境变量中： ```bash # ~/.openclaw/workspace/.env N8N_API_KEY=your-api-key-here ``` 重启网关： ```bash systemctl --user restart openclaw-gateway ``` 配置键：`baseUrl`，`apiKey`，`apiKeyEnv`，`enableEdit`，`enableCredentialsWrite`，`maxExecutionLogBytes`，`requestTimeoutMs`，`backupDir`。参见 [`openclaw.plugin.json`](./openclaw.plugin.json) 获取完整模式，[安全模型](#security-model) 获取双门控写入设计。 <details> <summary><b>OpenClaw - 手动（非 ClawHub）安装</b></summary> 如果您想将 OpenClaw 指向本地克隆而不是注册表： ```json { "plugins": { "allow": ["n8n"], "load": { "paths": ["/absolute/path/to/n8n-ops-mcp"] }, "entries": { "n8n": { "enabled": true, "config": { "baseUrl": "https://n8n.example.com", "enableEdit": false } } } } } ``` </details> ## 安全模型 两个标志控制写入访问权限，具有刻意的不同爆炸半径： - **`enableEdit`** （默认 `false`）- 暴露工作流 + 执行生命周期写入工具（创建/保存/存档/删除工作流，激活/停用，**触发**，取消/重试/删除执行，固定/取消固定节点数据，标签 CRUD）。`n8n_trigger` 也在此处受到保护：运行工作流执行任意代码/执行命令/ HTTP 节点并发布到 webhook，因此被视为写入。变异工具受到确认保护（包括 `trigger`，`activate`，`deactivate`，`archive`，`create_workflow`，`create_tag` 和 `set_workflow_tags`），破坏性工作流快照到 `backupDir` 首先。只读 `n8n_diff_workflow` 将 `snapshotPath` 读取限制到 `backupDir`，因此不能将其变成任意文件读取原语。 - **`enableCredentialsWrite`** （默认 `false`）- **第二个门控**，在 `enableEdit` 之上，需要公开 `n8n_create_credential` 和 `n8n_delete_credential`。如果代理被过度配置了 `enableEdit`，则无法注入或销毁凭证而无需此单独的配置更改。 两个标志都必须为真，凭证写入才会注册。凭证 **读取** 工具（`list-credentials`，`get-credential-schema`，`find-workflows-using-credential`）和禁用节点扫描器始终可用，无论如何。 为什么凭证需要第二个门控： 1. `create-credential` 是此包中唯一一个代理输入包含明文机密的工具。具有 `enableEdit` 的提示注入或混淆代理不应能够注入凭证。 2. `delete-credential` 会级联 - 引用该凭证的每个工作流将在下一次运行中失败。影响范围比任何单个工作流操作更广泛。 `数据` 防御： - n8n 的 OpenAPI 将 `data` 标记为 `writeOnly` - API 契约将其从每个响应中排除。我们信任但验证：**工具层剥离每个凭证响应中的 `data`，然后显示**，包括成功路径和删除凭证的回声，以便未来的 n8n 回归无法通过我们泄漏机密。 - 在 `create-credential` 错误时，n8n 响应正文（如果验证 400 时可以回显提交的 `data` 片段）被客户端层替换为仅状态错误消息。工具显示 `status` + `path` 仅。测试断言在强制 400 请求正文的任何部分不会到达工具响应。 ## 示例提示 > 今天有哪些 n8n 工作流出了问题？ 调用 `n8n_list_executions`，并使用 `status=error`，然后为失败的运行调用 `n8n_get_execution`。 > 哪个工作流报错为 "ECONNREFUSED"？ 调用 `n8n_search_executions`，并使用 `query: "ECONNREFUSED"`。 > 触发 "nightly intel" 工作流（需要 `N8N_ENABLE_EDIT=true`） 调用 `n8n_list_webhooks` 以查找路径，然后使用 `mode=webhook` 和 `confirm: true` 调用 `n8n_trigger`。 > 什么工作流在凌晨3点运行？ 调用 `n8n_list_schedules`，然后筛选结果以查找描述中包含 "03:00"（或 `cronExpression` 匹配早晨时间）的调度。 > 自从昨天的备份以来，我的 "intel pipeline" 工作流发生了什么变化？ 调用 `n8n_diff_workflow`，并使用 `id` 和 `snapshotPath` 指向备份文件。返回添加/删除/修改的节点及其参数级别的字段路径。 > 审核我的工作流中是否使用过弃用的 Code-node API 调用 `n8n_list_workflows`，然后对每个 ID 调用 `n8n_validate_workflow`，筛选 `code-node-old-node-ref` 和 `code-node-items-global` 警告。 > 本周哪些工作流不稳定？ 调用 `n8n_execution_stats`，并使用 `sinceHours: 168`，然后按 `failureRate` 排序。 > 我正在轮换 Slack 凭证 - 我需要在哪些地方更新？ 调用 `n8n_find_workflows_using_credential`，并使用凭证 ID 来枚举影响范围，然后再进行任何操作。 > 禁用 "experimental-bot" 工作流（需要 `N8N_ENABLE_EDIT=true`） 调用 `n8n_list_workflows`，并使用名称筛选，然后对匹配的 ID 调用 `n8n_deactivate`，并使用 `confirm: true`。 > 终止卡在 ECONNREFUSED 上的执行（需要 `N8N_ENABLE_EDIT=true`） 调用 `n8n_search_executions`，并使用 `query: "ECONNREFUSED"`，然后对匹配结果调用 `n8n_cancel_execution`。 > 清除上周的 noisy test-run 执行日志（需要 `N8N_ENABLE_EDIT=true`） 调用 `n8n_search_executions` 以查找 ID，然后调用 `n8n_delete_executions`，并使用 `confirm: true`，最多可删除 50 个。删除操作不可逆。 > 存档旧的 "staging-bot" 工作流 - 我可能以后会需要它（需要 `N8N_ENABLE_EDIT=true`） 调用 `n8n_list_workflows`，并使用名称筛选，然后对匹配结果调用 `n8n_archive_workflow`，并使用 `confirm: true`。可以通过 `n8n_unarchive_workflow` 恢复（您仍然需要 `n8n_activate`，并使用 `confirm: true` 来重新启用触发器）。 > 删除废弃的 "poc-scraper" 工作流 - 它已经几个月没用了（需要 `N8N_ENABLE_EDIT=true`） 调用 `n8n_list_workflows` 以查找 ID，然后调用 `n8n_delete_workflow`，并使用 `confirm: true`。快照首先存储在 `backupDir` 中；可以通过 `n8n_create_workflow` 恢复。如果要保留原始 ID，请优先使用 `n8n_archive_workflow`。 ## 为什么不使用更大的 n8n MCP 项目？ n8nctrl 设计上故意保持狭窄。它用于操作您已经运行的 n8n，而不是从节点目录创建新的流程。 - 对于索引 n8n 节点库的目录/文档工具，以便代理可以从节点元数据构建新的工作流，请参阅 [n8n-mcp](https://www.npmjs.com/package/n8n-mcp)。当您希望代理了解每种节点类型及其参数时，这就是合适的工具。 - n8nctrl 是合适的工具，当您希望代理或 CLI 回答“什么坏了，什么改变了，什么有风险，什么被调度”针对您的实时实例并对其采取行动：排查失败的执行，与备份进行差异比较，扫描安全性和凭证影响范围，并在明确的、快照写入门控后编辑工作流。 这两个工具互相补充。一个帮助构建；另一个帮助运行。 ## n8nctrl 不是什么 - **不是节点目录或工作流创作助手。** 它不索引 n8n 的节点库或建议节点参数。请使用 [n8n-mcp](https://www.npmjs.com/package/n8n-mcp) 来完成此任务。 - **不是 n8n UI 或其 REST API 的替代品。** 它是 n8n 公共 API 之上的薄、定制的操作层，专注于运维问题和安全写入。 - **不是托管服务。** 没有守护进程，没有遥测。它作为本地 stdio 进程（或进程内 OpenClaw 插件）运行，仅与您配置的 n8n 实例通信。 - **不是凭证提取路径。** 凭证读取仅返回元数据；凭证写入是双重控制的，并且 `data` 从每个响应分支中剥离。请参阅[安全模型](#security-model)。 ## 开发 ```bash npm install npm run dev # tsx on mcp-server.ts (MCP stdio) npm run typecheck npm test # vitest run npm run build # tsup bundle to dist/mcp-server.js npm start # node dist/mcp-server.js (post-build) ``` 或者从源代码安装： ```bash git clone https://github.com/lidless-labs/n8nctrl.git cd n8nctrl npm install npm run build ``` ## 贡献 欢迎提交补丁。请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 以了解什么可以轻松落地，[SECURITY.md](./SECURITY.md) 以了解如何报告漏洞，以及 [Code of Conduct](./CODE_OF_CONDUCT.md)。 ## 更新日志 请参阅 [CHANGELOG.md](./CHANGELOG.md) 以获取完整的版本历史。 ## 许可证 MIT。请参阅 [LICENSE](./LICENSE)。