搜 索

n8n-mcp 从入门到放弃

  • 27阅读
  • 2026年01月21日
  • 0评论
首页 / AI/大数据 / 正文

前言

作为一个热爱自动化但又经常被自动化折磨的程序员，当我听说可以让 Claude 直接操控 n8n 工作流时，我的第一反应是："这不就是让AI帮我写自动化脚本的自动化吗？"

然后我就开始了这段充满坑的旅程。

本文将记录如何将 n8n-mcp 与 Claude Desktop 集成，以及我在过程中踩过的那些"看起来很简单但实际上能让你debug到凌晨三点"的坑。

什么是 MCP？

MCP（Model Context Protocol）是 Anthropic 推出的一个协议，允许 AI 模型与外部工具和服务进行交互。简单来说，就是给 Claude 装上了"手和脚"，让它不再只是一个"嘴炮选手"。

graph LR A[👤 用户] --> B[💬 Claude Desktop] B --> C[🔌 MCP Protocol] C --> D[🔧 n8n-mcp Server] D --> E[⚡ n8n Instance] E --> F[🔄 Workflows] E --> G[📊 Executions] E --> H[🔐 Credentials] style A fill:#e1f5fe style B fill:#fff3e0 style C fill:#f3e5f5 style D fill:#e8f5e9 style E fill:#fff8e1

整体架构

在深入配置之前，让我们先看看整个系统是如何协作的：

sequenceDiagram participant User as 👤 用户 participant Claude as 🤖 Claude Desktop participant MCP as 🔌 n8n-mcp participant N8N as ⚡ n8n Server User->>Claude: 帮我创建一个定时发送邮件的工作流 Claude->>MCP: 调用 create_workflow API MCP->>N8N: POST /api/v1/workflows N8N-->>MCP: 返回 workflow_id MCP-->>Claude: 创建成功，ID: xxx Claude-->>User: 工作流已创建，需要我帮你激活吗？ User->>Claude: 好的，激活它 Claude->>MCP: 调用 activate_workflow API MCP->>N8N: PATCH /api/v1/workflows/{id}/activate N8N-->>MCP: 激活成功 MCP-->>Claude: 工作流已激活 Claude-->>User: 搞定！工作流现在每天早上9点会自动运行

环境准备

前置条件

在开始之前，请确保你的环境满足以下条件：

组件版本要求检查命令
Node.js>= 18.xnode -v
npm>= 8.xnpm -v
n8n>= 1.0n8n --version
Claude Desktop最新版检查 About

n8n 服务准备

首先确保你的 n8n 服务已经运行：

# 如果还没安装 n8n
npm install -g n8n

# 启动 n8n 服务
n8n start

# 或者使用 Docker
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n

获取 n8n API Key

  1. 打开 n8n 界面 (默认 http://localhost:5678)
  2. 点击右上角头像 → Settings
  3. 进入 API 选项卡
  4. 点击 Create an API key
  5. 复制生成的 API Key（只显示一次，务必保存好！）
flowchart TD A[打开 n8n 界面] --> B[点击头像] B --> C[进入 Settings] C --> D[选择 API 选项卡] D --> E[创建 API Key] E --> F[复制并保存 Key] F --> G[配置到 claude_desktop_config.json] style E fill:#ffcdd2 style F fill:#c8e6c9

安装 n8n-mcp

终于到了激动人心的安装环节！（flag 已立）

# 全局安装 n8n-mcp
sudo npm install -g n8n-mcp

# 验证安装
npx n8n-mcp --version

如果你看到版本号输出，恭喜你，你已经完成了整个流程中最简单的一步。

配置 Claude Desktop

配置文件位置

Claude Desktop 的配置文件位于：

操作系统配置文件路径
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
Linux~/.config/Claude/claude_desktop_config.json

完整配置示例

创建或编辑配置文件：

# macOS
mkdir -p ~/Library/Application\ Support/Claude
vim ~/Library/Application\ Support/Claude/claude_desktop_config.json

写入以下内容：

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "n8n-mcp"],
      "env": {
        "N8N_API_URL": "http://localhost:5678/api/v1",
        "N8N_BASE_URL": "http://localhost:5678",
        "MCP_MODE": "stdio",
        "N8N_API_KEY": "你的n8n-api-key"
      }
    }
  }
}

配置说明

