n8n-MCP Server 协议 + Claude Code完整配置指南：AI驱动的工作流自动化实战

AI自动化n8nClaude CodeMCP工作流自动化2026

n8n是开源的工作流自动化平台，500+节点覆盖邮件、数据库、AI、API集成。但手动配置工作流耗时且容易出错——需要记忆节点名称、配置参数、表达式语法。

n8n-MCP是一个Model Context Protocol服务器，为Claude Code等AI助手提供n8n的完整节点文档、属性和操作接口。安装后，你用自然语言描述需求，Claude Code就能帮你：

创建完整的n8n工作流
修改已有节点配置
调试表达式错误
生成Python/JavaScript Code节点代码

根据n8n官方社区数据，n8n-MCP（czlonkowski/n8n-mcp）在2026年已获得20.6k+ GitHub Stars，NPM包周下载量15.4万，是目前最热门的n8n+AI集成方案之一。

---

安装步骤

第一步：确认环境要求

n8n-MCP需要：

Node.js 18+（验证命令：`node -v`）
npm 9+（验证命令：`npm -v`）
已运行的n8n实例（Docker或源码）
Claude Code已安装并可正常使用

第二步：全局安装n8n-mcp包

npm install -g n8n-mcp

验证安装成功：

npx n8n-mcp --version

如果网络较慢，可使用淘宝镜像：

npm install -g n8n-mcp --registry=https://registry.npmmirror.com

第三步：配置Claude Code的MCP设置

找到Claude Code的MCP配置文件，位置取决于你的操作系统：

**macOS/Linux**: `~/.claude/projects//.mcp.json`
**Windows**: `%USERPROFILE%\.claude\projects\\.mcp.json`

在配置文件中添加：

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "n8n-mcp", "server"],
      "env": {
        "N8N_HOST": "http://localhost:5678",
        "N8N_API_KEY": "你的n8n API密钥"
      }
    }
  }
}

如何获取n8n API密钥：

1. 打开你的n8n实例（默认 http://localhost:5678）

2. 进入 Settings → API → Create API Key

3. 复制生成的密钥，替换配置文件中的"你的n8n API密钥"

第四步：验证连接

重启Claude Code（或新建会话），然后测试：

/mcp list

如果看到 n8n 在列表中，说明MCP服务器已成功连接。

也可以直接在Claude Code中测试：

用n8n-MCP帮我创建一个：每5分钟检查Gmail，如果有新邮件就将标题和发件人发送到Slack频道

---

我踩过的5个真实配置坑

坑1：N8N_HOST地址填错了

**错误信息**：连接n8n-MCP后，Claude Code报错 Connection refused to http://localhost:5678

**原因**：n8n运行在远程服务器或Docker容器里，localhost指向的是Claude Code的本地机器，不是n8n实际运行的位置。

解决方法：

如果n8n在本地Docker：`http://host.Docker 容器化部署.internal:5678`（不是localhost）
如果n8n在远程服务器：`http://你的服务器IP:5678`（确保5678端口已对外开放）
如果用了反向代理：`https://你的域名/api`（需要n8n设置 `N8N_PROTOCOL=https`）

验证方法：在Claude Code所在机器上用curl测试：

curl http://你的N8N_HOST/api/v1/users/me \
  -H "X-n8n 工作流自动化-API-KEY: 你的API密钥"

返回用户信息说明连接正常。

---

坑2：API密钥权限不足

**错误信息**：Claude Code创建工作流时报 Forbidden - API key does not have the required scope

原因：n8n的API密钥默认只有读取权限，创建工作流需要写入权限。

解决方法：

1. 在n8n中进入 Settings → API

2. 编辑现有API Key或创建新的

3. 确保勾选了 workflow:read, workflow:write, executions:read 权限

4. 更新Claude Code配置文件中的 N8N_API_KEY

n8n-MCP需要的最小权限：

`workflow:read` - 读取现有工作流
`workflow:write` - 创建和修改工作流
`execution:read` - 查看执行历史（调试用）

---

坑3：n8n版本不兼容

**错误信息**：n8n-mcp: server error - n8n instance is too old

原因：n8n-MCP的部分功能依赖n8n较新的REST API版本。旧版本n8n（如v0.x）不支持。

解决方法：

检查你的n8n版本：

# Docker方式
docker exec <容器名> n8n info | grep Version

# 源码方式
cd /path/to/n8n && npm info n8n version

推荐使用n8n v1.0+。如果版本太旧，需要升级：

# Docker升级
docker pull n8nio/n8n:latest
docker-compose up -d

# 源码升级
git pull origin master
npm install

---

坑4：Claude Code不识别MCP工具

错误现象：配置文件正确，但Claude Code说 "I don't have access to any n8n tools"

原因：Claude Code的MCP配置是项目级别的，不是全局的。需要为每个项目单独配置。

解决方法：

1. 确保配置文件在正确的项目目录下：

   ls ~/.claude/projects/
   # 找到你的项目名，如 default、my-project 等

2. 或者在项目根目录创建 .mcp.json（不是~下）

3. 重启Claude Code，确保加载了新配置：

   # 退出当前Claude Code会话
   # 新建会话时指定项目
   claude --project your-project-name

---

坑5：Docker网络隔离导致MCP连接失败

**错误信息**：n8n在Docker里运行，Claude Code报 ECONNREFUSED

