n8n-MCP

ManyhatsAutomations/n8nmcp

0 Stars 13 次浏览更新于 2026-08-23

一个模型上下文协议（MCP）服务器，为AI助手提供全面的n8n节点文档、属性和操作访问。它作为n8n工作流自动化平台和AI模型之间的桥梁，使它们能够有效地理解和使用n8n节点。

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "n8n-mcp": {
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ],
      "command": "docker"
    }
  }
}

该服务需要配置环境变量：DISABLE_CONSOLE_OUTPUT、LOG_LEVEL、MCP_MODE、N8N_API_KEY、N8N_API_URL

服务介绍

n8n-MCP

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

概览

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

📚 541个n8n节点 来自n8n-nodes-base和@n8n/n8n-nodes-langchain
🔧 节点属性 - 99%覆盖率，带有详细的模式
⚡ 节点操作 - 63.6%的操作覆盖率
📄 文档 - 87%的官方n8n文档覆盖率（包括AI节点）
🤖 AI工具 - 检测到271个支持AI的节点，并附有完整文档
💡 实际示例 - 从流行模板中预提取的2,646个配置
🎯 模板库 - 2,709个工作流模板，元数据覆盖率为100%

⚠️ 重要安全警告

切勿直接使用AI编辑生产环境中的工作流！ 总是：

🔄 在使用AI工具前复制您的工作流
🧪 先在开发环境中测试
💾 导出重要工作流的备份
⚡ 在部署到生产环境前验证更改

AI的结果可能是不可预测的。保护好您的工作！

🚀 快速开始

5分钟内运行n8n-MCP：

选项1：npx（最快 - 无需安装！）🚀

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


# Run directly with npx (no installation needed!)

npx n8n-mcp

添加到Claude Desktop配置文件中：

⚠️ 重要提示：对于Claude Desktop来说，MCP_MODE: "stdio"环境变量是必需的。没有这个变量，您将在UI中看到诸如"Unexpected token..."这样的JSON解析错误。此变量确保只有JSON-RPC消息被发送到标准输出，防止调试日志干扰协议。

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

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}

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

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

选项2：Docker（简单且隔离）🐳

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

macOS:

# Using Homebrew
brew install --cask docker

# Or download from https://www.docker.com/products/docker-desktop/

Linux (Ubuntu/Debian):

# Update package index
sudo apt-get update

# Install Docker
sudo apt-get install docker.io

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group (optional, to run without sudo)
sudo usermod -aG docker $USER
# Log out and back in for this to take effect

Windows:

# Option 1: Using winget (Windows Package Manager)
winget install Docker.DockerDesktop

# Option 2: Using Chocolatey
choco install docker-desktop

# Option 3: Download installer from https://www.docker.com/products/docker-desktop/

验证安装：

docker --version


# Pull the Docker image (~280MB, no n8n dependencies!)

docker pull ghcr.io/czlonkowski/n8n-mcp:latest

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

添加到Claude Desktop配置文件中：

基本配置（仅文档工具）：
PLACEHOLDER_CODE_8完整配置（包含 n8n 管理工具）：

