使用说明

n8n MCP 服务器 🚀

专业的MCP（模型上下文协议）服务器，用于通过编程方式管理n8n工作流。它使Claude、GPT等AI助手能够无缝地创建、管理和协调n8n工作流。

🚀 快速入门

使用Docker，几分钟内即可启动并运行：

克隆仓库：

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

构建Docker镜像：
```
docker build -t n8n-mcp-server .
```

运行容器： 替换占位符值为 N8N_BASE_URL 并且 N8N_API_KEY 使用您实际的n8n凭据。

docker run -d -p 8080:8080 \
  -e N8N_BASE_URL="https://your-instance.app.n8n.cloud" \
  -e N8N_API_KEY="your-n8n-api-key" \
  --name n8n-mcp-container \
  n8n-mcp-server

连接您的MCP客户端： 将您的MCP客户端（例如，Claude Desktop）指向 http://localhost:8080.

如需更详细的说明，请参阅安装和用法部分。

🎯 项目目标

主要目的

通过标准化、安全的接口，授权AI助手以编程方式管理n8n工作流。

业务目标

✅ 启用AI驱动的工作流自动化
✅ 简化工作流的创建、搜索和管理
✅ 安全高效的n8n API集成
✅ 对开发者友好的工具和文档

成功标准

✅ 工作流的100%功能齐全的CRUD操作
API响应时间小于2秒
✅ 错误率 < 1%
✅ 完全符合MCP协议规范
✅ 完整的文档和示例

✨ 特点

核心业务/核心运营

创建工作流使用节点和连接构建新的n8n工作流
获取工作流通过ID检索工作流详情
列出工作流浏览工作流并应用过滤条件（活动状态、标签、分页）
搜索工作流按名称或标签查找工作流
更新工作流程修改现有工作流程
删除工作流安全地移除工作流
激活/停用控制工作流执行状态
健康检查监视API连接状态

技术特性

🔐 安全认证基于API密钥的身份验证
⚡（闪电符号，常用于表示速度、能量或紧急情况）演出内置缓存，支持可配置的TTL（生存时间）
🔄 这个符号在中文中通常表示“循环”或“重复”的意思，可以翻译为“循环”或根据上下文具体表达为“再次”、“反复”等。 重试机制自动重试，采用指数退避策略
📊 表格/数据图表 全面日志记录带有不同级别的结构化日志记录
🛡️（盾牌） 错误处理强大的错误处理和恢复机制
🔌（电源插头） MCP协议完全符合MCP标准

📋 先决条件

python3.8或更高版本
n8n 实例云托管或自托管，支持API访问
n8n API密钥: 如何创建
MCP 客户端Claude Desktop，或任何兼容MCP的人工智能助手

🛠 安装

方法1：使用Docker（推荐用于生产环境和AI助手）

Docker 能够提供一个隔离的环境来运行项目及其所有依赖项，这是最稳定的方法。

创建Docker镜像： 在项目的主目录中运行以下命令：
```
docker build -t n8n-mcp-server .
```
运行容器： 使用以下命令启动容器。该命令会在后台启动服务器，并将您机器的8080端口重定向到容器的8080端口。

重要： 在运行命令之前 -e 如上所述 N8N_BASE_URL have的常用口语形式 N8N_API_KEY 别忘了用你自己的n8n信息替换环境变量。
```
docker run -d -p 8080:8080 \
  -e N8N_BASE_URL="https://your-instance.app.n8n.cloud" \
  -e N8N_API_KEY="your-n8n-api-key" \
  --name n8n-mcp-container \
  n8n-mcp-server
```
检查日志： 您可以使用以下命令来检查容器的状态和日志：
```
docker logs -f n8n-mcp-container
```

方法2：从源代码（用于开发）

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

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up configuration
cp config/config.example.json config/config.json
# Edit config/config.json with your n8n instance details

方法2：使用pip（即将推出）

pip install n8n-mcp-server

⚙️ 配置

选项1：JSON配置文件

创建 config/config.json：

{
  "n8n": {
    "base_url": "https://your-instance.app.n8n.cloud",
    "api_key": "your-n8n-api-key-here",
    "timeout": 30,
    "max_retries": 3
  },
  "mcp": {
    "server_name": "n8n-mcp-server",
    "version": "1.0.0"
  },
  "logging": {
    "level": "INFO",
    "file_path": "logs/n8n_mcp_server.log"
  },
  "performance": {
    "cache_ttl": 300
  }
}

