内容
# n8n-free-mcp
**免费且开源的MCP服务器，用于[n8n](https://n8n.io)。** 直接从Claude Code、Claude Desktop、Cursor或任何[模型上下文协议](https://modelcontextprotocol.io)客户端管理您的工作流、调试执行并控制您自行托管的n8n实例。
- 🆓 100% 免费，MIT许可 — 无付费墙，无遥测
- 🏠 为自行托管/家庭实验室n8n实例而建（也适用于n8n Cloud）
- 🔑 使用n8n的官方公共API（`/api/v1`）并使用您自己的API密钥
- 🪶 小巧：一个文件，两个依赖项（`@modelcontextprotocol/sdk` + `zod`）
- 🧠 适合上下文：列表工具返回紧凑的摘要，而不是转储完整的工作流JSON
## 工具
| 工具 | 描述 |
|---|---|
| `list_workflows` | 列出工作流（ID、名称、活动、标签、节点数），带有过滤器 + 分页 |
| `get_workflow` | 完整工作流JSON：节点、连接、设置 |
| `create_workflow` | 从n8n格式的JSON创建新的工作流 |
| `update_workflow` | 替换工作流（自动剥离只读字段） |
| `activate_workflow` / `deactivate_workflow` | 切换工作流的触发器 |
| `delete_workflow` | 删除工作流（不可逆 ⚠️） |
| `list_executions` | 列出执行结果，按状态（`error`/`success`/`waiting`）或工作流过滤 |
| `get_execution` | 执行结果详情 — 启用`includeData=true`返回每个节点的I/O用于调试 |
| `delete_execution` | 删除执行记录 |
| `list_tags` | 列出实例标签 |
| `check_connection` | 验证实例是否可达且API密钥有效 |
## 安装
### 1. 获取n8n API密钥
在您的n8n实例中：**设置 → n8n API → 创建API密钥**。
### 2. 安装
```bash
git clone https://github.com/jserna0001/n8n-free-mcp.git
cd n8n-free-mcp
npm install
npm run build
```
### 3. 配置您的MCP客户端
**Claude Code:**
```bash
claude mcp add --scope user n8n \
--env N8N_API_URL=https://your-n8n-instance.com \
--env N8N_API_KEY=your-api-key \
-- node /path/to/n8n-free-mcp/dist/index.js
```
**Claude Desktop / Cursor / 其他客户端** (`claude_desktop_config.json`, `mcp.json`等）：
```json
{
"mcpServers": {
"n8n": {
"command": "node",
"args": ["/path/to/n8n-free-mcp/dist/index.js"],
"env": {
"N8N_API_URL": "https://your-n8n-instance.com",
"N8N_API_KEY": "your-api-key"
}
}
}
}
```
**替代：`.env`文件。** 与其从客户端传递环境变量，请复制`.env.example`到`.env`到项目根目录并填写。客户端的环境变量优先。
### 4. 试用
询问您的助手类似的问题：
- *"列出我的n8n工作流"*
- *"显示最后运行的失败执行结果并诊断错误"*
- *"停用名为X的工作流"*
- *"复制此工作流但更改Webhook路径"*
## 备注
- n8n公共API不会暴露凭证*值*（按设计）。凭证管理工具故意不在范围内。
- `update_workflow`执行完全替换（`PUT`），这是n8n API的要求 — 使用`get_workflow`获取，修改，然后更新。
- n8n API密钥是具有过期日期的JWT。如果您开始获取401错误，请生成新的密钥。
## 贡献
问题和PR欢迎。路线图上的想法：
- [ ] 通过Webhook测试URL触发工作流
- [ ] 变量和项目端点
- [ ] npm包（`npx n8n-free-mcp`）
- [ ] Docker镜像
## 许可证
[MIT](LICENSE) © Justine Serna