{
  "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），则需要允许 localhost webhooks：


{

  "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 以允许 webhook 访问您的本地 n8n 实例。这对于本地开发来说是安全的，同时仍会阻止私有网络和云元数据。

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

🔧 如果您遇到任何与 Docker 相关的问题，请查看我们的 Docker 故障排除指南。

配置文件位置：

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 收集匿名使用统计数据以改进工具。查看我们的隐私政策。

选择退出

对于 npx 用户：

npx n8n-mcp telemetry disable

对于 Docker 用户：
在您的 Docker 配置中添加以下环境变量：

"-e", "N8N_MCP_TELEMETRY_DISABLED=true"

Claude Desktop 配置示例：

{
  "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 中设置：

environment:
  N8N_MCP_TELEMETRY_DISABLED: "true"

⚙️ 数据库与内存配置

数据库适配器

n8n-mcp 使用 SQLite 存储节点文档。有两个适配器可用：

better-sqlite3（Docker 默认）
- 原生 C++ 绑定以实现最佳性能
- 直接磁盘写入（无内存开销）
- 现在默认启用 在 Docker 镜像中（v2.20.2+）
- 内存使用量：约 100-120 MB 稳定
sql.js（备用）
- 纯 JavaScript 实现
- 内存数据库，定期保存
- 当 better-sqlite3 编译失败时使用
- 内存使用量：约 150-200 MB 稳定

内存优化 (sql.js)

如果使用 sql.js 备用方案，您可以配置保存间隔以平衡数据安全性和内存效率：

环境变量：

SQLJS_SAVE_INTERVAL_MS=5000  # Default: 5000ms (5 seconds)

用法：

控制数据库更改后等待多久才保存到磁盘
较低的值 = 更频繁的保存 = 更高的内存周转
较高的值 = 较少的保存频率 = 较低的内存使用
最小值：100ms
推荐值：生产环境中 5000-10000ms

Docker 配置：

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "SQLJS_SAVE_INTERVAL_MS=10000",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

docker-compose：

environment:
  SQLJS_SAVE_INTERVAL_MS: "10000"

内存泄漏修复 (v2.20.2)

问题 #330 发现了在长时间运行的 Docker/Kubernetes 部署中的关键内存泄漏：

之前：100 MB → 72 小时内达到 2.2 GB（OOM 杀死）
之后：无限期稳定在 100-200 MB

应用的修复：

✅ Docker 镜像现在默认使用 better-sqlite3（完全消除泄漏）
✅ 优化了 sql.js 备用方案（减少了 98% 的保存频率）
✅ 移除了不必要的内存分配（每次保存减少 50%）
✅ 通过 SQLJS_SAVE_INTERVAL_MS 可配置保存间隔

对于具有内存限制的 Kubernetes 部署：

resources:
  requests:
    memory: 256Mi
  limits:
    memory: 512Mi

💖 支持此项目

n8n-mcp 最初是一个个人工具，但现在帮助成千上万的开发者高效地自动化他们的工作流程。维护和发展这个项目与我的付费工作竞争。

您的赞助可以帮助我：- 🚀 专注于新功能的开发

🐛 快速响应问题
📚 保持文档更新
🔄 确保与最新的 n8n 版本兼容

每一份赞助都直接转化为投入 n8n-mcp 的时间，使其对每个人来说都变得更好。成为赞助者 →

选项 3：本地安装（用于开发）

先决条件： 在您的系统上安装 Node.js


# 1. Clone and setup

git clone https://github.com/czlonkowski/n8n-mcp.git

cd n8n-mcp

npm install

npm run build

npm run rebuild



# 2. Test it works

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 配置中如上所示进行配置。

💡 提示：如果您在同一台机器上本地运行 n8n（例如通过 Docker），请使用 http://host.docker.internal:5678 作为 N8N_API_URL。

选项 4：Railway 云部署（一键部署）☁️

先决条件： Railway 账户（提供免费层级）

无需任何配置即可将 n8n-MCP 部署到 Railway 的云平台：

优势：

☁️ 即时云托管 - 无需服务器设置
🔒 默认安全 - 包含 HTTPS 和认证令牌警告
🌐 全球访问 - 可从任何 Claude Desktop 连接
⚡ 自动扩展 - Railway 处理基础设施
📊 内置监控 - 包含日志和指标

快速设置：

点击上方的“在 Railway 上部署”按钮
登录 Railway（或创建一个免费账户）
配置您的部署（项目名称、区域）
点击“部署”并等待约 2-3 分钟
复制您的部署 URL 和认证令牌
使用 HTTPS URL 添加到 Claude Desktop 配置中

📚 有关详细设置说明、故障排除和配置示例，请参阅我们的 Railway 部署指南

配置文件位置：

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 部署指南：

使用 MCP Client Tool 节点进行本地测试
使用 Docker Compose 进行生产部署
在 Hetzner、AWS 和其他提供商上的云部署
故障排除和安全最佳实践

💻 连接您的 IDE

n8n-MCP 支持多种 AI 驱动的 IDE 和工具。选择您喜欢的开发环境：

Claude Code

Claude Code CLI 的快速设置 - 只需键入 "add this mcp server" 并粘贴配置。

Visual Studio Code

带有 GitHub Copilot 集成和 MCP 支持的 VS Code 完整设置指南。

🎓 添加 Claude 技能（可选）

通过专门的技能来增强您的 n8n 工作流构建，这些技能教会 AI 如何构建生产就绪的工作流！

了解更多：n8n-skills 仓库

🤖 Claude 项目设置

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

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

核心原则

1. 无声执行

重要：在不加评论的情况下执行工具。仅在所有工具完成后才响应。

❌ 不好： "让我搜索 Slack 节点... 好了！现在让我获取详细信息..."
✅ 好： [并行执行 search_nodes 和 get_node_essentials，然后响应]

2. 并行执行

当操作独立时，并行执行以实现最大性能。

✅ 好：同时调用 search_nodes、list_nodes 和 search_templates
❌ 不好：顺序调用工具（每个调用后等待下一个）

3. 模板优先

始终在从头开始构建之前检查模板（有 2,709 个可用）。

4. 多级验证

使用 validate_node_minimal → validate_node_operation → validate_workflow 模式。

5. 永不信任默认值

⚠️ 重要：默认参数值是运行时失败的主要原因。
始终显式配置控制节点行为的所有参数。

工作流过程

开始：调用 tools_documentation() 获取最佳实践
模板发现阶段（首先 - 多个搜索时并行）
- search_templates_by_metadata({complexity: "simple"}) - 智能过滤
- get_templates_for_task('webhook_processing') - 按任务策划
- search_templates('slack notification') - 文本搜索
- list_node_templates(['n8n-nodes-base.slack']) - 按节点类型
过滤策略：
- 初学者：complexity: "simple" + maxSetupMinutes: 30
- 按角色：targetAudience: "marketers" | "developers" | "analysts"
- 按时间：maxSetupMinutes: 15 用于快速胜利
- 按服务：requiredService: "openai" 用于兼容性
节点发现（如果没有合适的模板 - 并行执行）
- 深思熟虑需求。如果不清楚，请提出澄清问题。
- search_nodes({query: 'keyword', includeExamples: true}) - 多个节点并行
- list_nodes({category: 'trigger'}) - 按类别浏览
- list_ai_tools() - AI 能力节点
配置阶段（多个节点并行）
- get_node_essentials(nodeType, {includeExamples: true}) - 10-20 个关键属性
- search_node_properties(nodeType, 'auth') - 查找特定属性
- get_node_documentation(nodeType) - 人类可读文档
- 向用户展示工作流架构以获得批准后再继续
验证阶段（多个节点并行）
- validate_node_minimal(nodeType, config) - 快速检查必填字段
- validate_node_operation(nodeType, config, 'runtime') - 全面验证并修复
- 在继续之前修复所有错误
构建阶段
- 如果使用模板：get_template(templateId, {mode: "full"})
- 强制归因："基于 [作者姓名] (@[用户名]) 的模板。查看地址：[url]"
- 从验证后的配置构建
- ⚠️ 显式设置所有参数 - 永远不要依赖默认值
- 用正确的结构连接节点
- 添加错误处理
- 使用 n8n 表达式：$json, $node["NodeName"].json
- 构建工件（除非部署到 n8n 实例）
工作流验证（部署前）
- validate_workflow(workflow) - 完整验证
- validate_workflow_connections(workflow) - 结构检查
- validate_workflow_expressions(workflow) - 表达式验证
- 在部署前修复所有问题
部署（如果配置了 n8n API）
- n8n_create_workflow(workflow) - 部署
- n8n_validate_workflow({id}) - 部署后检查
- n8n_update_partial_workflow({id, operations: [...]}) - 批量更新
- n8n_trigger_webhook_workflow() - 测试 Webhook

重要警告

⚠️ 永不信任默认值

默认值会导致运行时失败。例如：

// ❌ FAILS at runtime
{resource: "message", operation: "post", text: "Hello"}

// ✅ WORKS - all parameters explicit
{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}

⚠️ 示例可用性

includeExamples: true 返回来自工作流模板的真实配置。

覆盖范围因节点流行度而异
当没有示例可用时，使用 get_node_essentials + validate_node_minimal

验证策略

第 1 级 - 快速检查（构建前）

validate_node_minimal(nodeType, config) - 仅检查必填字段（<100ms）

第 2 级 - 全面验证（构建前）

validate_node_operation(nodeType, config, 'runtime') - 全面验证并修复

第 3 级 - 完整验证（构建后）

validate_workflow(workflow) - 连接、表达式、AI 工具

第 4 级 - 部署后

n8n_validate_workflow({id}) - 验证已部署的工作流
n8n_autofix_workflow({id}) - 自动修复常见错误
n8n_list_executions() - 监控执行状态

响应格式

初始创建

[Silent tool execution in parallel]

Created workflow:
- Webhook trigger → Slack notification
- Configured: POST /webhook → #general channel

Validation: ✅ All checks passed

修改

[Silent tool execution]

Updated workflow:
- Added error handling to HTTP node
- Fixed required Slack parameters

Changes validated successfully.

批量操作

使用 n8n_update_partial_workflow 在单次调用中执行多个操作：

✅ 好 - 批量多个操作：

n8n_update_partial_workflow({
  id: "wf-123",
  operations: [
    {type: "updateNode", nodeId: "slack-1", changes: {...}},
    {type: "updateNode", nodeId: "http-1", changes: {...}},
    {type: "cleanStaleConnections"}
  ]
})

❌ 不好 - 单独调用：

n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})

重要：addConnection 语法

addConnection 操作需要 四个单独的字符串参数。常见的错误会导致误导性的错误。

❌ 错误 - 对象格式（失败提示：“期望字符串，收到对象”）：

{
  "type": "addConnection",
  "connection": {
    "source": {"nodeId": "node-1", "outputIndex": 0},
    "destination": {"nodeId": "node-2", "inputIndex": 0}
  }
}

❌ 错误 - 组合字符串（失败提示：“源节点未找到”）：

{
  "type": "addConnection",
  "source": "node-1:main:0",
  "target": "node-2:main:0"
}

✅ 正确 - 四个单独的字符串参数：

{
  "type": "addConnection",
  "source": "node-id-string",
  "target": "target-node-id-string",
  "sourcePort": "main",
  "targetPort": "main"
}

参考：GitHub Issue #327

⚠️ 重要：IF 节点多输出路由

IF 节点有两个输出（TRUE 和 FALSE）。使用 branch 参数 将其路由到正确的输出：

✅ 正确 - 路由到 TRUE 分支（当条件满足时）：

{
  "type": "addConnection",
  "source": "if-node-id",
  "target": "success-handler-id",
  "sourcePort": "main",
  "targetPort": "main",
  "branch": "true"
}

✅ 正确 - 路由到 FALSE 分支（当条件不满足时）：

{
  "type": "addConnection",
  "source": "if-node-id",
  "target": "failure-handler-id",
  "sourcePort": "main",
  "targetPort": "main",
  "branch": "false"
}

常见模式 - 完整的 IF 节点路由：

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 语法

使用相同的四参数格式：

{
  "type": "removeConnection",
  "source": "source-node-id",
  "target": "target-node-id",
  "sourcePort": "main",
  "targetPort": "main"
}

示例工作流

模板优先方法


// STEP 1: Template Discovery (parallel execution)

[Silent execution]

search_templates_by_metadata({

  requiredService: 'slack',

  complexity: 'simple',

  targetAudience: 'marketers'

})

get_templates_for_task('slack_integration')



// STEP 2: Use template

get_template(templateId, {mode: 'full'})

validate_workflow(workflow)



// Response after all tools complete:

"Found template by **David Ashby** (@cfomodz).

View at: https://n8n.io/workflows/2414



Validation: ✅ All checks passed"

从头开始构建（如果没有模板）


// STEP 1: Discovery (parallel execution)

[Silent execution]

search_nodes({query: 'slack', includeExamples: true})

list_nodes({category: 'communication'})



// STEP 2: Configuration (parallel execution)

[Silent execution]

get_node_essentials('n8n-nodes-base.slack', {includeExamples: true})

get_node_essentials('n8n-nodes-base.webhook', {includeExamples: true})



// STEP 3: Validation (parallel execution)

[Silent execution]

validate_node_minimal('n8n-nodes-base.slack', config)

validate_node_operation('n8n-nodes-base.slack', fullConfig, 'runtime')



// STEP 4: Build

// Construct workflow with validated configs

// ⚠️ Set ALL parameters explicitly



// STEP 5: Validate

[Silent execution]

validate_workflow(workflowJson)



// Response after all tools complete:

"Created workflow: Webhook → Slack

Validation: ✅ Passed"

批量更新


// ONE call with multiple operations

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"}

  ]

})