选项2：环境变量

创建 .env 文件：

N8N_BASE_URL=https://your-instance.app.n8n.cloud
N8N_API_KEY=your-n8n-api-key-here
N8N_TIMEOUT=30
N8N_MAX_RETRIES=3
MCP_SERVER_NAME=n8n-mcp-server
MCP_VERSION=1.0.0
LOG_LEVEL=INFO
LOG_FILE_PATH=logs/n8n_mcp_server.log
CACHE_TTL=300

然后运行：

python -m src.n8n_mcp.server --env

🚀 使用方法

启动服务器

# Using config file
python -m src.n8n_mcp.server

# Using environment variables
python -m src.n8n_mcp.server --env

# Using custom config path
python -m src.n8n_mcp.server /path/to/config.json

与MCP客户端（例如，Claude Desktop）一起使用

您可以将任何兼容MCP的客户端连接到此服务器。以下是几种常见方法：

方法1：连接到Docker容器（推荐）

一旦Docker容器运行起来，它就会在端口上暴露MCP服务器 8080您可以通过定义一个远程服务器将您的MCP客户端连接到它。

在您的MCP客户端配置中（例如。， claude_desktop_config.json), 添加一个指向（某处）的服务器条目 http://localhost:8080：

{
  "mcpServers": {
    "n8n-docker": {
      "url": "http://localhost:8080"
    }
  }
}

记得替换 "n8n-docker" 使用您希望为工具提供商指定的名称。

方法2：从源代码运行（用于开发）

添加到您的Claude桌面配置中（~/Library/Application Support/Claude/claude_desktop_config.json （在 macOS 上）：

{
  "mcpServers": {
    "n8n-local": {
      "command": "python",
      "args": [
        "-m",
        "src.n8n_mcp.server",
        "--env"
      ],
      "cwd": "/absolute/path/to/n8n-mcp-server"
    }
  }
}

确保你有一个 .env 在项目根目录下放置文件，或者在你的shell中导出必要的环境变量。

示例操作

创建一个工作流

# Ask Claude:
"Create a new n8n workflow called 'Data Sync' that syncs data between two systems"

搜索工作流

# Ask Claude:
"Find all workflows with 'email' in their name"

激活一个工作流

# Ask Claude:
"Activate the workflow with ID 'abc123'"

📚 可用工具

1. 创建工作流

创建一个新的n8n工作流。

参数：

name （必填）：工作流名称
nodes （可选）：节点配置数组
connections （可选）：节点连接对象
active （可选）：布尔值，默认为 false
tags （可选）：标签对象的数组

2. 获取工作流

通过ID检索特定的工作流。

参数：

workflow_id （必填）：工作流ID
use_cache （可选）：布尔值，默认为true

3. 列出工作流（list_workflows）

列出工作流，并可选择应用过滤器。

参数：

active （可选）：按激活状态筛选
tags （可选）：标签名称数组
limit （可选）：最大结果数（1-100），默认值为20
offset （可选）：分页偏移量，默认为0

4. 搜索工作流

按名称或标签搜索工作流。

参数：

query （必填）：搜索查询字符串
limit （可选）：最大结果数（1-100），默认为20

5. 更新工作流程

更新现有工作流。

参数：

workflow_id （必填）：工作流ID
name （可选）：新的工作流名称
nodes （可选）：更新节点配置
connections （可选）：更新连接
active （可选）：激活状态
tags （可选）：更新标签

6. 删除工作流

删除一个工作流。

参数：

workflow_id （必填）：工作流ID

7. 激活工作流

激活工作流以使其自动运行。

参数：

workflow_id （必填）：工作流ID

8. 禁用工作流

停用工作流以停止自动执行。

参数：

workflow_id （必填）：工作流ID

9. 健康检查

检查n8n API连接状态。

参数： 无

🏗 项目结构

n8n-mcp-server/
├── src/
│   └── n8n_mcp/
│       ├── __init__.py
│       ├── server.py          # Main MCP server implementation
│       ├── client.py          # n8n API client
│       ├── config.py          # Configuration management
│       └── logging_config.py  # Logging setup
├── config/
│   ├── config.json            # Main configuration
│   └── config.example.json    # Configuration template
├── tests/
│   ├── test_client.py
│   └── test_server.py
├── docs/
│   └── USAGE.md              # Detailed usage guide
├── logs/                      # Log files directory
├── requirements.txt          # Python dependencies
├── setup.py                  # Package setup
├── .gitignore
├── LICENSE
└── README.md                 # This file

