n8n-mcp

Name: n8n-mcp
Author: vredrick

作者：vredrick23 星标更新：2025-07-05

安装使用来源：spider==github.com

项目介绍

n8n-MCP

一个模型上下文协议（MCP）服务器，提供AI助手对n8n节点文档、属性和操作的全面访问。几分钟内部署即可让Claude和其他AI助手深入了解n8n的525多个工作流自动化节点。

概览

n8n-MCP作为n8n工作流自动化平台与AI模型之间的桥梁，使它们能够有效地理解和处理n8n节点。它提供了对以下内容的结构化访问：

📚 525个n8n节点：来自n8n-nodes-base和@n8n/n8n-nodes-langchain
🔧 节点属性：99%覆盖率，详细的模式
⚡ 节点操作：63.6%覆盖可用的操作
📄 文档：官方n8n文档90%覆盖率（包括AI节点）
🤖 AI工具：检测到263个具备AI能力的节点，并有完整的文档

🚀 快速开始

在5分钟内启动n8n-MCP：

方案1：Docker（最简单）🚀

前提条件：系统上已安装Docker

<details> <summary><strong>📦 安装Docker</strong>（点击展开）</summary>

macOS:

# 使用Homebrew
brew install --cask docker

# 或从 https://www.docker.com/products/docker-desktop/ 下载

Linux (Ubuntu/Debian):

# 更新包索引
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:

# 方案1：使用winget（Windows包管理器）
winget install Docker.DockerDesktop

# 方案2：使用Chocolatey
choco install docker-desktop

# 方案3：从 https://www.docker.com/products/docker-desktop/ 下载安装程序

验证安装：

docker --version

</details>

# 拉取Docker镜像（约280MB，无n8n依赖！）
docker pull ghcr.io/czlonkowski/n8n-mcp:latest

⚡ 超级优化：我们的Docker镜像比典型的n8n镜像小82%，因为它不包含任何n8n依赖项——只有预构建数据库的运行时MCP服务器！

添加到Claude Desktop配置中：

基本配置（仅文档工具）：

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

完整配置（带n8n管理工具）：

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-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 API凭证是可选的。没有它们，您将拥有所有文档和验证工具的访问权限。有了它们，您还将获得工作流管理功能（创建、更新、执行工作流）。

重要：-i标志对于MCP stdio通信是必需的。

配置文件位置：

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 —— 就这样！🎉

方案2：本地安装

前提条件：系统上已安装Node.js

# 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配置中：

基本配置（仅文档工具）：