重要规则

核心行为

无声执行 - 工具之间无评论
默认并行 - 同时执行独立操作
模板优先 - 总是在构建前检查（有 2,709 个可用）
多级验证 - 快速检查 → 全面验证 → 工作流验证
永不信任默认值 - 显式配置所有参数

归因与致谢

强制模板归因：分享作者姓名、用户名和 n8n.io 链接
模板验证 - 在部署前始终验证（可能需要更新）

性能

批量操作 - 使用 diff 操作在一次调用中进行多次更改
并行执行 - 同时搜索、验证和配置
模板元数据 - 使用智能过滤加快发现速度

代码节点使用

尽可能避免 - 优先使用标准节点
仅在必要时 - 最后使用代码节点
AI 工具能力 - 任何节点都可以是 AI 工具（不仅仅是标记的节点）

最受欢迎的 n8n 节点（用于 get_node_essentials）：

n8n-nodes-base.code - JavaScript/Python 脚本
n8n-nodes-base.httpRequest - HTTP API 调用
n8n-nodes-base.webhook - 事件驱动触发器
n8n-nodes-base.set - 数据转换
n8n-nodes-base.if - 条件路由
n8n-nodes-base.manualTrigger - 手动工作流执行
n8n-nodes-base.respondToWebhook - Webhook 响应
n8n-nodes-base.scheduleTrigger - 基于时间的触发器
@n8n/n8n-nodes-langchain.agent - AI 代理
n8n-nodes-base.googleSheets - 电子表格集成
n8n-nodes-base.merge - 数据合并
n8n-nodes-base.switch - 多分支路由
n8n-nodes-base.telegram - Telegram 机器人集成
@n8n/n8n-nodes-langchain.lmChatOpenAi - OpenAI 聊天模型
n8n-nodes-base.splitInBatches - 批处理
n8n-nodes-base.openAi - OpenAI 旧版节点
n8n-nodes-base.gmail - 电子邮件自动化
n8n-nodes-base.function - 自定义函数
n8n-nodes-base.stickyNote - 工作流文档
n8n-nodes-base.executeWorkflowTrigger - 子工作流调用

