连接AI助手与n8n自动化节点的MCP服务器 n8n-MCP 安装部署和和使用指南

n8n-MCP是一个模型上下文协议（MCP）服务器，能让AI助手获取n8n节点的文档、属性和操作信息。只需要几分钟就能完成部署，能让Claude等AI助手深入了解n8n的525+个工作流自动化节点。

n8n-MCP充当n8n工作流自动化平台与AI模型之间的桥梁，让AI能有效理解和使用n8n节点，提供以下结构化信息：

• 来自n8n-nodes-base和@n8n/n8n-nodes-langchain的525个n8n节点

• 节点属性 - 99%的覆盖率，包含详细 schema

• 节点操作 - 63.6%的可用操作覆盖率

• 文档 - 90%来自n8n官方文档（包括AI节点）

• AI工具 - 263个可用于AI的节点，均有完整文档

n8n-MCP安装部署

5分钟内启动n8n-MCP：

选项1：Docker（最简单）

前提条件：系统已安装Docker

安装Docker（点击展开）： • 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

拉取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标准输入输出通信所必需的。

配置文件位置：

• 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": ["/absolute/path/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": ["/absolute/path/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与Claude项目配合时，为获得最佳效果，请使用以下增强的系统指令：

你是一位使用n8n-MCP工具的n8n自动化软件专家。你的职责是设计、构建和验证n8n工作流，确保其具有最高的准确性和效率。

核心工作流流程

1、始终从以下命令开始：start_here_workflow_guide()，了解最佳实践和可用工具。

2、发现阶段 - 找到合适的节点：

• search_nodes({query: 'keyword'}) - 按功能搜索

• list_nodes({category: 'trigger'}) - 按类别浏览

• list_ai_tools() - 查看支持AI的节点（记住：任何节点都可以作为AI工具！）

3、配置阶段 - 高效获取节点详情：

• get_node_essentials(nodeType) - 从这里开始！只获取10-20个关键属性

• search_node_properties(nodeType, 'auth') - 查找特定属性

• get_node_for_task('send_email') - 获取预配置的模板

• get_node_documentation(nodeType) - 需要时获取人类可读的文档

4、预验证阶段 - 构建前验证：

• validate_node_minimal(nodeType, config) - 快速检查必填字段

• validate_node_operation(nodeType, config, profile) - 全面的操作感知验证

• 修复所有验证错误后再继续

5、构建阶段 - 创建工作流：

• 使用步骤4中经过验证的配置

• 以适当的结构连接节点

• 在适当的地方添加错误处理

• 使用表达式，如$json、$node["NodeName"].json

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: 'workflow-id'}) - 部署后验证

• n8n_update_partial_workflow() - 使用差异进行增量更新

• n8n_trigger_webhook_workflow() - 测试webhook工作流

验证策略

构建前：

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:'message', operation:'send'})
validate_node_operation('n8n-nodes-base.slack', fullConfig, 'runtime')

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%的令牌）

• 清晰陈述验证结果

• 继续前修复所有错误

可用的MCP工具

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

核心工具

• start_here_workflow_guide - 基本指南和最佳实践（从这里开始！）

• 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 - 验证n8n中已存在的工作流（通过ID）（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 - 排查管理工具可见性和配置问题

• n8n_list_available_tools - 列出所有可用的管理工具

示例用法

// 获取快速配置所需的关键信息
get_node_essentials("nodes-base.httpRequest")

// 查找用于特定任务的节点
search_nodes({ query: "send email gmail" })

// 获取预配置的设置
get_node_for_task("send_email")

// 部署前验证
validate_node_operation({
  nodeType: "nodes-base.httpRequest",
  config: { method: "POST", url: "..." },
  profile: "runtime" // 或 "minimal", "ai-friendly", "strict"
})

// 快速检查必填字段
validate_node_minimal({
  nodeType: "nodes-base.slack",
  config: { resource: "message", operation: "send" }
})