使用说明

n8n MCP 服务器

一个模型上下文协议（MCP）服务器，它作为Claude AI与n8n工作流自动化之间的桥梁，能够通过自然语言实现智能工作流的创建和管理。

这是什么？

这个项目提供了一个 模型上下文协议（MCP）服务器 将AI助手（如Claude）连接到您的 n8n 工作流自动化实例。通过这种集成，您可以：

创建工作流 使用自然语言描述
管理现有工作流程 （激活，停用，更新，删除）
监控执行情况 并调试问题
查询工作流状态 以及配置
自动化工作流操作 通过对话式人工智能

为什么要使用这个？

无需在n8n用户界面中手动构建工作流，您只需向Claude描述您想要的内容即可：

“创建一个工作流，用于监控我的GitHub仓库中的新问题，向团队频道发送Slack通知，并在Trello中创建卡片以便跟踪。”

克劳德（Claude）通过这个MCP服务器与您的n8n实例相连，可以为您自动构建工作流。

特点

全面的工作流程管理
- 列出、创建、更新和删除工作流
- 按需激活和停用工作流
- 获取详细的流程配置
执行监控
- 查看工作流执行历史
- 获取详细的执行日志和结果
- 删除旧的执行记录
资源管理
- 列出并管理凭据
- 使用标签组织工作流程
灵活部署
- Docker对容器化环境的支持
- 本地开发环境设置
- 适用于家庭实验室部署的Portainer准备就绪
安全集成
- API密钥认证
- 基于环境的配置
- 不硬编码凭证

先决条件

在开始之前，请确保您已准备好：

Node.js 20 或更高版本 （用于本地开发）
Docker 和 Docker Compose （用于容器化部署）
一个正在运行的n8n实例 （自托管或云端）
n8n API密钥 （以下为说明）
克劳德桌面版 或者 克劳德·科德 (命令行界面)

获取您的n8n API密钥

登录到您的n8n实例
导航至设置 → n8n API
点击 创建API密钥
复制生成的API密钥（配置时需要用到）
安全地存储它（像对待密码一样）

快速入门

3分钟内快速启动并运行：

# Clone the repository
git clone https://github.com/nourdeo/mcp-n8n-server.git
cd mcp-n8n-server

# Install dependencies
npm install

# Create configuration
cp .env.example .env
# Edit .env with your n8n details

# Build the project
npm run build

# Start the server
npm start

然后配置Claude（参见配置（部分/章节）。

安装方法

方法1：Docker（推荐）

最适合用于生产环境部署、家庭实验室以及容器化环境。

步骤1：克隆仓库

git clone https://github.com/nourdeo/mcp-n8n-server.git
cd mcp-n8n-server

步骤2：配置环境变量

cp .env.example .env

编辑 .env 附上您的n8n详细信息：

N8N_BASE_URL=https://your-n8n-instance.com
N8N_API_KEY=your-api-key-here

步骤3：使用Docker Compose构建并运行

docker-compose up -d

步骤4：验证其是否正在运行

docker ps | grep mcp-n8n-server
docker logs mcp-n8n-server

方法2：本地开发

最适合用于开发、测试和定制。

步骤1：安装依赖项

npm install

步骤2：配置环境

cp .env.example .env
# Edit .env with your credentials

第三步：构建项目

npm run build

步骤4：运行服务器

npm start

对于带自动重载的开发：

npm run watch

方法3：Portainer部署

非常适合使用Portainer的家用实验室环境。

步骤1：创建一个新的堆栈

打开 Portainer
首选 栈（或堆栈） → 添加堆栈
给它起个名字 mcp-n8n-server

步骤2：上传docker-compose.yml文件

或者上传 docker-compose.yml 选择文件或粘贴其内容：

version: '3.8'

services:
  mcp-n8n-server:
    build: .
    container_name: mcp-n8n-server
    environment:
      - N8N_BASE_URL=${N8N_BASE_URL}
      - N8N_API_KEY=${N8N_API_KEY}
    restart: unless-stopped
    stdin_open: true
    tty: true

步骤3：添加环境变量

在Portainer的环境变量部分，添加：

N8N_BASE_URL： https://your-n8n-instance.com
N8N_API_KEY: your-api-key-here

步骤4：部署

点击 部署堆栈 并等待它启动。

配置

连接到Claude桌面版

Claude Desktop 使用配置文件来连接到 MCP 服务器。