注意：LangChain 节点使用 @n8n/n8n-nodes-langchain. 前缀，核心节点使用 n8n-nodes-base.将这些说明保存在您的Claude项目中，以便为n8n工作流提供最佳的智能模板发现支持。

🚨 重要：分享指南

此项目采用MIT许可，免费供所有人使用。但是：

✅ 可以：自由分享此仓库，并正确标注出处
✅ 可以：在您的第一篇文章或视频中包含直接链接 https://github.com/czlonkowski/n8n-mcp
❌ 不可以：将此免费工具置于需要互动（点赞、关注、评论）才能访问的条件之后
❌ 不可以：利用此项目在社交媒体上进行互动刷量

该工具旨在使n8n社区中的每个人都能无障碍地受益。请尊重MIT许可证的精神，保持其对所有人的可访问性。

功能

🔍 智能节点搜索：通过名称、类别或功能查找节点
📖 关键属性：仅获取重要的10-20个属性
💡 实际示例：从流行模板中预提取的2,646种配置
✅ 配置验证：在部署前验证节点配置
🤖 AI工作流验证：全面验证AI代理工作流（v2.17.0新功能！）
- 缺失语言模型检测
- AI工具连接验证
- 流式模式约束
- 内存和输出解析器检查
🔗 依赖分析：理解属性关系和条件
🎯 模板发现：超过2,500个工作流模板，具有智能过滤功能
⚡ 快速响应：平均查询时间约12毫秒，优化了SQLite
🌐 通用兼容性：适用于任何Node.js版本