🧪 测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src/n8n_mcp --cov-report=html

# Run specific test file
pytest tests/test_client.py

🔧 开发

设置开发环境

# Install development dependencies
pip install -r requirements.txt

# Install pre-commit hooks
pre-commit install

# Run code formatting
black src/ tests/

# Run linting
flake8 src/ tests/

# Type checking
mypy src/

代码风格

这个项目后续为：

PEP 8（Python增强提案8） 风格指南
黑色用于代码格式化
isort（通常指Python中的代码排序工具，用于对导入语句进行排序） 用于进口分类
类型提示 为了提高代码质量

🐛 故障排除

常见问题

问题“配置错误：无效的 n8n 配置”

解决方案请检查config.json中的n8n基础URL和API密钥

问题API健康检查失败

解决方案请验证您的n8n实例是否可访问，并且API密钥是否有效

问题“导入错误：没有名为 'mcp' 的模块”

解决方案安装依赖项： pip install -r requirements.txt

调试模式

在 config.json 中启用调试日志记录：

{
  "logging": {
    "level": "DEBUG"
  }
}

📊 性能优化技巧

缓存调整 cache_ttl 根据您的工作流程更新频率
分页使用 limit 和 offset 对于大型工作流程列表
重试逻辑调音 max_retries 针对不稳定网络
超时增加 timeout 对于复杂的工作流程

🤝 贡献

我们欢迎投稿！请参阅 CONTRIBUTING.md 翻译为中文是：“贡献指南.md” 或 “贡献规范.md”（具体翻译可能根据上下文略有调整，但大意相同）。这里，“CONTRIBUTING”通常指的是关于如何为项目做出贡献的指南或规范，而“.md”是Markdown文件的扩展名详情见下。

为贡献者提供的快速入门指南

为仓库创建分支（或“克隆仓库”）
创建一个特性分支： git checkout -b feature/amazing-feature
提交您的更改： git commit -m 'Add amazing feature'
推送到分支： git push origin feature/amazing-feature
提交一个拉取请求

📝 更新日志

见 CHANGELOG.md 翻译为中文是：“变更日志文件（Markdown 格式）” 用于版本历史记录。

📄 许可证

这个项目采用MIT许可证授权——详见许可证文件中有详细信息。

🙏 致谢

n8n 为卓越的工作流程自动化平台
模型上下文协议对于MCP标准
“Anthropic”可以翻译为“人类中心主义”或“以人为本”，具体翻译取决于上下文和使用场景。在人工智能领域，有时也会直接使用“Anthropic”作为专有名词，不进行翻译为克劳德和MCP（或某特定概念/项目）带来灵感

📞 支持

问题： GitHub 问题（或议题）
讨论: GitHub 讨论区
电子邮件support@yourproject.com（可翻译为）：support@yourproject.com（注：此邮件地址本身无需翻译，但若需说明其用途，可表述为“用于联系项目的支持团队的邮箱地址：support@yourproject.com”）

🔗 链接

为n8n和AI自动化社区倾心打造

使用说明

n8n MCP 服务器 🚀

🚀 快速入门

🎯 项目目标

主要目的

业务目标

成功标准

✨ 特点

核心业务/核心运营

技术特性

📋 先决条件

🛠 安装

方法1：使用Docker（推荐用于生产环境和AI助手）

方法2：从源代码（用于开发）

方法2：使用pip（即将推出）

⚙️ 配置

选项1：JSON配置文件

选项2：环境变量

🚀 使用方法

启动服务器

与MCP客户端（例如，Claude Desktop）一起使用

方法1：连接到Docker容器（推荐）

方法2：从源代码运行（用于开发）

示例操作

创建一个工作流

搜索工作流

激活一个工作流

📚 可用工具

1. 创建工作流

2. 获取工作流

3. 列出工作流（list_workflows）

4. 搜索工作流

5. 更新工作流程

6. 删除工作流

7. 激活工作流

8. 禁用工作流

9. 健康检查

🏗 项目结构

🧪 测试

🔧 开发

设置开发环境

代码风格

🐛 故障排除

常见问题

调试模式

📊 性能优化技巧

🤝 贡献

为贡献者提供的快速入门指南

📝 更新日志

📄 许可证

🙏 致谢

📞 支持

🔗 链接

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

Unity MCP AI游戏开发工具