配置文件位置：

macOS（苹果电脑操作系统）: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux（发音类似“林克斯”）： ~/.config/Claude/claude_desktop_config.json

对于本地安装：

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n-server/build/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

替换 /absolute/path/to/ 并替换为您的实际安装路径。

对于Docker安装：

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "mcp-n8n-server",
        "node",
        "build/index.js"
      ],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

编辑完配置后，重启Claude桌面应用。

连接到Claude代码（CLI）

Claude Code（命令行界面版本）有一个独立的配置文件。

配置文件位置：

macOS/Linux（操作系统）： ~/.config/claude/config.json
Windows： %USERPROFILE%\.config\claude\config.json

创建或编辑此文件：

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n-server/build/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

编辑配置文件后，重启Claude Code。

可用工具

MCP服务器向Claude提供了以下工具：

工作流管理

工具	描述
`list_workflows`	列出所有工作流及其状态
`get_workflow`	获取特定工作流的详细信息
`create_workflow`	从头开始创建一个新的工作流
`update_workflow`	更新现有工作流的配置
`delete_workflow` 永久删除工作流
`activate_workflow`	激活工作流以使其运行
`deactivate_workflow`	禁用工作流以停止其运行

执行管理

工具	描述
`list_executions`	列出工作流执行历史
`get_execution`	获取详细的执行日志和结果
`delete_execution`	删除特定的执行记录

资源管理

工具	描述
`list_credentials`	列出所有已配置的凭据
`list_tags`	列出所有可用标签

使用示例

一旦连接到Claude，您就可以使用自然语言与您的n8n实例进行交互：

基本查询

"List all my n8n workflows"
"Show me the details of workflow ID 123"
"What are the recent executions for my email workflow?"

工作流管理

"Create a new workflow called 'Daily Backup Notification'"
"Activate the workflow with ID 456"
"Deactivate all workflows tagged with 'testing'"

高级工作流创建

"Help me build a workflow that:
1. Monitors my GitHub repository for new issues
2. Sends a Slack notification to #dev-team
3. Creates a Trello card in the 'To Do' list"

"Create a workflow that checks my website every 5 minutes
and sends me an email if it's down"

调试与监控

"Show me all failed executions from the past week"
"Why did workflow 789 fail? Show me the execution details"
"List all workflows that haven't been executed in the past month"

项目结构

mcp-n8n-server/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── n8n-client.ts         # n8n API client wrapper
├── build/                    # Compiled JavaScript (generated)
│   ├── index.js
│   └── n8n-client.js
├── node_modules/             # Dependencies (generated)
├── .env                      # Your environment variables (not in git)
├── .env.example              # Example environment variables template
├── .gitignore                # Git ignore rules
├── .dockerignore             # Docker ignore rules
├── package.json              # Node.js dependencies and scripts
├── package-lock.json         # Locked dependency versions
├── tsconfig.json             # TypeScript compiler configuration
├── Dockerfile                # Docker image definition
├── docker-compose.yml        # Docker Compose orchestration
└── README.md                 # This file

发展

可用脚本

# Build the project
npm run build

# Watch mode (auto-recompile on changes)
npm run watch

# Start the server
npm start

# Development mode (build + start)
npm run dev

做出改变

在（某处）编辑TypeScript文件 src/
跑步 npm run build 编译
使用……进行测试 npm start
对于积极开发，请使用 npm run watch 在一个终端中，并且 npm start 在另一个

添加新工具

添加一个新的MCP工具：

添加API方法至 src/n8n-client.ts
在（系统/平台）中注册该工具 src/index.ts
定义工具的模式和处理器
重建并测试

故障排除

连接问题

验证n8n是否可访问：

curl https://your-n8n-instance.com/api/v1/workflows \
  -H "X-N8N-API-KEY: your-api-key"

预期：包含工作流列表的JSON响应

检查 Docker 日志：

docker logs mcp-n8n-server

检查连接错误或身份验证问题。

验证环境变量：

docker exec mcp-n8n-server env | grep N8N

确保两者都 N8N_BASE_URL 并且 N8N_API_KEY 设置正确。

认证错误

症状401 未授权或 403 禁止访问

解决方案：

确保您的API密钥有效且未过期
验证API密钥是否具有必要的权限
请检查您是否使用了正确的API密钥格式
确认基础URL正确（末尾没有斜杠）