**原因**：Docker的默认网络模式是桥接，localhost指向容器内部而非宿主机。

解决方法：

方案A：使用host.docker.internal（推荐）

{
  "env": {
    "N8N_HOST": "http://host.docker.internal:5678"
  }
}

方案B：自定义Docker网络

# docker-compose.yml
services:
  n8n:
    networks:
      - n8n-network
  claude-code-sidecar:
    # 如果你有sidecar容器
    networks:
      - n8n-network

networks:
  n8n-network:
    driver: bridge

然后N8N_HOST填 http://n8n:5678（服务名）

方案C：暴露端口（简单但不安全）

# docker-compose.yml中
ports:
  - "5678:5678"

N8N_HOST填 http://你的服务器IP:5678

---

完整的n8n-MCP + Claude Code配置清单

将以下内容保存到你的项目根目录 .mcp.json：

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "n8n-mcp", "server"],
      "env": {
        "N8N_HOST": "http://localhost:5678",
        "N8N_API_KEY": "nta_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "N8N_LOG_LEVEL": "debug",
        "N8N_PROTOCOL": "http"
      }
    }
  }
}

各配置项说明：

配置项	说明	默认值
N8N_HOST	n8n实例地址	http://localhost:5678
N8N_API_KEY	n8n设置中生成的API密钥	（必填）
N8N_LOG_LEVEL	日志级别，可选debug/info/warn	info
N8N_PROTOCOL	协议，http或https	http

---

实战示例：用Claude Code创建第一个n8n工作流

启动Claude Code后，尝试以下自然语言指令：

示例1：创建Gmail转Slack通知工作流

触发器：每5分钟检查Gmail新邮件
条件：如果发件人不在白名单，过滤掉
动作：将邮件标题和发件人发送到Slack #alerts频道

帮我创建一个n8n工作流：

示例2：创建数据库备份工作流

每周一凌晨2点执行
将PostgreSQL的users表导出为CSV
上传到S3兼容存储（用阿里云OSS）
发送执行报告到钉钉群

用n8n创建一个工作流：

示例3：调试现有工作流

我的n8n工作流 "gmail-slack-forward" 执行失败了，
帮我查看最近的5次执行记录，找出失败原因并修复

---

n8n-MCP的进阶用法

使用n8n-skills提升生成质量

n8n社区提供了专门的Claude Code Skills（czlonkowski/n8n-skills），安装后能显著提升生成的工作流质量：

git clone https://github.com/czlonkowski/n8n-skills.git
# 将skills内容复制到你的Claude Code skills目录

n8n-skills包含7个专门技能：

**n8n Expression Syntax** - 正确的表达式写法
**n8n MCP Tools Expert** - MCP工具高效使用
**JavaScript Code Nodes** - Code节点JS编写
**Python Code Nodes** - Code节点Python编写

自定义MCP服务器启动参数

如果需要更细粒度的控制，可以不用npx直接调用：

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/usr/local/lib/node_modules/n8n-mcp/dist/server.js"],
      "env": {
        "N8N_HOST": "https://your-n8n.example.com",
        "N8N_API_KEY": "nta_xxx",
        "NODE_ENV": "production"
      }
    }
  }
}

---

常见问题排查清单

遇到问题时，按顺序检查：

1. **n8n是否正常运行**：curl http://localhost:5678 返回n8n页面

2. **API密钥是否正确**：在浏览器直接访问 http://localhost:5678/api/v1/users/me 并带入API Key

3. 端口是否可访问：telnet或curl从Claude Code机器测试n8n地址

4. **MCP配置是否生效**：新建Claude Code会话，输入 /mcp list 确认n8n在列表中

5. Node.js版本是否满足：18.0+，低版本会报语法错误

---

适合与不适合的场景

适合使用n8n-MCP的情况：

需要快速搭建复杂工作流（10+节点）
经常需要修改和迭代n8n工作流
希望用自然语言调试和修复工作流
需要批量创建类似的工作流

不适合的情况：

n8n实例在完全没有外网访问的内网
需要极低延迟的实时触发（每次都要等Claude Code生成）
n8n版本低于v1.0

---

总结

n8n-MCP将Claude Code的自然语言能力与n8n的500+工作流节点结合，让你用对话方式构建自动化流程。安装本身不复杂，但容易在网络配置、权限、版本兼容性上踩坑。

核心配置就3点：

1. N8N_HOST填正确地址（注意Docker网络）

2. N8N_API_KEY权限要包含workflow读写

3. 配置文件要在正确的项目目录下

推荐资源：

n8n-MCP GitHub: github.com/czlonkowski/n8n-mcp（20.6k⭐）
n8n官方文档: docs.n8n.io/integrations/mcp
Claude Code + n8n 视频教程: YouTube搜索 "Claude Code n8n tutorial 2026"

👉 立即体验AI工作流自动化：MiniMax Token订阅平台

---

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Related Tech Articles

Deep dive into related technical topics:

2026-05-17-n8n-mcp-claude-code-ai-2026.html

技术标签: ai自动化, claude code

2026-05-17-n8n-mcp-claude-code-the-complete-2026-setup-guide--en.html

技术标签: ai automation, claude code

2026-05-17-n8n-mcp-claude-code-the-complete-2026-setup-guide--en.html

技术标签: ai automation, claude code

⚡ Automation Workflow Hardware

查看推荐 →