n8n-MCP Claude Code 安装配置指南

lvlv_feifei
459 阅读5分钟

n8n-MCP Claude Code 安装配置指南

概述

n8n-MCP 是一个强大的 Model Context Protocol (MCP) 服务器，允许 Claude Code 直接与 n8n 工作流自动化平台进行交互。通过这个集成，您可以使用自然语言在 Claude Code 中设计、构建、验证和部署 n8n 工作流。

在我的claude code实践中 n8n-mcp安装遇到查询不到数据库节点的情况，当使用了本地build后解决了这个问题，考虑到本地build难度较低，大家也可以使用这个方式或者直接将本文档喂到claude code进行安装。

核心功能

  • 🔍 智能节点搜索：从 534+ 个节点中快速找到所需功能
  • 🤖 AI 工具支持：268 个 AI 就绪节点，支持智能自动化
  • ✅ 实时验证：构建前、构建后全流程验证
  • 🚀 直接部署：从 Claude Code 直接创建和管理工作流
  • 📊 执行监控：实时查看工作流执行状态

前置要求

  • n8n 实例：本地或远程运行的 n8n (默认: http://localhost:5678)
  • n8n API Key：从 n8n 设置中获取 API 密钥
  • Node.js：版本 18.x 或更高
  • Claude Code：最新版本的 Claude Code CLI
  • Git：用于克隆仓库

安装步骤

1. 克隆 n8n-MCP 仓库

cd ~/Downloads  # 或您偏好的目录
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp

2. 构建项目

# 安装依赖
npm install

# 构建 TypeScript 代码
npm run build

# 验证构建成功
ls -la dist/mcp/
# 应该看到 index.js 文件

3. 配置环境变量

在您的 n8n 项目目录下使用 direnv 或直接设置环境变量：

使用 direnv（推荐）
cd /Users/lvlv/my_n8n  # 您的 n8n 项目目录

# 创建 .envrc 文件
cat > .envrc << 'EOF'
export N8N_API_URL="http://localhost:5678"
export N8N_API_KEY="your-api-key-here"
EOF

# 允许 direnv 加载环境变量
direnv allow
获取 n8n API Key
  1. 登录您的 n8n 实例
  2. 前往 Settings → API Settings
  3. 生成新的 API Key 或复制现有的
  4. 保存该密钥用于配置

4. 配置 MCP 服务器

在您的 n8n 项目目录创建 .mcp.json 配置文件：

cd /Users/lvlv/my_n8n

创建 .mcp.json 文件：

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": ["/Users/lvlv/Downloads/n8n-mcp/dist/mcp/index.js"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "debug",
        "DISABLE_CONSOLE_OUTPUT": "false",
        "N8N_API_URL": "http://localhost:5678",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

重要配置说明：

  • command: 使用 node 执行 JavaScript
  • args: 指向构建后的 index.js 文件的完整路径
  • MCP_MODE: 必须设置为 stdio 以支持 Claude Code
  • N8N_API_URL: 您的 n8n 实例地址
  • N8N_API_KEY: 从 n8n 获取的 API 密钥

5. 在 Claude Code 中添加 MCP 服务器

# 在 n8n 项目目录下执行
cd /Users/lvlv/my_n8n

# 添加 MCP 配置到 Claude Code
claude mcp add

# Claude Code 会自动检测 .mcp.json 文件并加载配置

验证加载成功：

# 启动 Claude Code
claude

# 在 Claude Code 中测试
> 请列出可用的 n8n MCP 工具

6. 配置 Claude 指令文件

创建 CLAUDE.md 文件来定义 Claude 的工作方式：

cd /Users/lvlv/my_n8n

创建包含最佳实践的 CLAUDE.md 文件（github.com/czlonkowski…

核心内容包括：

  • 工作流创建流程
  • 验证策略
  • 节点搜索方法
  • 部署最佳实践

功能验证

测试 1: 验证数据库连接

在 Claude Code 中执行：

请检查 n8n-mcp 数据库统计信息

预期结果：

{
  "totalNodes": 534,
  "aiTools": 268,
  "triggers": 108,
  ...
}

测试 2: 获取工作流信息

请列出我的 n8n 工作流

预期结果：显示您 n8n 实例中的工作流列表

测试 3: 搜索节点

搜索 webhook 相关的节点

预期结果：返回 webhook 相关节点列表

常用命令速查

节点发现

// 搜索特定功能
mcp__n8n-mcp__search_nodes({query: 'slack'})

// 按类别浏览
mcp__n8n-mcp__list_nodes({category: 'trigger'})

// 查看 AI 工具
mcp__n8n-mcp__list_ai_tools()

节点配置

// 获取节点基本信息
mcp__n8n-mcp__get_node_essentials('nodes-base.webhook')

// 获取完整文档
mcp__n8n-mcp__get_node_documentation('nodes-base.slack')

// 搜索特定属性
mcp__n8n-mcp__search_node_properties('nodes-base.httpRequest', 'auth')

工作流管理

// 创建工作流
mcp__n8n-mcp__n8n_create_workflow(workflow)

// 验证工作流
mcp__n8n-mcp__validate_workflow(workflow)

// 列出工作流
mcp__n8n-mcp__n8n_list_workflows({limit: 10})

故障排除

问题 1: MCP 工具不可用

症状：Claude Code 中看不到 n8n-mcp 工具

解决方案：

  1. 确认 .mcp.json 文件在正确位置
  2. 重启 Claude Code：claude restart
  3. 检查构建是否成功：ls -la /path/to/n8n-mcp/dist/mcp/index.js

问题 2: API 连接失败

症状：无法获取工作流信息

解决方案：

  1. 验证 n8n 实例正在运行
  2. 检查 API URL 是否正确
  3. 验证 API Key 是否有效
  4. 测试连接：curl http://localhost:5678/api/v1/workflows -H "X-N8N-API-KEY: your-key"

问题 3: 节点验证失败

症状：创建工作流时验证错误

解决方案：

  1. 使用 validate_node_minimal 进行预验证
  2. 检查必填字段
  3. 使用 get_node_essentials 获取正确的配置格式

最佳实践

1. 工作流开发流程

发现 → 预验证 → 构建 → 验证 → 部署 → 监控

2. 使用验证优先原则

  • 始终在构建前验证节点配置
  • 构建后验证完整工作流
  • 部署后验证执行状态

3. 增量更新策略

使用 n8n_update_partial_workflow 进行增量更新，可节省 80-90% 的 token 使用量。

4. 错误处理

  • 在关键节点添加错误处理
  • 使用 continueOnFail 选项
  • 配置错误工作流进行监控

进阶配置

自定义日志级别

在 .mcp.json 中调整：

"LOG_LEVEL": "info"  // 可选: debug, info, warn, error

性能优化

  1. 使用 get_node_essentials 而非 get_node_info
  2. 批量验证节点配置
  3. 缓存常用节点信息

资源链接

💡 提示: 遇到问题时，可以使用 mcp__n8n-mcp__n8n_diagnostic({verbose: true}) 进行详细诊断。

avatar
文章
阅读
粉丝