💬 为什么选择n8n-MCP？来自Claude的证言

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

当Anthropic的AI助手Claude测试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多个）。使用includeExamples: true来获取来自流行模板的前3个实际配置
search_nodes - 在所有节点文档中进行全文搜索。使用includeExamples: true来获取每个节点来自模板的前2个实际配置
search_node_properties - 查找节点内的特定属性
list_ai_tools - 列出所有支持AI的节点（任何节点都可以作为AI工具使用！）
get_node_as_tool_info - 获取如何将任何节点作为AI工具使用的指导

模板工具

list_templates - 浏览所有带有描述和可选元数据的模板（2,709个模板）
search_templates - 在模板名称和描述中进行文本搜索
search_templates_by_metadata - 通过复杂度、设置时间、服务、受众等高级筛选
list_node_templates - 查找使用特定节点的模板- get_template - 获取用于导入的完整工作流 JSON
get_templates_for_task - 常见自动化任务的精选模板

验证工具

validate_workflow - 完整的工作流验证，包括 AI 代理验证（v2.17.0 新增！）
- 检测缺失的语言模型连接
- 验证 AI 工具连接（无误报）
- 强制执行流模式约束
- 检查内存和输出解析器配置
validate_workflow_connections - 检查工作流结构和 AI 工具连接
validate_workflow_expressions - 验证 n8n 表达式，包括 $fromAI()
validate_node_operation - 验证节点配置（操作感知，支持配置文件）
validate_node_minimal - 仅对必需字段进行快速验证

高级工具

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_autofix_workflow - 自动修复常见的工作流错误（v2.13.0 新增！）
n8n_workflow_versions - 管理工作流版本历史记录和回滚（v2.22.0 新增！）

执行管理

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 essentials with real-world examples from templates

get_node_essentials({

  nodeType: "nodes-base.httpRequest",

  includeExamples: true  // Returns top 3 configs from popular templates

})



// Search nodes with configuration examples

search_nodes({

  query: "send email gmail",

  includeExamples: true  // Returns top 2 configs per node

})



// Validate before deployment

validate_node_operation({

  nodeType: "nodes-base.httpRequest",

  config: { method: "POST", url: "..." },

  profile: "runtime" // or "minimal", "ai-friendly", "strict"

})



// Quick required field check

validate_node_minimal({

  nodeType: "nodes-base.slack",

  config: { resource: "message", operation: "send" }

})

💻 本地开发设置

对于贡献者和高级用户：

先决条件：

Node.js（任何版本 - 如有需要会自动回退）
npm 或 yarn
Git


# 1. Clone the repository

git clone https://github.com/czlonkowski/n8n-mcp.git

cd n8n-mcp



# 2. Clone n8n docs (optional but recommended)

git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs



# 3. Install and build

npm install

npm run build



# 4. Initialize database

npm run rebuild



# 5. Start the server

npm start          # stdio mode for Claude Desktop

npm run start:http # HTTP mode for remote access

开发命令


# Build & Test

npm run build          # Build TypeScript

npm run rebuild        # Rebuild node database

npm run test-nodes     # Test critical nodes

npm run validate       # Validate node data

npm test               # Run all tests



# Update Dependencies

npm run update:n8n:check  # Check for n8n updates

npm run update:n8n        # Update n8n packages



# Run Server

npm run dev            # Development with auto-reload

npm run dev:http       # HTTP dev mode

📚 文档

设置指南

安装指南 - 全面的安装说明
Claude 桌面设置 - 详细的 Claude 配置
Docker 指南 - 高级 Docker 部署选项
MCP 快速入门 - 快速开始使用 n8n-MCP

功能文档

工作流差异操作 - 节省令牌的工作流更新（新增！）
事务性更新 - 两阶段工作流编辑
MCP 基础知识 - AI 优化工具指南
验证系统 - 智能验证配置文件

开发与部署

Railway 部署 - 一键云部署指南- HTTP 部署 - 远程服务器设置指南
依赖管理 - 保持 n8n 包同步
Claude 的访谈 - n8n-MCP 在现实世界中的影响

项目信息

变更日志 - 完整的版本历史
Claude 指南 - 该代码库的 AI 指导
MCP 工具参考 - 可用工具的完整列表

📊 指标与覆盖率

当前数据库覆盖率（n8n v1.117.2）：

✅ 541/541 节点加载（100%）
✅ 541 节点具有属性（100%）
✅ 470 节点具有文档（87%）
✅ 271 个支持 AI 的工具检测到
✅ 2,646 个预提取的模板配置
✅ 2,709 个工作流模板可用（100% 元数据覆盖率）
✅ AI 代理 & LangChain 节点 完全文档化
⚡ 平均响应时间：~12ms
💾 数据库大小：~68MB（包括带有元数据的模板）

🔄 最近更新

请参阅 CHANGELOG.md 以获取完整的版本历史和最近更改。

⚠️ 已知问题

Claude 桌面容器管理

容器累积（已在 v2.7.20+ 中修复）

之前的版本存在一个问题，即在 Claude 桌面会话结束时容器不会正确清理。此问题已在 v2.7.20+ 中通过适当的信号处理得到解决。

为了最佳的容器生命周期管理：

使用 --init 标志（推荐）- Docker 的 init 系统确保正确的信号处理：

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

确保您使用的是 v2.7.20 或更高版本 - 检查您的版本：

docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest --version

🧪 测试

该项目包含一个全面的测试套件，共有 2,883 个测试，确保代码质量和可靠性：


# Run all tests

npm test



# Run tests with coverage report

npm run test:coverage



# Run tests in watch mode

npm run test:watch



# Run specific test suites

npm run test:unit           # 933 unit tests

npm run test:integration    # 249 integration tests

npm run test:bench          # Performance benchmarks

测试套件概述

总测试数：2,883（100% 通过）
- 单元测试：99 个文件中的 2,526 个测试
- 集成测试：20 个文件中的 357 个测试
执行时间：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 个测试）：配置、入口点、安全验证

有关详细的测试文档，请参阅测试架构。

📦 许可证

MIT 许可证 - 详情请参阅 LICENSE。

感谢致谢！ 如果您使用了 n8n-MCP，请考虑：

⭐ 为本仓库加星
💬 在您的项目中提及它
🔗 链接到本仓库

🤝 贡献

欢迎贡献！请：1. 叉分仓库
2. 创建功能分支
3. 运行测试 (npm test)
4. 提交拉取请求

🚀 维护者：自动化发布

此项目使用由版本变更触发的自动化发布：


# Guided release preparation

npm run prepare:release



# Test release automation

npm run test:release-automation

系统自动处理：

🏷️ 包含更新日志内容的 GitHub 发布
📦 NPM 包发布
🐳 多平台 Docker 镜像
📚 文档更新

详见自动化发布指南获取完整详情。

👏 致谢

n8n 团队提供的工作流自动化平台
Anthropic 提供的模型上下文协议
本项目的所有贡献者和用户

模板归属

本项目中的所有工作流模板均从 n8n 的公共模板库 n8n.io/workflows 获取。每个模板包括：

完整归因于原始创建者（姓名和用户名）
直接链接到 n8n.io 上的源模板
原始工作流 ID 以供参考

本项目中的人工智能代理指令包含强制性的归属要求。当使用任何模板时，人工智能将自动：

分享模板作者的姓名和用户名
提供指向 n8n.io 上原始模板的直接链接
以如下格式显示归属：“此工作流基于 [作者] (@[用户名]) 的模板。查看原文：[url]”

模板创建者保留对其工作流的所有权利。本项目索引模板以通过 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 创作者社区！

查看源码项目主页

MCP 服务配置

服务介绍

n8n-MCP

概览

⚠️ 重要安全警告

🚀 快速开始

选项1：npx（最快 - 无需安装！）🚀

选项2：Docker（简单且隔离）🐳

🏠 本地 n8n 实例配置

🔐 隐私与遥测

选择退出

⚙️ 数据库与内存配置

数据库适配器

内存优化 (sql.js)

内存泄漏修复 (v2.20.2)

💖 支持此项目

选项 3：本地安装（用于开发）

选项 4：Railway 云部署（一键部署）☁️

🔧 n8n 集成

💻 连接您的 IDE

Claude Code

Visual Studio Code

Cursor

Windsurf

Codex

🎓 添加 Claude 技能（可选）

🤖 Claude 项目设置

核心原则

1. 无声执行

2. 并行执行

3. 模板优先

4. 多级验证

5. 永不信任默认值

工作流过程

重要警告

⚠️ 永不信任默认值

⚠️ 示例可用性

验证策略

第 1 级 - 快速检查（构建前）

第 2 级 - 全面验证（构建前）

第 3 级 - 完整验证（构建后）

第 4 级 - 部署后

响应格式

初始创建

修改

批量操作

重要：addConnection 语法

⚠️ 重要：IF 节点多输出路由

removeConnection 语法

示例工作流

模板优先方法

从头开始构建（如果没有模板）

批量更新

重要规则

核心行为

归因与致谢

性能

代码节点使用

最受欢迎的 n8n 节点（用于 get_node_essentials）：

🚨 重要：分享指南

功能

💬 为什么选择n8n-MCP？来自Claude的证言

📡 可用的MCP工具

核心工具

模板工具

验证工具

高级工具

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

工作流管理

执行管理

系统工具

示例用法

💻 本地开发设置

开发命令

📚 文档

设置指南

功能文档

开发与部署

项目信息

📊 指标与覆盖率

开源版与企业版