graph TB subgraph 配置项说明 A["N8N_API_URL"] --> A1["n8n API 端点地址
用于 API 调用"] B["N8N_BASE_URL"] --> B1["n8n 服务基础地址
⚠️ 必须配置，否则只读模式"] C["MCP_MODE"] --> C1["通信模式
⚠️ 必须设为 stdio"] D["N8N_API_KEY"] --> D1["API 认证密钥
从 n8n 设置获取"] end style B fill:#ffcdd2 style C fill:#ffcdd2 style B1 fill:#ffebee style C1 fill:#ffebee

🕳️ 踩坑实录

坑点一：MCP_MODE 未配置导致 JSON 解析错误

症状描述：

配置完成后重启 Claude Desktop，发现 MCP 插件无法加载，控制台疯狂报错：

Error: Unexpected token in JSON at position xxx
SyntaxError: JSON.parse: unexpected character at line x column y

原因分析：

当未设置 MCP_MODE: "stdio" 时，n8n-mcp 会将调试日志和运行时信息直接输出到标准输出流。而 Claude Desktop 期望通过 stdio 接收的是纯净的 JSON 格式数据，混入的日志信息直接破坏了 JSON 结构。

sequenceDiagram participant Claude as Claude Desktop participant MCP as n8n-mcp Note over Claude,MCP: ❌ 错误情况：未配置 MCP_MODE MCP->>Claude: [DEBUG] Initializing connection... MCP->>Claude: {"jsonrpc":"2.0"...} MCP->>Claude: [INFO] Connected to n8n Claude->>Claude: 💥 JSON.parse() 失败！ Note over Claude,MCP: ✅ 正确情况：MCP_MODE=stdio MCP->>Claude: {"jsonrpc":"2.0","method":"..."} Claude->>Claude: ✅ 解析成功

解决方案：

确保配置中包含：

"MCP_MODE": "stdio"

坑点二：缺少 N8N_BASE_URL 导致只读模式

症状描述：

Claude 能识别到 n8n-mcp 插件，也能列出工作流，但是：

  • 无法创建新工作流
  • 无法修改现有工作流
  • 无法执行工作流
  • Claude 提示插件处于"只读模式"

原因分析：

N8N_API_URL 和 N8N_BASE_URL 看起来很像，但它们的作用完全不同：

配置项作用缺失后果
N8N_API_URL指定 API 端点完全无法连接
N8N_BASE_URL指定服务基础地址，用于构建完整URL部分功能失效，只读模式
flowchart LR subgraph "只配置 API_URL" A1[读取工作流 ✅] A2[列出执行记录 ✅] A3[创建工作流 ❌] A4[执行工作流 ❌] end subgraph "同时配置 BASE_URL" B1[读取工作流 ✅] B2[列出执行记录 ✅] B3[创建工作流 ✅] B4[执行工作流 ✅] end style A3 fill:#ffcdd2 style A4 fill:#ffcdd2 style B3 fill:#c8e6c9 style B4 fill:#c8e6c9

解决方案：

两个配置都要有：

{
  "N8N_API_URL": "http://localhost:5678/api/v1",
  "N8N_BASE_URL": "http://localhost:5678"
}

坑点三：API Key 权限不足

症状描述：

某些操作返回 403 Forbidden。

解决方案：

在 n8n 中创建 API Key 时，确保授予足够的权限：

  • ✅ workflow:read
  • ✅ workflow:write
  • ✅ workflow:execute
  • ✅ execution:read

实战示例

配置完成后，让我们来看看 Claude + n8n-mcp 能做什么骚操作。

示例一：创建定时备份工作流

对话示例：

👤 用户：帮我创建一个工作流，每天凌晨2点自动备份数据库，并发送邮件通知

🤖 Claude：好的，我来帮你创建这个工作流...

graph LR A[⏰ Cron Trigger
每天 02:00] --> B[🗄️ MySQL
执行备份命令] B --> C{备份成功?} C -->|是| D[📧 发送成功邮件] C -->|否| E[📧 发送失败告警] D --> F[✅ 结束] E --> F style A fill:#e3f2fd style B fill:#fff3e0 style D fill:#e8f5e9 style E fill:#ffebee

示例二：监控 API 健康状态

对话示例：

👤 用户：创建一个工作流，每5分钟检查我的API是否正常，如果异常就发送Slack通知
graph TD A[⏰ 每5分钟触发] --> B[🌐 HTTP Request
GET /health] B --> C{状态码 = 200?} C -->|是| D[📝 记录正常日志] C -->|否| E[🔔 Slack 告警] E --> F[📊 记录异常到数据库] D --> G[结束] F --> G style A fill:#e3f2fd style E fill:#ffcdd2 style D fill:#c8e6c9

示例三：自动化内容发布

对话示例：

👤 用户：当我在 Notion 添加新文章时，自动发布到我的博客并同步到各个平台
graph LR A[📝 Notion
新文章触发] --> B[🔄 格式转换
Markdown] B --> C[📤 发布到博客] C --> D[并行分发] D --> E[掘金] D --> F[知乎] D --> G[CSDN] D --> H[cnblogs] E --> I[📊 汇总结果] F --> I G --> I H --> I I --> J[📧 发送报告] style A fill:#fff3e0 style D fill:#e8f5e9

示例四：智能客服工单处理

sequenceDiagram participant User as 客户 participant Form as 表单 participant N8N as n8n participant AI as Claude API participant Slack as Slack participant Jira as Jira User->>Form: 提交工单 Form->>N8N: Webhook 触发 N8N->>AI: 分析工单内容 AI-->>N8N: 紧急程度：高
类型：技术问题 alt 紧急工单 N8N->>Slack: 立即通知值班人员 N8N->>Jira: 创建高优先级Issue else 普通工单 N8N->>Jira: 创建普通Issue end N8N->>User: 发送确认邮件

常用命令速查

n8n-mcp 提供的能力

功能说明使用场景
列出工作流获取所有工作流列表查看现有自动化
创建工作流基于描述创建新工作流快速搭建自动化
更新工作流修改现有工作流配置迭代优化
执行工作流手动触发工作流运行测试或临时执行
查看执行记录获取历史执行结果问题排查
管理凭证配置第三方服务认证集成外部服务

调试技巧

# 查看 Claude Desktop 日志 (macOS)
tail -f ~/Library/Logs/Claude/mcp*.log

# 直接测试 n8n-mcp 连接
N8N_API_URL=http://localhost:5678/api/v1 \
N8N_BASE_URL=http://localhost:5678 \
N8N_API_KEY=your-key \
MCP_MODE=stdio \
npx n8n-mcp

# 测试 n8n API 连通性
curl -H "X-N8N-API-KEY: your-key" \
  http://localhost:5678/api/v1/workflows

完整配置流程图

flowchart TD Start([开始]) --> A[安装 Node.js >= 18] A --> B[安装 n8n] B --> C[启动 n8n 服务] C --> D[获取 API Key] D --> E[安装 n8n-mcp] E --> F[创建配置文件] F --> G{配置检查} G -->|缺少 MCP_MODE| H[添加 MCP_MODE: stdio] G -->|缺少 BASE_URL| I[添加 N8N_BASE_URL] G -->|配置完整| J[重启 Claude Desktop] H --> G I --> G J --> K{MCP 加载成功?} K -->|是| L([🎉 开始使用]) K -->|否| M[检查日志排错] M --> G style Start fill:#e3f2fd style L fill:#c8e6c9 style H fill:#ffcdd2 style I fill:#ffcdd2

最佳实践

1. 安全建议

mindmap root((安全实践)) API Key 管理 定期轮换 最小权限原则 不要提交到 Git 网络安全 使用 HTTPS 限制访问 IP 设置防火墙 监控告警 异常执行通知 API 调用监控 定期审计日志

2. 工作流设计原则

  • 单一职责：每个工作流只做一件事
  • 错误处理：添加 Error Trigger 节点
  • 日志记录：关键节点记录执行状态
  • 版本管理：定期导出工作流备份

3. 性能优化

  • 避免在循环中调用外部 API
  • 合理设置 Cron 触发间隔
  • 大数据量处理时使用批处理

总结

经过以上一番折腾，我们终于实现了 Claude + n8n 的梦幻联动。现在你可以：

  • 🗣️ 用自然语言描述需求，让 Claude 帮你创建工作流
  • 🔍 让 Claude 帮你分析和优化现有工作流
  • 🐛 出问题时让 Claude 帮你排查执行记录
  • 🚀 实现真正的"自动化的自动化"

当然，如果你在配置过程中遇到了本文没有提到的坑...

恭喜你，你已经具备了写续集的资格！ 🎉

参考资料

本文属于「从入门到放弃」系列，如果你真的放弃了，记得在评论区留下你的故事。

如果你成功了...那你一定是看了这篇文章。 😏

从入门到放弃自动化n8nCluade
版权属于：outlier
本文链接：https://underestimated.cn/archives/n8n-mcp-from-zero-to-zero.html
随意转载，请注明出处
评论区
暂无评论
avatar