N8n Debug MCP

🔍 n8n调试MCP

最后，像侦探一样调试n8n工作流，而不是受制于日志

 ](https://nodejs.org/)  

这 唯一专为调试n8n工作流而构建的MCP服务器。停止单击n8n UI查找错误。开始询问Claude出了什么问题，并在整个工作流架构中跟踪执行链。

______________________________________________________________________

😤 每个人都知道的问题

您触发了一个webhook。您的编排工作流程启动。它叫一个代理人。代理程序会访问内存管理器。那么。..沉默。

有些事情失败了。 但是在哪里？为什么？

n8n调试的噩梦：

• 🖱️ 点击用户界面15分钟以上，寻找失败的执行
• 📍 手动关联3个以上工作流的时间戳，以跟踪执行链
• 🔍 在页面之间复制粘贴执行ID以跟踪线程
• 📋 在没有上下文的情况下读取原始错误消息，了解导致失败的数据
• 🤷 API中没有可见的父子执行关系

这是大多数n8n调试工具停止的地方。他们给你原木。你可以在自己的时间里扮演法医侦探。

______________________________________________________________________

✨ 了解解决方案

n8n调试mcp 为您的工作流编排带来AI驱动的调试。有了Claude的支持，调试将从乏味的搜索转变为对话式的调查。

它的作用：

• 🔗 跟踪执行链 自动跨多个工作流（其他人没有构建的MCP）
• 🔬 从法律角度分析错误 基于人工智能的修复建议
• 💬 说你的语言 -通过与Claude的自然对话进行调试
• ⚡ 节省时间 -手动调试需要几分钟的时间

真实调试体验

You: "Why did my last task creation fail?"

Claude: [automatically traces execution]
  → Main orchestrator (success)
  → Task Agent (success)
  → Notion Database connector (ERROR: 401 Unauthorized)

Analysis: Your Notion API key may have expired or been revoked.
Suggestion: Verify credentials in n8n Settings > Credentials

______________________________________________________________________

🆚 这有什么不同

而其他n8n MCP服务器则专注于 建筑 或 管理 工作流程，n8n调试mcp专门从事 调试它们:

______________________________________________________________________

🛠️ 六个强大的调试工具

🔗 list_active_工作流

列出所有带有ID、状态和webhook路径的工作流。非常适合一目了然地了解您的架构。

在以下情况下使用： “我正在运行哪些工作流？”

You: "List all my workflows"
Claude: [displays organized list grouped by pattern]
  - MAIN_Orchestrator (webhook: /webhook/main)
  - AGENT_TaskManager (sub-workflow)
  - MEMORY_Manager (sub-workflow)

______________________________________________________________________

📊 get_workflowexecutions

获取任何工作流的最近执行情况，按状态（成功/错误/运行）过滤。

在以下情况下使用： “显示TaskManager中最近的错误”

You: "What failed in TaskManager recently?"
Claude: [lists failed executions with timestamps]
  - Execution #abc123 (2m ago, ERROR)
  - Execution #def456 (15m ago, ERROR)
  - Execution #ghi789 (1h ago, SUCCESS)

______________________________________________________________________

🔍 getexecution_trace

完整的逐节点执行跟踪，显示每个运行节点的输入、输出和计时。

在以下情况下使用： “告诉我这次处决中发生了什么”

You: "Trace execution abc123"
Claude: [shows complete flow]
  1. HTTP Request (input: webhook payload)
     ↓ 245ms
  2. Set Variables (processed user_id)
     ↓ 12ms
  3. Notion Lookup (ERROR: 401)
     Input: { user_id: "123", page_id: "xyz" }
     Error: Unauthorized - API key invalid

______________________________________________________________________

⛓️ get_correlated_executions ← 杀手级特征

自动跟踪整个执行链 整个工作流架构这解决了n8n的最大局限性：没有本机执行相关性。

在以下情况下使用： “显示用户触发此操作时的完整执行过程”

You: "Trace my last webhook call through all workflows"
Claude: [builds execution tree]
  MAIN_Orchestrator (execution #main123) ✅
    ├─ HTTP Request node → user_id: "user456"
    └─ Calls webhook /webhook/agent

  AGENT_TaskManager (execution #agent456) ✅
    ├─ Create task in Notion
    └─ Calls webhook /webhook/memory

  MEMORY_Manager (execution #memory789) ❌ ERROR
    └─ Update memory context
       Error: Rate limit exceeded on Airtable

关联策略 -智能多方法匹配：

• 时间戳接近度 （30秒窗口内）
• 用户ID匹配 （有效载荷中的user_id）
• Webhook URL模式 （HTTP请求URL）
• 请求/响应ID （您现有的关联模式）

______________________________________________________________________

🚨 执行失败

通过错误摘要快速查看所有工作流中最近的故障。

在以下情况下使用： “最后一个小时发生了什么？”

You: "What failed in the last hour?"
Claude: [aggregates recent errors]
  TimeManager (3 failures) - Connection timeout
  DataSync (2 failures) - Missing required fields
  Notion Integration (5 failures) - API rate limit

______________________________________________________________________

🔬 分析执行错误

通过上下文感知调试对特定失败执行进行深入的取证分析。

在以下情况下使用： “这到底为什么失败了？我该怎么办？”

You: "Why did execution #abc123 fail?"
Claude: [comprehensive analysis]
  Failed Node: Notion Database Update
  Error: 401 Unauthorized

  Context:
  - Input data was valid (user_id: "123", fields: [...])
  - API key was used from credentials: "notion_prod"
  - Last successful call: 2 hours ago
  - Other Notion calls failing: Yes (4 in last hour)

  Analysis:
  🔍 Pattern: Multiple 401 errors suggest credential issue
  💡 Suggestion: Notion API key may have been revoked or expired

  Next Steps:
  1. Check Notion workspace for revoked integrations
  2. Generate new API key if needed
  3. Update n8n credentials
  4. Re-execute the workflow

______________________________________________________________________

🚀 快速开始

先决条件

• n8n 本地或远程运行（启用API）
• n8n API密钥 （我们将在30秒内创建此内容）
• Node.js 18+ 安装

步骤1：创建n8n API密钥

1. 打开n8n： http://localhost:5678 （或您的n8n URL）
2. 首选 设置→ n8n API （左侧边栏）
3. 点击 创建API密钥
4. 复制密钥（以开头 n8n_api_...)

步骤2：配置环境

创建 .env 项目根目录中的文件：

N8N_API_KEY=n8n_api_xxxxxxxxxxxxxxxxxxxxx
N8N_BASE_URL=http://localhost:5678  # Optional, defaults to localhost:5678

步骤3：安装并运行

# Install dependencies
npm install

# Run in development mode (with auto-reload)
npm run dev

# Or build and run production
npm run build
npm start

步骤4：测试它是否有效

MCP服务器现在可供Claude Desktop和配置有此服务器的其他MCP客户端使用。

在Claude Desktop或Claude Code中，尝试：

"What workflows do I have?"

克劳德将使用 list_active_workflows 工具自动。你在调试！ 🎉

______________________________________________________________________

⚠️ 安全和隐私声明

重要提示：此MCP将工作流执行数据发送到Claude/Anthropic的API。

共享哪些数据

当您使用此MCP调试工作流时，以下数据将发送给Claude：

• 完整的执行跟踪（逐节点输入和输出）
• 错误消息和堆栈跟踪
• 工作流有效负载中的用户ID、关联ID和其他上下文数据
• 工作流配置和节点参数

您的职责

• ✅ 仅将此MCP用于包含非敏感数据的工作流，或者
• ✅ 接受工作流输出中的敏感数据（PII、凭据、令牌）将被发送到Anthropic的风险
• ✅ 确保符合贵组织的数据治理政策
• ✅ 查看Anthropic的数据使用政策：https://www.anthropic.com/legal/privacy

此MCP不做什么

• ❌ 不从执行跟踪中编辑或过滤敏感数据
• ❌ 不实施PII检测或消毒
• ❌ 不提供合规性审计日志

为什么？ MCP是协议桥，而不是安全层。它们在系统之间透明地传递数据。数据隐私和治理是用户的责任。

安全传输

• ✅ 默认情况下，非本地主机连接需要HTTPS
• ✅ 验证API密钥格式以防止错误配置
• ✅ 通过输入验证防止路径遍历攻击

对于使用HTTP的本地开发，设置 ALLOW_HTTP=true 在您的环境中。

______________________________________________________________________

💡 专业提示和常见场景

场景1：“有些事情失败了，但我不知道是什么”

You: "Why did my last workflow execution fail?"

Claude handles:
1. Fetches recent failed executions
2. Gets detailed trace for the most recent failure
3. Analyzes the error with context
4. Suggests remediation steps

场景2：“Bug位于工作流链中的某个位置”

You: "Trace my last user request through all workflows"

Claude handles:
1. Correlates executions using timestamp + user_id
2. Builds execution tree showing MAIN → AGENT → MEMORY flow
3. Highlights any failures in the chain
4. Shows data transformation at each step

场景3：“此错误不断发生”

You: "The Notion integration keeps failing. What's the pattern?"

Claude handles:
1. Gets recent failed executions with Notion
2. Analyzes error patterns
3. Suggests common causes (rate limits, expired credentials, etc.)
4. Recommends fixes

场景4：“我需要调试特定节点”

You: "Show me the inputs and outputs for all HTTP Request nodes in the last execution"

Claude handles:
1. Gets execution trace
2. Filters to specific node types
3. Displays data flow with formatting
4. Highlights any data issues

专业提示

• 用自然语言提问 -Claude了解您的工作流架构的上下文
• 使用执行ID -有身份证吗？克劳德可以深入细节
• 参考用户ID -“显示用户123的执行情况”使用自动关联
• 时间窗口 -“过去2小时内发生了什么故障？”会自动触发正确的工具

______________________________________________________________________

🏗️ 相关性如何工作

n8n在其API中不公开父子执行关系。因此，我们使用多种策略建立了智能关联：

相关方法（按置信度排序）

1. 用户上下文匹配 （置信度：0.5-0.8）

- user_id 有效载荷 - chat_id 有效载荷 - correlation_id 有效载荷

1. Webhook图案匹配 （置信度：0.3）

- HTTP请求URL与另一个工作流的webhook路径匹配 - 表示子工作流调用

1. 时间戳接近度 （置信度：0.2-0.3）

- 在30秒内执行 - 按执行开始时间排序

1. 响应ID模式 （置信度：0.1-0.2）

- 现有的 response_id 数据中的模式 - 您嵌入的自定义相关性ID

构建执行树

Claude使用这些方法构建执行树：

INPUT: execution_id = "abc123"

STEP 1: Fetch execution #abc123 (MAIN_Orchestrator)
  - Extract user_id = "user456"
  - Extract webhook call: /webhook/agent

STEP 2: Find executions with user_id="user456" within 5s window
  - Found: AGENT_TaskManager execution #def456

STEP 3: Repeat for downstream workflows
  - AGENT_TaskManager calls /webhook/memory
  - Found: MEMORY_Manager execution #ghi789

STEP 4: Display tree with results and confidence scores

相关性并不完美，但它比手动搜索时间戳要好得多！

______________________________________________________________________

📚 技术文档

可用工具参考

环境变量

# Required
N8N_API_KEY=n8n_api_xxxxxxxxxxxxx

# Optional
N8N_BASE_URL=http://localhost:5678  # Defaults to localhost:5678
N8N_API_VERSION=v1                   # API version, defaults to v1

发展

# Run with hot-reload (uses tsx)
npm run dev

# Compile TypeScript
npm run build

# Run compiled JavaScript
npm start

# TypeScript configuration in tsconfig.json

______________________________________________________________________

🔗 资源

• n8n文档 -官方n8n文档
• MCP协议 -什么是MCP？
• 克劳德桌面版 -与Claude一起使用此MCP
• 克劳德代码 -或者通过Claude Code CLI使用它

______________________________________________________________________

📄 许可证

Apache许可证2.0-请参阅 许可证 详细信息文件

由开发人员构建，适用于厌倦了点击日志的开发人员。

______________________________________________________________________

贡献

发现bug了吗？有功能请求吗？

• 问题:
• 讨论：社区欢迎创意

发展贡献

这是TypeScript。架构：

• src/index.ts -MCP服务器入口点
• src/n8n-client.ts -n8n API包装器
• src/correlator.ts -执行关联引擎
• src/formatter.ts -LLM优化输出

______________________________________________________________________

🎯 接下来是什么？

已经安装？试试这些：

1. “列出我的工作流” -查看您的架构
2. “显示最近的错误” -快速健康检查
3. “为什么执行\[ID\]失败？” -深入了解特定故障
4. “追踪我最后一次webhook调用” -查看完整的执行故事

问题？问克劳德！

______________________________________________________________________

调试工作流程应该很容易。最后，它是。

⭐ 如果这为您节省了调试时间，请在GitHub上给它打一颗星