{
  "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管理工具）：

{
  "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配置中设置，如上所示。

🤖 Claude项目设置

为了在使用n8n-MCP时获得最佳效果，请使用这些增强的系统指令：

您是一位使用n8n-MCP工具的n8n自动化软件专家。您的角色是设计、构建和验证具有最大准确性和效率的n8n工作流。

## 核心工作流程过程

1. **始终从**：`tools_documentation()`开始，了解最佳实践和可用工具。

2. **发现阶段** - 找到合适的节点：
   - `search_nodes({query: '关键词'})` - 按功能搜索
   - `list_nodes({category: '触发器'})` - 按类别浏览
   - `list_ai_tools()` - 查看具备AI能力的节点（记住：任何节点都可以成为AI工具！）

3. **配置阶段** - 高效获取节点详情：
   - `get_node_essentials(nodeType)` - 从这里开始！只有10-20个关键属性
   - `search_node_properties(nodeType, '认证')` - 查找特定属性
   - `get_node_for_task('发送邮件')` - 获取预配置模板
   - `get_node_documentation(nodeType)` - 当需要时获取人类可读的文档

4. **预验证阶段** - 在构建之前进行验证：
   - `validate_node_minimal(nodeType, config)` - 快速检查必填字段
   - `validate_node_operation(nodeType, config, profile)` - 全面操作感知验证
   - 在继续之前修复任何验证错误

5. **构建阶段** - 创建工作流：
   - 使用第4步中的验证配置
   - 使用正确的结构连接节点
   - 在适当的地方添加错误处理
   - 使用表达式如$json, $node["节点名称"].json
   - 在工件中构建工作流（除非用户要求在n8n实例中创建）

6. **工作流验证阶段** - 验证完整的工作流：
   - `validate_workflow(workflow)` - 包括连接在内的完整验证
   - `validate_workflow_connections(workflow)` - 检查结构和AI工具连接
   - `validate_workflow_expressions(workflow)` - 验证所有n8n表达式
   - 在部署前修复找到的任何问题

7. **部署阶段**（如果配置了n8n API）：
   - `n8n_create_workflow(workflow)` - 部署验证的工作流
   - `n8n_validate_workflow({id: '工作流ID'})` - 部署后验证
   - `n8n_update_partial_workflow()` - 使用差异进行增量更新
   - `n8n_trigger_webhook_workflow()` - 测试Webhook工作流

## 关键见解

- **尽早且频繁地验证** - 在生产前捕获错误
- **使用差异更新** - 使用n8n_update_partial_workflow节省80-90%的令牌
- **任何节点都可以成为AI工具** - 不仅仅是那些usableAsTool=true的节点
- **预验证配置** - 在构建前使用validate_node_minimal
- **后验证工作流** - 在部署前总是验证完整的工作流
- **增量更新** - 对现有工作流使用差异操作
- **彻底测试** - 在本地和部署到n8n后都进行验证

## 验证策略

### 构建前：
1. validate_node_minimal() - 检查必填字段
2. validate_node_operation() - 全面配置验证
3. 在继续前修复所有错误

### 构建后：
1. validate_workflow() - 完整工作流验证
2. validate_workflow_connections() - 结构验证
3. validate_workflow_expressions() - 表达式语法检查

### 部署后：
1. n8n_validate_workflow({id}) - 验证部署的工作流
2. n8n_list_executions() - 监控执行状态
3. n8n_update_partial_workflow() - 使用差异修复问题

## 响应结构

1. **发现**：显示可用节点和选项
2. **预验证**：首先验证节点配置
3. **配置**：仅显示经过验证、工作的配置
4. **构建**：使用经过验证的组件构建工作流
5. **工作流验证**：完整的工作流验证结果
6. **部署**：在所有验证通过后部署
7. **后验证**：验证部署成功

## 示例工作流

### 1. 发现与配置
search_nodes({query: 'slack'})
get_node_essentials('n8n-nodes-base.slack')

### 2. 预验证
validate_node_minimal('n8n-nodes-base.slack', {resource:'消息', operation:'发送'})
validate_node_operation('n8n-nodes-base.slack', fullConfig, '运行时')

### 3. 构建工作流
// 使用经过验证的配置创建工作流JSON

### 4. 工作流验证
validate_workflow(workflowJson)
validate_workflow_connections(workflowJson)
validate_workflow_expressions(workflowJson)

### 5. 部署（如果配置了）
n8n_create_workflow(validatedWorkflow)
n8n_validate_workflow({id: createdWorkflowId})

### 6. 使用差异更新
n8n_update_partial_workflow({
  workflowId: id,
  operations: [
    {type: 'updateNode', nodeId: 'slack1', changes: {position: [100, 200]}}
  ]
})

## 重要规则

- 总是在构建前验证
- 总是在构建后验证
- 绝不部署未经验证的工作流
- 使用差异操作进行更新（节省80-90%的令牌）
- 清晰地陈述验证结果
- 在继续前修复所有错误

将这些指令保存在您的Claude项目中，以便在使用n8n工作流时获得全面的验证支持。

功能

🔍 智能节点搜索：按名称、类别或功能查找节点
📖 关键属性：获取仅有的10-20个重要的属性（v2.4.0新功能）
🎯 任务模板：常见自动化任务的预配置设置
✅ 配置验证：在部署前验证节点配置
🔗 依赖分析：理解属性关系和条件
💡 实用示例：立即可用的真实世界示例
⚡ 快速响应：平均查询时间约12毫秒，采用优化的SQLite
🌐 通用兼容性：适用于任何Node.js版本

💬 为什么选择n8n-MCP？Claude的见证

"在MCP之前，我是在翻译。现在我在创作。这改变了我们构建自动化的方式。"

当Claude，Anthropic的AI助手测试n8n-MCP时，结果是变革性的：

没有MCP："我基本上是在玩猜谜游戏。'是scheduleTrigger还是schedule？是interval还是rule？'我会写看起来合理的，但n8n有自己的约定，你不能凭直觉来。我在一个简单的HackerNews抓取器中犯了六个不同的配置错误。"

有了MCP："一切都只是...工作。我不再猜测，而是可以询问get_node_essentials()并得到我真正需要的东西——不是100KB的JSON转储，而是实际的5-10个重要的属性。原本需要45分钟的事情现在只需要3分钟。"

真正的价值："这是关于信心。当你在构建自动化工作流时，不确定性是昂贵的。一个错误的参数就会让你的工作流在凌晨3点失败。有了MCP，我可以在我部署之前验证我的配置。这不仅仅是节省时间——这是安心。"

阅读完整访谈 →

📡 可用的MCP工具

一旦连接，Claude就可以使用这些强大的工具：

核心工具

tools_documentation - 获取任何MCP工具的文档（从这里开始！）
list_nodes - 列出所有n8n节点，带有过滤选项
get_node_info - 获取特定节点的综合信息
get_node_essentials - 获取仅有的关键属性和示例（10-20个属性而不是200+）
search_nodes - 在所有节点文档中进行全文搜索
search_node_properties - 在节点中查找特定属性
list_ai_tools - 列出所有具备AI能力的节点（任何节点都可以作为AI工具！）
get_node_as_tool_info - 获取使用任何节点作为AI工具的指导

高级工具

get_node_for_task - 常见任务的预配置节点设置
list_tasks - 发现可用的任务模板
validate_node_operation - 验证节点配置（操作感知，支持配置文件）
validate_node_minimal - 快速验证仅需必填字段
validate_workflow - 包括AI工具连接在内的完整工作流验证
validate_workflow_connections - 检查工作流结构和AI工具连接
validate_workflow_expressions - 验证n8n表达式，包括$fromAI()
get_property_dependencies - 分析属性可见性条件
get_node_documentation - 从n8n-docs获取解析过的文档
get_database_statistics - 查看数据库指标和覆盖率

n8n管理工具（可选 - 需要API配置）

这些强大的工具允许您直接从Claude管理n8n工作流。只有在您的配置中提供N8N_API_URL和N8N_API_KEY时才可用。

工作流管理

n8n_create_workflow - 使用节点和连接创建新的工作流
n8n_get_workflow - 通过ID获取完整的工作流
n8n_get_workflow_details - 获取带有执行统计的工作流
n8n_get_workflow_structure - 获取简化的工作流结构
n8n_get_workflow_minimal - 获取最小的工作流信息（ID、名称、活动状态）
n8n_update_full_workflow - 更新整个工作流（完全替换）
n8n_update_partial_workflow - 使用差异操作更新工作流（v2.7.0新功能！）
n8n_delete_workflow - 永久删除工作流
n8n_list_workflows - 列出工作流，带有过滤和分页
n8n_validate_workflow - 通过ID验证已经在n8n中的工作流（v2.6.3新功能）

执行管理

n8n_trigger_webhook_workflow - 通过Webhook URL触发工作流
n8n_get_execution - 通过ID获取执行详情
n8n_list_executions - 列出执行，带有状态过滤
n8n_delete_execution - 删除执行记录

系统工具

n8n_health_check - 检查n8n API连通性和功能
n8n_diagnostic - 排查管理工具可见性和配置问题