克劳德未看到服务器

症状MCP服务器未列在Claude中，工具无法使用

解决方案:

更新配置后重启Claude Desktop/Code
验证配置文件路径是否正确
检查配置文件中的JSON语法（使用JSON验证器）
确保服务器进程正在运行：
- Docker： docker ps | grep mcp-n8n-server
- 本地：检查进程是否处于活动状态
检查克劳德的MCP日志中的错误信息

构建错误

症状TypeScript 编译失败

解决方案：

确保已安装 Node.js 20 或更高版本： node --version
删除 node_modules 并重新安装： rm -rf node_modules && npm install
清理构建目录： rm -rf build && npm run build

安全最佳实践

永远不要承诺 .env 文件
- 已经在 .gitignore，但一定要再三核对
- 使用 .env.example 作为模板
为n8n使用HTTPS
- 始终使用 https:// 在 N8N_BASE_URL
- 不要通过明文HTTP暴露n8n
保护好您的API密钥
- 将API密钥视为密码
- 定期更换密钥
- 为不同环境使用不同的密钥
网络限制
- 使用防火墙规则限制对n8n API的访问
- 考虑为家庭实验室使用VPN或私有网络
- 使用Docker网络进行容器隔离
定期更新
- 保持依赖项更新至最新版本： npm update
- 监控安全公告
- 定期重建Docker镜像
访问控制
- 限制谁能访问MCP服务器
- 在可能的情况下使用只读API密钥
- 审计工作流程定期变更

做出贡献

欢迎投稿！以下是您如何帮助的方式：

报告错误提交一个包含详细信息和复现步骤的问题
建议功能提出一个问题，阐述你的想法和用例
提交拉取请求克隆仓库，进行更改，然后提交拉取请求（PR）
改进文档帮助让这个README文件更出色

开发环境设置

# Fork and clone the repository
git clone https://github.com/nourdeo/mcp-n8n-server.git
cd mcp-n8n-server

# Install dependencies
npm install

# Create a feature branch
git checkout -b feature/your-feature-name

# Make your changes and test
npm run build
npm start

# Commit and push
git add .
git commit -m "Add your feature description"
git push origin feature/your-feature-name

许可证

MIT 许可证 - 详见许可证文件中有详细信息。

资源

官方文档

n8n 文档 - 了解n8n工作流自动化
n8n API 参考手册 - 完成n8n API文档
模型上下文协议 - 了解MCP架构
Claude Desktop（可译为“克劳德桌面版”或根据具体语境简化为“克劳德桌面”） - 下载Claude桌面应用程序
克劳德代码文档 - Claude CLI 文档

社区与支持

n8n社区论坛 - 从n8n社区寻求帮助
MCP GitHub（可译为：“MCP在GitHub上”或“MCP的GitHub页面”，具体根据上下文确定最合适的译法） - MCP规范及示例
人类之间的不和 - 加入Anthropic社区

有问题吗？

如果您有问题或需要帮助：

检查一下故障排除部分；章节
搜索现有问题
打开一个新问题（带有）详细信息

自动化愉快！

使用说明

n8n MCP 服务器

目录

这是什么？

为什么要使用这个？

特点

先决条件

获取您的n8n API密钥

快速入门

安装方法

方法1：Docker（推荐）

步骤1：克隆仓库

步骤2：配置环境变量

步骤3：使用Docker Compose构建并运行

步骤4：验证其是否正在运行

方法2：本地开发

步骤1：安装依赖项

步骤2：配置环境

第三步：构建项目

步骤4：运行服务器

方法3：Portainer部署

步骤1：创建一个新的堆栈

步骤2：上传docker-compose.yml文件

步骤3：添加环境变量

步骤4：部署

配置

连接到Claude桌面版

对于本地安装：

对于Docker安装：

连接到Claude代码（CLI）

可用工具

工作流管理

执行管理

资源管理

使用示例

基本查询

工作流管理

高级工作流创建

调试与监控

项目结构

发展

可用脚本

做出改变

添加新工具

故障排除

连接问题

验证n8n是否可访问：

检查 Docker 日志：

验证环境变量：

认证错误

克劳德未看到服务器

构建错误

安全最佳实践

做出贡献

开发环境设置

许可证

资源

官方文档

社区与支持

相关项目

有问题吗？

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

Unity MCP AI游戏开发工具