企业官网建设流程全解析

如何用 n8n-mcp 的 n8n_evaluations 工具运行并读取 n8n 工作流评估测试？

【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp

n8n_evaluations是 n8n-mcp 提供的 MCP 工具，用于对配置了评估触发器（evaluation trigger）的 n8n 工作流做评估测试：触发一次评估运行（run）、取消运行、列出运行记录、读取单次运行的聚合指标，以及逐条拉取每个用例（case）的输入输出与指标。本文给出从触发运行到读取结果的完整操作路径，以及各错误码的判断方法。

该工具有明确的版本与权限前提，先确认再操作：

• n8n 实例版本：读取类动作（list_runs、get_run、list_cases）要求 n8n2.30.0 及以上；run和cancel要求 n8n2.32.0 及以上（触发/取消路由在 2.32 才引入）。
• API key 权限：n8n-mcp 本身需要在配置中提供N8N_API_URL和N8N_API_KEY。key 还需要带testRun相关 scope——读取需要testRun:read/testRun:list，run需要testRun:create，cancel需要testRun:cancel。在这些版本之前创建的 key 会静默缺失这些 scope，必须重建 key。另外，run/cancel还要求 key 的拥有者具备该工作流的workflow:execute项目 scope。
• 工作流配置：工作流必须包含一个已配置好数据集（dataset）的评估触发器，否则run会返回 409。

列出已有的评估运行

先确认工作流下有哪些历史运行，同时验证 key 的读取权限是否配置正确：

n8n_evaluations({ action: "list_runs", workflowId: "abc123" // 替换为你的工作流 ID })

返回结构为{ testRuns, returned, nextCursor, hasMore }，按时间从新到旧排列。可以加status过滤（可选值：new、running、completed、error、cancelled），例如只看已完成的运行：

n8n_evaluations({ action: "list_runs", workflowId: "abc123", status: "completed", limit: 10 })

limit取值范围 1–250，list_runs默认 100；翻页用上一页返回的cursor。

触发一次评估运行

n8n_evaluations({ action: "run", workflowId: "abc123" }) // → { id, status: "new", createdAt }

注意run是异步的：响应只确认运行已创建，此时还没有任何用例开始执行。文档提醒：run会按数据集的每一行执行一次工作流，真实节点会触发（HTTP 调用、数据库写入、消息发送等），LLM 指标调用会产生费用，对较大的数据集尤其如此——开始一次运行前应先确认。

轮询运行状态直到结束

用run返回的id作为runId轮询get_run，直到status变为completed、error或cancelled：

n8n_evaluations({ action: "get_run", workflowId: "abc123", runId: "run456" // 替换为 run 返回的 id })

返回的 run 对象包含{ id, status, runAt, completedAt, metrics, errorCode, errorDetails, finalResult, testCaseCount, createdAt, updatedAt }。判断运行结果的依据：

• status：终态为completed、error、cancelled；
• finalResult：运行完成后为success、error或warning；
• metrics：跨所有用例聚合的扁平键值表（指标名 → 数值/布尔值），包含自定义指标和 n8n 自动产生的指标（promptTokens、completionTokens、totalTokens、executionTime）。对比同一工作流不同次运行的metrics，可以用来发现提示词或模型变更引入的回退。

读取逐条用例结果

n8n_evaluations({ action: "list_cases", workflowId: "abc123", runId: "run456" })

返回{ testCases, returned, nextCursor, hasMore }，每个 case 包含{ id, status, runAt, completedAt, metrics, errorCode, errorDetails, inputs, outputs, executionId }。文档建议保持默认limit20 并用cursor翻页，因为每个 case 携带原始 inputs/outputs，负载可能很大。

定位到某个失败用例后，可以用它的executionId深入到对应的执行记录：

n8n_executions({ action: "get", id: "用例返回的 executionId", mode: "error" })

取消一个运行中的测试

n8n_evaluations({ action: "cancel", workflowId: "abc123", runId: "run456" }) // → { id, status: "cancelled" }

cancel只能作用于状态仍为new或running的运行；响应表示取消请求已被接受，但仍在执行的 case 是异步停止的，需要再用get_run确认该运行确实到达cancelled状态。

错误码判断

工具的错误信息中会包含testRun scopes、testRun:create等关键字段引导重建 key，相关映射逻辑可参考 handlers-evaluations 测试。

边界与限制

• 评估功能在 n8n 侧受许可证/配额约束：未授权 evaluations 的实例对run/cancel回答 403，且读取类动作没有运行记录可返回。
• 每次调用n8n_evaluations对应一个 n8n API 请求，典型耗时 50–200ms；run在任何用例执行前就返回，轮询时间需单独预估。
• 跟踪历史结果时建议只存 run id，不要存 case 负载。
• 如果只需要只读能力，可以通过DISABLED_TOOL_OPERATIONS=n8n_evaluations:run,cancel只禁掉触发与取消动作，保留list_runs/get_run/list_cases（见 README 的 Read-Only Deployment 一节）。

更多参数与返回结构细节见 工具完整文档 和 WORKFLOW_GUIDE.md 的 n8n_evaluations 章节。

【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp