内容
# n8n-MCP
[](https://opensource.org/licenses/MIT)
[](https://github.com/czlonkowski/n8n-mcp)
[](https://www.npmjs.com/package/n8n-mcp)
[](https://codecov.io/gh/czlonkowski/n8n-mcp)
[](https://github.com/czlonkowski/n8n-mcp/actions)
[](https://github.com/n8n-io/n8n)
[](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
[](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)
模型上下文协议（MCP）服务器，为AI助手提供对n8n节点文档、属性和操作的全面访问。几分钟内部署即可让Claude和其他AI助手深入了解n8n的1,084个工作流自动化节点（537个核心节点 + 547个社区节点）。
## 概述
n8n-MCP作为n8n工作流自动化平台和AI模型之间的桥梁，使它们能够有效理解和操作n8n节点。它提供对以下内容的 структури化访问：
- 📚 **1,084个n8n节点** - 537个核心节点 + 547个社区节点（301个已验证）
- 🔧 **节点属性** - 99%覆盖，附带详细模式
- ⚡ **节点操作** - 63.6%覆盖可用操作
- 📄 **文档** - 87%覆盖官方n8n文档（包括AI节点）
- 🤖 **AI工具** - 检测到265种AI能力工具变体，附带完整文档
- 💡 **现实世界示例** - 2,646个预提取的流行模板配置
- 🎯 **模板库** - 2,709个工作流模板，100%元数据覆盖
- 🌐 **社区节点** - 搜索已验证的社区集成，附带`source`筛选（新增！）
## ⚠️ 重要安全警告
**绝不能直接使用AI编辑生产工作流！** 始终：
- 🔄 **复制**工作流后再使用AI工具
- 🧪 **在开发环境**中测试
- 💾 **导出备份**重要工作流
- ⚡ **验证更改**后再部署到生产环境
AI结果不可预测。保护你的工作！
## 🚀 快速开始
### 选项1：托管服务（最简单 - 无需设置！） ☁️
**尝试n8n-MCP最快的方式** - 无需安装，无需配置：
👉 **[dashboard.n8n-mcp.com](https://dashboard.n8n-mcp.com)**
- ✅ **免费层**: 每天100次工具调用
- ✅ **即时访问**: 立即开始构建工作流
- ✅ **始终保持最新**: 最新n8n节点和模板
- ✅ **无需基础设施**: 我们处理一切
只需注册，获取你的API密钥，然后连接你的MCP客户端。
---
## 🏠 自托管选项
更喜欢自己运行n8n-MCP？选择你的部署方式：
### 选项A：npx（快速本地设置） 🚀
几分钟内运行n8n-MCP：
[](https://youtu.be/5CccjiLLyaY?si=Z62SBGlw9G34IQnQ&t=343)
**先决条件：** [Node.js](https://nodejs.org/) 已安装在你的系统上
```bash
# 直接使用npx运行（无需安装！）
npx n8n-mcp
```
添加到Claude Desktop配置：
> ⚠️ **重要**: `MCP_MODE: "stdio"`环境变量是**必需**的，用于Claude Desktop。没有它，你将在UI中看到类似`"Unexpected token..."`的JSON解析错误。该变量确保只有JSON-RPC消息发送到stdout，防止调试日志干扰协议。
**基本配置（仅限文档工具）：**
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "npx",
"args": ["n8n-mcp"],
"env": {
"MCP_MODE": "stdio",
"LOG_LEVEL": "error",
"DISABLE_CONSOLE_OUTPUT": "true"
}
}
}
}
```
**完整配置（带有n8n管理工具）：**
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "npx",
"args": ["n8n-mcp"],
"env": {
"MCP_MODE": "stdio",
"LOG_LEVEL": "error",
"DISABLE_CONSOLE_OUTPUT": "true",
"N8N_API_URL": "https://your-n8n-instance.com",
"N8N_API_KEY": "your-api-key"
}
}
}
}
```
> **注意**: npx将自动下载并运行最新版本。该软件包包含一个预建的数据库，包含所有n8n节点信息。
**配置文件位置：**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
**更新配置后重启Claude Desktop** - 就是这样！ 🎉
### 选项B：Docker（隔离和可复制） 🐳
**先决条件：** Docker已安装在你的系统上
<details>
<summary><strong>📦 安装Docker</strong>（点击展开）</summary>
**macOS：**
```bash
# 使用Homebrew
brew install --cask docker
# 或从 https://www.docker.com/products/docker-desktop/ 下载
```
**Linux（Ubuntu/Debian）：**
```bash
# 更新软件包索引
sudo apt-get update
# 安装Docker
sudo apt-get install docker.io
# 启动Docker服务
sudo systemctl start docker
sudo systemctl enable docker
# 将用户添加到docker组（可选，运行无需sudo）
sudo usermod -aG docker $USER
# 注销并重新登录以使其生效
```
**Windows：**
```bash
# 选项1：使用winget（Windows包管理器）
winget install Docker.DockerDesktop
# 选项2：使用Chocolatey
choco install docker-desktop
# 选项3：从 https://www.docker.com/products/docker-desktop/ 下载安装程序
```
**验证安装：**
```bash
docker --version
```
</details>
```bash
# 拉取Docker镜像（约280MB，无n8n依赖！）
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
```
添加到Claude Desktop配置：
**基本配置（仅限文档工具）：**
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e", "MCP_MODE=stdio",
"-e", "LOG_LEVEL=error",
"-e", "DISABLE_CONSOLE_OUTPUT=true",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}
```
**完整配置（带有n8n管理工具）：**
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e", "MCP_MODE=stdio",
"-e", "LOG_LEVEL=error",
"-e", "DISABLE_CONSOLE_OUTPUT=true",
"-e", "N8N_API_URL=https://your-n8n-instance.com",
"-e", "N8N_API_KEY=your-api-key",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}
```
>💡 提示：如果你在同一台机器上本地运行n8n（例如，通过Docker），请使用http://host.docker.internal:5678作为N8N_API_URL。
> **注意**: n8n API凭证是可选的。没有它们，你将可以访问所有文档和验证工具。有了它们，你还将获得工作流管理功能（创建、更新、执行工作流）。
### 🏠 本地n8n实例配置
如果你在本地运行n8n（例如，`http://localhost:5678` 或 Docker），你需要允许本地Webhook：
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "docker",
"args": [
"run", "-i", "--rm", "--init",
"-e", "MCP_MODE=stdio",
"-e", "LOG_LEVEL=error",
"-e", "DISABLE_CONSOLE_OUTPUT=true",
"-e", "N8N_API_URL=http://host.docker.internal:5678",
"-e", "N8N_API_KEY=your-api-key",
"-e", "WEBHOOK_SECURITY_MODE=moderate",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}
```
> ⚠️ **重要：** 设置`WEBHOOK_SECURITY_MODE=moderate`以允许向本地n8n实例发送Webhook。这对于本地开发是安全的，同时仍然阻止私有网络和云元数据。
**重要：** `-i`标志对于MCP stdio通信是必需的。
> 🔧 如果你在使用Docker时遇到任何问题，请查看我们的 [Docker故障排除指南](./docs/DOCKER_TROUBLESHOOTING.md)。
**配置文件位置：**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
**更新配置后重启Claude Desktop** - 就是这样！ 🎉
## 🔐 隐私和遥测
n8n-mcp收集匿名使用统计数据以改进工具。 [查看我们的隐私政策](./PRIVACY.md)。
### 退出
**对于npx用户：**
```bash
npx n8n-mcp telemetry disable
```
**对于Docker用户：**
在Docker配置中添加以下环境变量：
```json
"-e", "N8N_MCP_TELEMETRY_DISABLED=true"
```
示例，在Claude Desktop配置中：
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e", "MCP_MODE=stdio",
"-e", "LOG_LEVEL=error",
"-e", "N8N_MCP_TELEMETRY_DISABLED=true",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}
```
**对于docker-compose用户：**
在环境文件或docker-compose.yml中设置：
```yaml
environment:
N8N_MCP_TELEMETRY_DISABLED: "true"
```
## ⚙️ 数据库和内存配置
### 数据库适配器
n8n-mcp使用SQLite存储节点文档。提供了两个适配器：
1. **better-sqlite3** （Docker默认）
- 原生C++绑定，提供最佳性能
- 直接磁盘写入（无内存开销）
- **现在默认**在Docker镜像中启用（v2.20.2+）
- 内存使用：~100-120 MB稳定
2. **sql.js** （备用）
- 纯JavaScript实现
- 内存数据库，定期保存
- 当better-sqlite3编译失败时使用
- 内存使用：~150-200 MB稳定
### 内存优化（sql.js）
如果你使用sql.js备用方案，可以配置保存间隔以平衡数据安全性和内存效率：
**环境变量：**
```bash
SQLJS_SAVE_INTERVAL_MS=5000 # 默认：5000ms（5秒）
```
**用法：**
- 控制数据库更改后等待多久再保存到磁盘
- 较低的值 = 更频繁的保存 = 较高的内存变化
- 较高的值 = 不太频繁的保存 = 较低的内存使用
- 最小值：100ms
- 推荐：生产环境下为5000-10000ms
**Docker配置：**
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e", "SQLJS_SAVE_INTERVAL_MS=10000",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}
```
**docker-compose：**
```yaml
environment:
SQLJS_SAVE_INTERVAL_MS: "10000"
```
## 💖 支持该项目
<div align="center">
<a href="https://github.com/sponsors/czlonkowski">
<img src="https://img.shields.io/badge/Sponsor-❤️-db61a2?style=for-the-badge&logo=github-sponsors" alt="赞助n8n-mcp" />
</a>
</div>
**n8n-mcp**最初是一个个人工具，但现在帮助数万名开发者高效自动化工作流。维护和开发该项目与我的付费工作竞争。
你的赞助帮助我：
- 🚀 **专注时间**进行新功能开发
- 🐛 **快速响应**问题
- 📚 **保持文档**更新
- 🔄 **确保兼容性**与最新的n8n版本
每笔赞助直接转化为投入，使n8n-mcp对所有人变得更好。 **[成为赞助者 →](https://github.com/sponsors/czlonkowski)**
---
### 选项C：本地安装（用于开发）
**先决条件：** [Node.js](https://nodejs.org/) 已安装在你的系统上
```bash
# 1. 克隆并设置
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild
# 2. 测试它是否有效
npm start
```
添加到Claude Desktop配置：
**基本配置（仅限文档工具）：**
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "node",
"args": ["/绝对路径/to/n8n-mcp/dist/mcp/index.js"],
"env": {
"MCP_MODE": "stdio",
"LOG_LEVEL": "error",
"DISABLE_CONSOLE_OUTPUT": "true"
}
}
}
}
```
**完整配置（带有n8n管理工具）：**
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "node",
"args": ["/绝对路径/to/n8n-mcp/dist/mcp/index.js"],
"env": {
"MCP_MODE": "stdio",
"LOG_LEVEL": "error",
"DISABLE_CONSOLE_OUTPUT": "true",
"N8N_API_URL": "https://your-n8n-instance.com",
"N8N_API_KEY": "your-api-key"
}
}
}
}
```
> **注意**: n8n API凭证可以通过`.env`文件（从`.env.example`创建）或直接在Claude配置中指定，如上所示。
> 💡 提示：如果你在同一台机器上本地运行n8n（例如，通过Docker），请使用http://host.docker.internal:5678作为N8N_API_URL。
### 选项D：Railway云部署（单键部署） ☁️
**先决条件：** Railway账户（提供免费层）
通过Railway的云平台，在零配置的情况下部署n8n-MCP：
[](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)
**益处：**
- ☁️ **即时云托管** - 无需服务器设置
- 🔒 **默认安全** - 包含HTTPS，身份验证令牌警告
- 🌐 **全球访问** - 从任何Claude Desktop连接
- ⚡ **自动扩展** - Railway处理基础设施
- 📊 **内置监控** - 包含日志和指标
**快速设置：**
1. 点击上面的“在Railway上部署”按钮
2. 登录Railway（或创建免费账户）
3. 配置部署（项目名称，区域）
4. 点击“部署”，等待约2-3分钟
5. 复制部署网址和身份验证令牌
6. 使用HTTPS网址将配置添加到Claude Desktop
> 📚 **有关详细设置说明，故障排除和配置示例，请参阅我们的 [Railway部署指南](./docs/RAILWAY_DEPLOYMENT.md)**
**配置文件位置：**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
**更新配置后重启Claude Desktop** - 就是这样！ 🎉
## 🔧 n8n集成
想将n8n-MCP与你的n8n实例结合使用？查看我们的综合 [n8n部署指南](./docs/N8N_DEPLOYMENT.md)，了解：
- 使用MCP客户端工具进行本地测试
- 使用Docker Compose进行生产部署
- 在Hetzner、AWS等云提供商上进行云部署
- 故障排除和安全最佳实践
## 💻 连接你的IDE
n8n-MCP与多种AI驱动的IDE和工具配合使用。选择你喜欢的开发环境：
### [Claude Code](./docs/CLAUDE_CODE_SETUP.md)
只需输入“添加此MCP服务器”，然后粘贴配置即可快速设置Claude Code CLI。
### [Visual Studio Code](./docs/VS_CODE_PROJECT_SETUP.md)
有关带有GitHub Copilot集成和MCP支持的VS Code的完整设置指南。
### [Cursor](./docs/CURSOR_SETUP.md)
将n8n-MCP连接到Cursor IDE的逐步教程，带有自定义规则。
### [Windsurf](./docs/WINDSURF_SETUP.md)
使用项目规则将n8n-MCP与Windsurf集成。
### [Codex](./docs/CODEX_SETUP.md)
将n8n-MCP与Codex集成的完整指南。
### [Antigravity](./docs/ANTIGRAVITY_SETUP.md)
将n8n-MCP与Antigravity集成的完整指南。
## 🎓 添加Claude技能（可选）
通过专门的技能提升n8n工作流构建能力，教你AI如何构建生产就绪的工作流！
[](https://www.youtube.com/watch?v=e6VvRqmUY2Y)
了解更多： [n8n-skills 仓库](https://github.com/czlonkowski/n8n-skills)
## 🤖 Claude项目设置
为了在与Claude项目结合使用n8n-MCP时获得最佳结果，请使用这些增强的系统指令：
````markdown
你是使用n8n自动化软件的专家，使用n8n-MCP工具。你的角色是使用最大精度和效率设计、构建和验证n8n工作流。
## 核心原则
### 1. 静默执行
关键：无注释执行工具。仅在所有工具完成后响应。
❌ 差： “让我搜索Slack节点... 好的，现在让我获取详细信息...”
✅ 好： [并行执行search_nodes和get_node，然后响应 ]
### 2. 并行执行
当操作独立时，并行执行以最大限度地提高性能。
✅ 好：同时调用search_nodes、list_nodes和search_templates
❌ 差：顺序调用工具（等待一个调用完成后再调用下一个）
### 3. 优先使用模板
在从头开始构建之前，始终检查模板（可用2,709个）。
### 4. 多级验证
使用validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow模式。
### 5. 绝不信任默认值
⚠️ 关键：默认参数值是运行时失败的最常见原因。
始终显式配置控制节点行为的所有参数。
````
## 工作流程
1. **开始**: 调用 `tools_documentation()` 以获取最佳实践
2. **模板发现阶段** (第一步 - 并行搜索多个模板)
- `search_templates({searchMode: 'by_metadata', complexity: 'simple'})` - 智能过滤
- `search_templates({searchMode: 'by_task', task: 'webhook_processing'})` - 按任务分类
- `search_templates({query: 'slack notification'})` - 文本搜索（默认搜索模式为'keyword'）
- `search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']})` - 按节点类型
**过滤策略**:
- 初学者：`complexity: "simple"` + `maxSetupMinutes: 30`
- 按角色：`targetAudience: "marketers"` | `"developers"` | `"analysts"`
- 按时间：`maxSetupMinutes: 15` 以获取快速解决方案
- 按服务：`requiredService: "openai"` 以确保兼容性
3. **节点发现** （如果没有合适的模板 - 并行执行）
- 深入思考需求。如果不明确，请提出澄清问题。
- `search_nodes({query: 'keyword', includeExamples: true})` - 并行搜索多个节点
- `search_nodes({query: 'trigger'})` - 浏览触发器
- `search_nodes({query: 'AI agent langchain'})` - 具备AI能力的节点
4. **配置阶段** （并行执行多个节点）
- `get_node({nodeType, detail: 'standard', includeExamples: true})` - 基本属性（默认）
- `get_node({nodeType, detail: 'minimal'})` - 仅基本元数据（约200个令牌）
- `get_node({nodeType, detail: 'full'})` - 完整信息（约3000-8000个令牌）
- `get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'})` - 查找特定属性
- `get_node({nodeType, mode: 'docs'})` - 易读的Markdown文档
- 在继续之前，向用户展示工作流架构以获取批准
5. **验证阶段** （并行执行多个节点）
- `validate_node({nodeType, config, mode: 'minimal'})` - 快速必填字段检查
- `validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - 完整验证并修复错误
- 在继续之前修复所有错误
6. **构建阶段**
- 如果使用模板：`get_template(templateId, {mode: "full"})`
- **强制署名**："基于 **[author.name]** （@[username]）的模板。在 [url] 处查看。"
- 从验证的配置中构建
- ⚠️ 显式设置所有参数 - 绝不依赖默认值
- 连接节点并具有正确的结构
- 添加错误处理
- 使用n8n表达式：$json, $node["NodeName"].json
- 在工件中构建（除非部署到n8n实例）
7. **工作流验证** （在部署前）
- `validate_workflow(workflow)` - 完整验证
- `validate_workflow_connections(workflow)` - 结构检查
- `validate_workflow_expressions(workflow)` - 表达式验证
- 在部署前修复所有问题
8. **部署** （如果配置了n8n API）
- `n8n_create_workflow(workflow)` - 部署
- `n8n_validate_workflow({id})` - 部署后检查
- `n8n_update_partial_workflow({id, operations: [...]})` - 批量更新
- `n8n_test_workflow({workflowId})` - 测试工作流执行
## 重要警告
### ⚠️ 绝不信任默认值
默认值会导致运行时失败。示例：
```json
// ❌ 运行时失败
{resource: "message", operation: "post", text: "Hello"}
// ✅ 正确 - 所有参数显式
{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}
```
### ⚠️ 示例可用性
`includeExamples: true` 返回来自工作流模板的真实配置。
- 覆盖范围因节点受欢迎程度而异
- 当没有可用示例时，使用 `get_node` + `validate_node({mode: 'minimal'})`
## 验证策略
### 级别 1 - 快速检查（在构建前）
`validate_node({nodeType, config, mode: 'minimal'})` - 仅必填字段（<100毫秒）
### 级别 2 - 全面（在构建前）
`validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - 完整验证并修复错误
### 级别 3 - 完整（在构建后）
`validate_workflow(workflow)` - 连接、表达式、AI工具
### 级别 4 - 部署后
1. `n8n_validate_workflow({id})` - 验证已部署的工作流
2. `n8n_autofix_workflow({id})` - 自动修复常见错误
3. `n8n_executions({action: 'list'})` - 监控执行状态
## 响应格式
### 初始创建
```
[静默工具执行并行]
创建工作流：
- Webhook 触发器 → Slack 通知
- 配置：POST /webhook → #general 频道
验证：✅ 所有检查通过
```
### 修改
```
[静默工具执行]
更新工作流：
- 添加了 HTTP 节点的错误处理
- 修复了必填的 Slack 参数
变更验证成功。
```
## 批量操作
使用 `n8n_update_partial_workflow` 并在单个调用中传递多个操作：
✅ 良好 - 批量多个操作：
```json
n8n_update_partial_workflow({
id: "wf-123",
operations: [
{type: "updateNode", nodeId: "slack-1", changes: {...}},
{type: "updateNode", nodeId: "http-1", changes: {...}},
{type: "cleanStaleConnections"}
]
})
```
❌ 差 - 分别调用：
```json
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
```
### 关键：addConnection 语法
`addConnection` 操作需要 **四个单独的字符串参数**。常见的错误会导致令人误解的错误。
❌ 错误 - 对象格式（失败并提示“Expected string, received object”）：
```json
{
"type": "addConnection",
"connection": {
"source": {"nodeId": "node-1", "outputIndex": 0},
"destination": {"nodeId": "node-2", "inputIndex": 0}
}
}
```
❌ 错误 - 组合字符串（失败并提示“Source node not found”）：
```json
{
"type": "addConnection",
"source": "node-1:main:0",
"target": "node-2:main:0"
}
```
✅ 正确 - 四个单独的字符串参数：
```json
{
"type": "addConnection",
"source": "node-id-string",
"target": "target-node-id-string",
"sourcePort": "main",
"targetPort": "main"
}
```
**参考**：[GitHub 问题 #327](https://github.com/czlonkowski/n8n-mcp/issues/327)
### ⚠️ 关键：IF 节点多输出路由
IF 节点有 **两个输出** （TRUE 和 FALSE）。使用 **`branch` 参数** 将路由到正确的输出：
✅ 正确 - 路由到 TRUE 分支（当条件满足时）：
```json
{
"type": "addConnection",
"source": "if-node-id",
"target": "success-handler-id",
"sourcePort": "main",
"targetPort": "main",
"branch": "true"
}
```
✅ 正确 - 路由到 FALSE 分支（当条件不满足时）：
```json
{
"type": "addConnection",
"source": "if-node-id",
"target": "failure-handler-id",
"sourcePort": "main",
"targetPort": "main",
"branch": "false"
}
```
**常见模式** - 完整的 IF 节点路由：
```json
n8n_update_partial_workflow({
id: "workflow-id",
operations: [
{type: "addConnection", source: "If Node", target: "True Handler", sourcePort: "main", targetPort: "main", branch: "true"},
{type: "addConnection", source: "If Node", target: "False Handler", sourcePort: "main", targetPort: "main", branch: "false"}
]
})
```
**注意**：如果没有 `branch` 参数，两个连接可能会最终在同一个输出上，从而导致逻辑错误！
### removeConnection 语法
使用相同的四参数格式：
```json
{
"type": "removeConnection",
"source": "source-node-id",
"target": "target-node-id",
"sourcePort": "main",
"targetPort": "main"
}
```
## 示例工作流
### 基于模板的方法
```
// 步骤 1：模板发现（并行执行）
[静默执行]
search_templates({
searchMode: 'by_metadata',
requiredService: 'slack',
complexity: 'simple',
targetAudience: 'marketers'
})
search_templates({searchMode: 'by_task', task: 'slack_integration'})
// 步骤 2：使用模板
get_template(templateId, {mode: 'full'})
validate_workflow(workflow)
// 响应后所有工具完成：
"由 **David Ashby** （@cfomodz）找到模板。
在：https://n8n.io/workflows/2414 处查看
验证：✅ 所有检查通过"
```
### 从零开始构建（如果没有模板）
// 步骤 1：发现（并行执行）
[静默执行]
search_nodes({query: 'slack', includeExamples: true})
search_nodes({query: 'communication trigger'})
// 步骤 2：配置（并行执行）
[静默执行]
get_node({nodeType: 'n8n-nodes-base.slack', detail: 'standard', includeExamples: true})
get_node({nodeType: 'n8n-nodes-base.webhook', detail: 'standard', includeExamples: true})
// 步骤 3：验证（并行执行）
[静默执行]
validate_node({nodeType: 'n8n-nodes-base.slack', config, mode: 'minimal'})
validate_node({nodeType: 'n8n-nodes-base.slack', config: fullConfig, mode: 'full', profile: 'runtime'})
// 步骤 4：构建
// 使用验证的配置构建工作流
// ⚠️ 显式设置所有参数
// 步骤 5：验证
[静默执行]
validate_workflow(workflowJson)
// 响应后所有工具完成：
"创建工作流：Webhook → Slack
验证：✅ 通过"
```
### 批量更新
```json
// 一次调用多个操作
n8n_update_partial_workflow({
id: "wf-123",
operations: [
{type: "updateNode", nodeId: "slack-1", changes: {position: [100, 200]}},
{type: "updateNode", nodeId: "http-1", changes: {position: [300, 200]}},
{type: "cleanStaleConnections"}
]
})
```
## 重要规则
### 核心行为
1. **静默执行** - 工具之间无评论
2. **默认并行** - 默认情况下同时执行独立操作
3. **模板优先** - 始终在构建前检查（有 2709 个可用）
4. **多级验证** - 快速检查 → 完整验证 → 工作流验证
5. **绝不信任默认值** - 显式配置所有参数
### 署名和积分
- **强制模板署名**：分享作者姓名、用户名和 n8n.io 链接
- **模板验证** - 部署前始终验证（可能需要更新）
### 性能
- **批量操作** - 使用具有多个更改的差异操作
- **并行执行** - 同时搜索、验证和配置
- **模板元数据** - 使用智能过滤以实现更快的发现
### 代码节点用法
- **避免可能时** - 优先使用标准节点
- **仅在必要时** - 将代码节点作为最后的手段
- **AI 工具能力** - 任何节点都可以是 AI 工具（不仅仅是标记的节点）
### 最受欢迎的 n8n 节点（用于 get_node）：
1. **n8n-nodes-base.code** - JavaScript/Python 脚本
2. **n8n-nodes-base.httpRequest** - HTTP API 调用
3. **n8n-nodes-base.webhook** - 事件驱动的触发器
4. **n8n-nodes-base.set** - 数据转换
5. **n8n-nodes-base.if** - 条件路由
6. **n8n-nodes-base.manualTrigger** - 手动工作流执行
7. **n8n-nodes-base.respondToWebhook** - Webhook 响应
8. **n8n-nodes-base.scheduleTrigger** - 基于时间的触发器
9. **@n8n/n8n-nodes-langchain.agent** - AI 代理
10. **n8n-nodes-base.googleSheets** - 电子表格集成
11. **n8n-nodes-base.merge** - 数据合并
12. **n8n-nodes-base.switch** - 多分支路由
13. **n8n-nodes-base.telegram** - Telegram 机器人集成
14. **@n8n/n8n-nodes-langchain.lmChatOpenAi** - OpenAI 聊天模型
15. **n8n-nodes-base.splitInBatches** - 批处理
16. **n8n-nodes-base.openAi** - OpenAI 旧节点
17. **n8n-nodes-base.gmail** - 电子邮件自动化
18. **n8n-nodes-base.function** - 自定义函数
19. **n8n-nodes-base.stickyNote** - 工作流文档
20. **n8n-nodes-base.executeWorkflowTrigger** - 子工作流调用
**注意**：LangChain 节点使用 `@n8n/n8n-nodes-langchain.` 前缀，核心节点使用 `n8n-nodes-base.` 前缀
````
请保存这些说明在您的Claude项目中以实现最佳的n8n工作流协助，并具有智能模板发现。## 🚨 重要：共享指南
该项目是 MIT 许可的，对每个人免费。但是：
- **✅ 可以**：免费分享此仓库并提供适当的署名
- **✅ 可以**：在您的第一个帖子/视频中包含指向 https://github.com/czlonkowski/n8n-mcp 的直接链接
- **❌ 不允许**：将此免费工具置于参与要求后面（例如，点赞、关注、评论）
- **❌ 不允许**：用于社交媒体上的参与度农场
该工具被创建以造福整个 n8n 社区，没有任何摩擦。请尊重 MIT 许可精神，保持其对所有人可访问。
### 示例用法
```typescript
// 获取不同详细程度的节点信息
get_node({
nodeType: "nodes-base.httpRequest",
detail: "standard", // 默认：基本属性
includeExamples: true // 包含来自模板的现实示例
})
// 获取文档
get_node({
nodeType: "nodes-base.slack",
mode: "docs" // 人类可读的 Markdown 文档
})
// 搜索特定属性
get_node({
nodeType: "nodes-base.httpRequest",
mode: "search_properties",
propertyQuery: "authentication"
})
// 版本历史和重大变更
get_node({
nodeType: "nodes-base.httpRequest",
mode: "versions" // 查看所有版本及其摘要
})
// 搜索带有配置示例的节点
search_nodes({
query: "send email gmail",
includeExamples: true // 返回每个节点的前 2 个配置
})
// 仅搜索社区节点
search_nodes({
query: "scraping",
source: "community" // 选项：all, core, community, verified
})
// 搜索已验证的社区节点
search_nodes({
query: "pdf",
source: "verified" // 仅限已验证的社区集成
})
// 验证节点配置
validate_node({
nodeType: "nodes-base.httpRequest",
config: { method: "POST", url: "..." },
mode: "full",
profile: "runtime" // 或 "minimal", "ai-friendly", "strict"
})
// 快速必填字段检查
validate_node({
nodeType: "nodes-base.slack",
config: { resource: "message", operation: "send" },
mode: "minimal"
})
// 按任务搜索模板
search_templates({
searchMode: "by_task",
task: "webhook_processing"
})
```
## 💻 本地开发设置
适用于贡献者和高级用户：
**前提条件：**
- [Node.js](https://nodejs.org/) （任意版本 - 如有需要自动回退）
- npm 或 yarn
- Git
```bash
# 1. 克隆仓库
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
# 2. 克隆 n8n 文档（可选但推荐）
git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs
# 3. 安装和构建
npm install
npm run build
# 4. 初始化数据库
npm run rebuild
# 5. 启动服务器
npm start # stdio 模式适用于 Claude Desktop
npm run start:http # HTTP 模式适用于远程访问
```
### 开发命令
```bash
# 构建和测试
npm run build # 构建 TypeScript
npm run rebuild # 重建节点数据库
npm run test-nodes # 测试关键节点
npm run validate # 验证节点数据
npm test # 运行所有测试
# 更新依赖项
npm run update:n8n:check # 检查 n8n 更新
npm run update:n8n # 更新 n8n 包
# 运行服务器
npm run dev # 开发并自动重新加载
npm run dev:http # HTTP 开发模式
```
## 📚 文档
### 设置指南
- [安装指南](./docs/INSTALLATION.md) - 全面的安装说明
- [Claude Desktop 设置](./docs/README_CLAUDE_SETUP.md) - 详细的 Claude 配置
- [Docker 指南](./docs/DOCKER_README.md) - 高级 Docker 部署选项
- [MCP 快速入门](./docs/MCP_QUICK_START_GUIDE.md) - 快速开始使用 n8n-MCP
### 功能文档
- [工作流差异操作](./docs/workflow-diff-examples.md) - Token 高效的工作流更新（新！）
- [事务更新](./docs/transactional-updates-example.md) - 两步工作流编辑
- [MCP 必备](./docs/MCP_ESSENTIALS_README.md) - AI 优化工具指南
- [验证系统](./docs/validation-improvements-v2.4.2.md) - 智能验证配置文件
### 开发和部署
- [Railway 部署](./docs/RAILWAY_DEPLOYMENT.md) - 一键云部署指南
- [HTTP 部署](./docs/HTTP_DEPLOYMENT.md) - 远程服务器设置指南
- [依赖管理](./docs/DEPENDENCY_UPDATES.md) - 保持 n8n 包同步
- [Claude's Interview](./docs/CLAUDE_INTERVIEW.md) - n8n-MCP 的现实影响
### 项目信息
- [变更日志](./CHANGELOG.md) - 完整的版本历史
- [Claude 说明](./CLAUDE.md) - 本代码库的 AI 指南
- [MCP 工具参考](#-可用MCP工具) - 可用工具的完整列表
## 📊 指标和覆盖率
当前数据库覆盖率（n8n v2.2.3）：
- ✅ **1,084 个总节点** - 537 个核心 + 547 个社区
- ✅ **301 个已验证** 的社区节点来自 n8n Strapi API
- ✅ **246 个流行的** npm 社区包已索引
- ✅ **470 个** 节点带有文档（87% 核心覆盖率）
- ✅ **265 个** AI 能力工具变体被检测到
- ✅ **2,646 个** 预提取的模板配置
- ✅ **2,709 个** 工作流模板可用（100% 元数据覆盖率）
- ✅ **AI 代理和 LangChain 节点** 完全记录
- ⚡ **平均响应时间**：~12ms
- 💾 **数据库大小**：~70MB（包括模板和社区节点）
## 🔄 最近更新
查看 [CHANGELOG.md](./CHANGELOG.md) 以获取完整的版本历史和最近的更改。
## 🧪 测试
该项目包含一个全面的测试套件，共有 **2,883 个测试** ，确保代码质量和可靠性：
```bash
# 运行所有测试
npm test
# 运行测试并生成覆盖率报告
npm run test:coverage
# 以监视模式运行测试
npm run test:watch
# 运行特定的测试套件
npm run test:unit # 933 个单元测试
npm run test:integration # 249 个集成测试
npm run test:bench # 性能基准测试
```
### 测试套件概述
- **总测试数**：2,883（100% 通过）
- **单元测试**：2,526 个测试，跨 99 个文件
- **集成测试**：357 个测试，跨 20 个文件
- **执行时间**：CI 中约 2.5 分钟
- **测试框架**：Vitest（适用于速度和 TypeScript 支持）
- **模拟**：MSW 用于 API 模拟，自定义模拟用于数据库
### 覆盖率和质量
- **覆盖率报告**：在 `./coverage` 目录中生成
- **CI/CD**：所有 PR 上使用 GitHub Actions 自动测试
- **性能**：CI 和本地环境感知阈值
- **并行执行**：可配置的线程池以加快运行速度
### 测试架构
**总计：3,336 个测试** ，跨单元和集成测试套件
- **单元测试**（2,766 个测试）：隔离的组件测试，带有模拟
- 服务层：增强的验证，属性过滤，工作流验证
- 解析器：节点解析，属性提取，文档映射
- 数据库：存储库，适配器，迁移，FTS5 搜索
- MCP 工具：工具定义，文档系统
- HTTP 服务器：多租户支持，安全，配置
- **集成测试**（570 个测试）：完整的系统行为验证
- **n8n API 集成**（172 个测试）：所有 18 个 MCP 处理程序工具均针对真实的 n8n 实例进行了测试
- 工作流管理：创建，读取，更新，删除，列出，验证，自动修复
- 执行管理：触发，检索，列出，删除
- 系统工具：健康检查，工具列表，诊断
- **MCP 协议**（119 个测试）：协议合规性，会话管理，错误处理
- **数据库**（226 个测试）：存储库操作，事务，性能，FTS5 搜索
- **模板**（35 个测试）：模板获取，存储，元数据操作
- **Docker**（18 个测试）：配置，入口点，安全验证
有关详细的测试文档，请参阅 [测试架构](./docs/testing-architecture.md)。
## 📦 许可证
MIT 许可证 - 有关详细信息，请参阅 [LICENSE](LICENSE)。
**如果您使用 n8n-MCP，请考虑：**
- ⭐ 给此仓库加星标
- 💬 在您的项目中提及它
- 🔗 链接回此仓库
## 🤝 贡献
欢迎贡献！请：
1. 分叉仓库
2. 创建一个功能分支
3. 运行测试（`npm test`）
4. 提交拉取请求
### 🚀 适用于维护者的自动化发布
该项目使用由版本更改触发的自动化发布：
```bash
# 引导发布准备
npm run prepare:release
# 测试发布自动化
npm run test:release-automation
```
该系统自动处理：
- 🏷️ GitHub 发布，附带变更日志内容
- 📦 NPM 包发布
- 🐳 跨平台 Docker 镜像
- 📚 文档更新
有关完整详细信息，请参阅 [自动化发布指南](./docs/AUTOMATED_RELEASES.md)。
## 👏 致谢
- [n8n](https://n8n.io) 团队提供工作流自动化平台
- [Anthropic](https://anthropic.com) 提供模型上下文协议
- 本项目的贡献者和用户
### 模板致谢
本项目中的所有工作流模板均从 n8n 的公共模板库 [n8n.io/workflows](https://n8n.io/workflows) 获取。每个模板都包含：
- 对原始创建者的完整致谢（姓名和用户名）
- 直接链接到 n8n.io 上的源模板
- 用于参考的原始工作流 ID
本项目中的 AI 代理说明包含强制性致谢要求。当使用任何模板时，AI 将自动：
- 分享模板作者的姓名和用户名
- 提供指向 n8n.io 上原始模板的直接链接
- 以以下格式显示致谢： “此工作流基于 **[作者]**（@ [用户名]）的模板。 在 [网址] 上查看原始模板。”
模板创建者保留对其工作流的所有权利。本项目索引模板以通过 AI 助手提高可发现性。如果您是模板创建者，并且对您的模板被索引有疑虑，请打开一个问题。
特别感谢那些为成千上万用户提供自动化工作流的模板贡献者，包括：
**David Ashby**（@cfomodz），**Yaron Been**（@yaron-nofluff），**Jimleuk**（@jimleuk），**Davide**（@n3witalia），**David Olusola**（@dae221），**Ranjan Dailata**（@ranjancse），**Airtop**（@cesar-at-airtop），**Joseph LePage**（@joe），**Don Jayamaha Jr**（@don-the-gem-dealer），**Angel Menendez**（@djangelic），以及整个 n8n 创作者社区！
---
<div align="center">
<strong>用 ❤️ 为 n8n 社区构建</strong><br>
<sub>让 AI + n8n 工作流创建变得令人愉快</sub>
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器