n8n MCP 服务器

一个模型上下文协议（MCP）服务器，允许 AI 助手通过自然语言与 n8n 工作流进行交互。

概述

本项目提供了一个模型上下文协议（MCP）服务器，使 AI 助手能够无缝地与流行的工作流自动化工具 n8n 进行交互。它充当桥梁，使 AI 助手能够使用自然语言命令以编程方式管理和控制 n8n 工作流及执行。

安装

先决条件

• Node.js 20 或更高版本
• 已启用 API 访问的 n8n 实例

从 npm 安装

npm install -g @leonardsellem/n8n-mcp-server

从源代码安装

# 克隆仓库
git clone https://github.com/leonardsellem/n8n-mcp-server.git
cd n8n-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 可选：全局安装
npm install -g .

Docker 安装

您也可以使用 Docker 运行服务器：

# 拉取镜像
docker pull leonardsellem/n8n-mcp-server

# 使用您的 n8n API 配置运行容器
docker run -e N8N_API_URL=http://your-n8n:5678/api/v1 \
  -e N8N_API_KEY=your_n8n_api_key \
  -e N8N_WEBHOOK_USERNAME=username \
  -e N8N_WEBHOOK_PASSWORD=password \
  leonardsellem/n8n-mcp-server

更新服务器

更新服务器的方式取决于您最初安装的方式。

1. 通过 npm 全局安装

如果您使用 npm install -g @leonardsellem/n8n-mcp-server 安装了服务器：

1. 打开终端或命令提示符。
2. 运行以下命令以获取最新版本：

   npm install -g @leonardsellem/n8n-mcp-server@latest
   

3. 如果服务器当前正在运行（例如作为后台进程或服务），则需要重新启动它才能使更改生效。

2. 从源代码安装

如果您克隆了仓库并从源代码安装：

1. 打开终端或命令提示符。
2. 导航到您克隆项目的目录：

   cd path/to/n8n-mcp-server
   

3. 如果您对代码进行了本地修改并希望保留这些更改，可以考虑暂存它们（可选）：

   git stash
   

   您稍后可以使用 git stash pop 将其恢复。
4. 从仓库拉取最新更改（假设您在 main 分支上）：

   git pull origin main
   

   如果您在其他分支上，请将 main 替换为您的分支名称。
5. 安装或更新任何已更改的依赖项：

   npm install
   

6. 重新构建项目以包含最新更新：

   npm run build
   

7. 如果您之前曾使用 npm install -g . 从该源文件夹全局安装过，可能需要再次运行此命令以更新全局链接：

   npm install -g .
   

8. 重启服务器。
   • 如果您直接使用类似 node build/index.js 的命令在 AI 助手的 MCP 配置中运行服务器，请确保路径仍然正确。使用 npm install -g . 然后以 n8n-mcp-server 作为命令应该能保持一致性。

3. 使用 Docker

如果您使用 Docker 运行服务器：

1. 从 Docker Hub 拉取最新镜像：

   docker pull leonardsellem/n8n-mcp-server:latest
   

2. 停止并移除旧容器。您需要容器的名称或 ID（可以使用 docker ps 查看）：

   docker stop <your_container_name_or_id>
   docker rm <your_container_name_or_id>
   

3. 使用更新后的镜像启动新容器。请使用您之前使用的相同 docker run 命令，并包含所有必要的环境变量（参考“Docker 安装”部分中的示例命令）。例如：

   docker run -e N8N_API_URL=http://your-n8n:5678/api/v1 \
     -e N8N_API_KEY=your_n8n_api_key \
     -e N8N_WEBHOOK_USERNAME=username \
     -e N8N_WEBHOOK_PASSWORD=password \
     leonardsellem/n8n-mcp-server:latest
   

   请确保使用 :latest 或您打算运行的特定版本标签。

配置

在您将运行服务器的目录中创建一个 .env 文件，以 .env.example 为模板：

cp .env.example .env

配置以下环境变量：

变量	描述	示例
N8N_API_URL	n8n API 的完整 URL，包括 /api/v1	http://localhost:5678/api/v1
N8N_API_KEY	用于与 n8n 身份验证的 API 密钥	n8n_api_...
N8N_WEBHOOK_USERNAME	Webhook 身份验证的用户名（如果使用 Webhook）	username
N8N_WEBHOOK_PASSWORD	Webhook 身份验证的密码	password
DEBUG	启用调试日志记录（可选）	true 或 false

生成 n8n API 密钥

1. 在浏览器中打开您的 n8n 实例。
2. 转到设置 > API > API 密钥。
3. 创建具有适当权限的新 API 密钥。
4. 将密钥复制到您的 .env 文件中。

使用

运行服务器

从安装目录运行：

n8n-mcp-server

或者如果已全局安装：

n8n-mcp-server

与 AI 助手集成

在构建服务器（npm run build）之后，您需要配置您的 AI 助手（例如带有 Claude 扩展的 VS Code 或 Claude Desktop 应用程序）以运行该服务器。这通常涉及编辑一个 JSON 配置文件。

配置示例（例如，在 VS Code 的 settings.json 或 Claude Desktop 的 claude_desktop_config.json 中）：

{
  "mcpServers": {
    // 为您的服务器指定一个唯一名称
    "n8n-local": {
      // 使用 'node' 来执行构建后的 JavaScript 文件
      "command": "node",
      // 提供构建后 `index.js` 文件的 *绝对路径*
      "args": [
        "/path/to/your/cloned/n8n-mcp-server/build/index.js"
        // 在 Windows 上，请使用双反斜杠：
        // "C:\\path\\to\\your\\cloned\\n8n-mcp-server\\build\\index.js"
      ],
      // 服务器所需的环境变量
      "env": {
        "N8N_API_URL": "http://your-n8n-instance:5678/api/v1", // 替换为您的 n8n 实例 URL
        "N8N_API_KEY": "YOUR_N8N_API_KEY", // 替换为您的 API 密钥
        // 仅当您计划使用 webhook 工具时才添加 webhook 凭据
        // "N8N_WEBHOOK_USERNAME": "your_webhook_user",
        // "N8N_WEBHOOK_PASSWORD": "your_webhook_password"
      },
      // 确保服务器已启用
      "disabled": false,
      // 默认自动批准设置
      "autoApprove": []
    }
    // ... 其他服务器也可以在此处配置
  }
}

关键点：

• 将 /path/to/your/cloned/n8n-mcp-server/ 替换为您克隆并构建仓库的实际绝对路径。
• 根据您的操作系统使用正确的路径分隔符（macOS/Linux 使用正斜杠 /，Windows 使用双反斜杠 \\）。
• 确保提供正确的 N8N_API_URL（包括 /api/v1）和 N8N_API_KEY。
• 必须先构建服务器（npm run build），然后助手才能运行 build/index.js 文件。

可用工具

该服务器提供了以下工具：

使用 Webhook

此 MCP 服务器支持通过 n8n webhook 执行工作流。要使用此功能：

1. 在 n8n 中创建一个由 webhook 触发的工作流。
2. 在您的 webhook 节点上设置基本身份验证。
3. 使用 run_webhook 工具触发工作流，只需传递工作流名称即可。

示例：

const result = await useRunWebhook({
  workflowName: "hello-world", // 将调用 <n8n-url>/webhook/hello-world
  data: {
    prompt: "来自 AI 助手的问候！"
  }
});

Webhook 身份验证会使用 N8N_WEBHOOK_USERNAME 和 N8N_WEBHOOK_PASSWORD 环境变量自动处理。

工作流管理

• workflow_list: 列出所有工作流
• workflow_get: 获取特定工作流的详细信息
• workflow_create: 创建新工作流
• workflow_update: 更新现有工作流
• workflow_delete: 删除工作流
• workflow_activate: 激活工作流
• workflow_deactivate: 停用工作流

执行管理

• execution_run: 通过 API 执行工作流
• run_webhook: 通过 webhook 执行工作流
• execution_get: 获取特定执行的详细信息
• execution_list: 列出某个工作流的所有执行记录
• execution_stop: 停止正在运行的执行

资源

该服务器提供了以下资源：

• n8n://workflows/list: 所有工作流列表
• n8n://workflow/{id}: 特定工作流的详细信息
• n8n://executions/{workflowId}: 某个工作流的所有执行记录
• n8n://execution/{id}: 特定执行的详细信息

路线图

n8n MCP 服务器是一个社区驱动的项目，其未来发展方向将由您的反馈和贡献决定！

目前，我们的路线图是灵活且持续开发中的。我们相信会根据用户的需求和想法不断改进服务器。

我们鼓励您参与塑造这款工具的未来：

• 提出功能建议： 您是否有关于新工具、资源或改进的想法？
• 讨论优先级： 您想就我们接下来应该关注什么发表意见吗？

请通过在我们的 GitHub Issues 页面 上提交问题来分享您的想法、功能请求和创意。让我们一起打造一款强大的 AI 助手工具吧！

开发

构建

npm run build

以开发模式运行

npm run dev

测试

npm test

代码检查

npm run lint

贡献

我们欢迎社区的贡献，并期待看到您如何帮助改进 n8n MCP 服务器！无论您是在修复 bug、提出新功能，还是改进文档，您的帮助都备受珍视。

报告 Bug

如果您遇到任何 bug，请通过在我们的 GitHub Issues 页面 上提交问题来报告。

提交 bug 报告时，请包含以下内容：

• 清晰且描述性的标题。
• 对问题的详细描述，包括重现 bug 的步骤。
• 您的环境信息（例如 Node.js 版本、n8n MCP 服务器版本、操作系统）。
• 任何相关的错误消息或截图。

提出改进建议

我们一直在寻找让服务器变得更好的方法。如果您对某项改进或新功能有想法，请在我们的 GitHub Issues 页面 上提交问题。

请提供：

• 清晰且描述性的建议标题。
• 对拟议改进的详细说明，以及它为何有益。
• 任何潜在的使用场景或示例。

提交 Pull Request

如果您想贡献代码，请按照以下步骤操作：

1. Fork 仓库： 创建您自己的 n8n-mcp-server 仓库 分支。
2. 创建分支： 在您的分支中为您的更改创建一个新分支（例如 git checkout -b feature/your-feature-name 或 bugfix/issue-number）。
3. 进行更改： 实现您的功能或修复 bug。
   • 确保您的代码符合现有的编码风格。（我们使用 Prettier 进行格式化，可以通过 npm run lint 运行）。
   • 如果适用，请为您的更改添加测试。您可以使用 npm test 运行测试。
4. 提交更改： 编写清晰简洁的提交信息。
5. 推送到您的分支： 将您的更改推送到您分叉的仓库。
6. 打开 Pull Request (PR)： 向官方 n8n-mcp-server 仓库的 main 分支提交 PR。
   • 为您的 PR 提供清晰的标题和描述，解释您所做的更改，并引用任何相关问题。

我们会尽快审查您的 PR 并提供反馈。感谢您的贡献！

许可证

MIT

🚀 加入我们的团队：诚招联合维护者！

本项目是一个充满活力、由社区驱动的工具，深受AI爱好者和开发者的喜爱。目前，该项目由一位充满热情但并非资深工程师的个人以兼职方式维护，他致力于将AI与工作流自动化相结合。为了推动项目的蓬勃发展、确保其长期健康运行，并满足不断增长的用户需求，我们正在寻找热情洋溢的联合维护者加入团队！

为什么参与贡献？

• 学习与成长： 在TypeScript、Node.js、API集成以及AI工具开发等领域提升你的技能。
• 协作共赢： 与其他积极进取的开发者和AI用户并肩合作。
• 产生影响： 直接塑造项目的未来，帮助打造一款对AI社区极具价值的工具。
• 开源经验： 获得参与开源项目的经验。

你可以如何贡献力量？

我们欢迎多种形式的贡献！以下是一些你可以大展身手的领域：

• 修复Bug： 帮助我们识别并解决各类问题，提升系统稳定性。
• 功能开发： 根据用户需求和你的创意，实现新的工具和功能。
• 文档编写： 完善指南、示例和API参考，让项目更加易用。
• 测试： 优化我们的测试套件（单元测试、集成测试），确保代码质量和可靠性。
• CI/CD： 协助优化我们的开发与部署流程。
• 代码评审： 对拉取请求提供反馈，帮助维护代码规范。
• 社区支持： 回答用户问题，协助管理社区讨论。

立即行动吧！

如果你对AI与工作流自动化结合的应用充满兴趣，并希望获得一次有意义的开源贡献机会，我们非常期待你的加入！

准备好贡献了吗？

1. 访问我们的GitHub Issues页面，查找现有任务、提出新想法，或表达你成为联合维护者的意愿。
2. 你可以创建一个标题为“联合维护者申请”的议题来正式提交申请，或者直接从现有议题开始贡献。
3. 如果有任何疑问，也欢迎随时联系现有的维护者。

让我们携手共建AI驱动的工作流自动化未来！🙌

感谢社区的支持！

n8n-mcp-server 快速上手指南

n8n-mcp-server 是一个基于模型上下文协议（MCP）的服务器，它允许 AI 助手通过自然语言指令与 n8n 工作流自动化平台进行交互，实现工作流的创建、执行和管理。

环境准备

在开始之前，请确保满足以下前置条件：

• Node.js: 版本 20 或更高。
• n8n 实例: 需要有一个可访问的 n8n 实例，并已启用 API 访问权限。
• API Key: 需要在 n8n 中生成用于认证的 API Key。

安装步骤

你可以选择通过 npm 全局安装、源码安装或使用 Docker 运行。

方式一：通过 npm 全局安装（推荐）

这是最简单的安装方式：

npm install -g @leonardsellem/n8n-mcp-server

方式二：从源码安装

如果你需要修改代码或参与开发：

# 克隆仓库
git clone https://github.com/leonardsellem/n8n-mcp-server.git
cd n8n-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# (可选) 全局链接
npm install -g .

方式三：使用 Docker

# 拉取镜像
docker pull leonardsellem/n8n-mcp-server

# 运行容器（请替换环境变量为你的实际配置）
docker run -e N8N_API_URL=http://your-n8n:5678/api/v1 \
  -e N8N_API_KEY=your_n8n_api_key \
  -e N8N_WEBHOOK_USERNAME=username \
  -e N8N_WEBHOOK_PASSWORD=password \
  leonardsellem/n8n-mcp-server

基本使用

1. 配置环境变量

在项目目录或运行目录下创建 .env 文件，填入 n8n 的连接信息：

cp .env.example .env

编辑 .env 文件，配置以下关键变量：

变量	说明	示例
N8N_API_URL	n8n API 完整地址（需包含 /api/v1）	http://localhost:5678/api/v1
N8N_API_KEY	n8n API 密钥	n8n_api_...
N8N_WEBHOOK_USERNAME	Webhook 认证用户名（可选）	username
N8N_WEBHOOK_PASSWORD	Webhook 认证密码（可选）	password

如何获取 API Key: 登录 n8n -> 设置 (Settings) -> API -> API Keys -> 创建新密钥。

2. 启动服务器

如果已全局安装，直接在终端运行：

n8n-mcp-server

如果是源码安装且未全局链接，运行：

node build/index.js

3. 集成到 AI 助手

配置你的 AI 客户端（如 Claude Desktop 或支持 MCP 的 VS Code 插件）以连接该服务器。以下是一个典型的 claude_desktop_config.json 配置示例：

{
  "mcpServers": {
    "n8n-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/n8n-mcp-server/build/index.js"
      ],
      "env": {
        "N8N_API_URL": "http://your-n8n-instance:5678/api/v1",
        "N8N_API_KEY": "YOUR_N8N_API_KEY"
      },
      "disabled": false
    }
  }
}

注意：

• 请将 args 中的路径替换为你本地的绝对路径。
• Windows 用户请使用双反斜杠 \\ 作为路径分隔符。
• 确保 N8N_API_URL 和 N8N_API_KEY 填写正确。

4. 功能验证

配置完成后，你可以在 AI 对话中直接使用自然语言操作 n8n，例如：

• “列出所有工作流”
• “运行名为 'hello-world' 的工作流”
• “查看最近一次执行的详情”

服务器支持的主要工具包括：workflow_list, execution_run, run_webhook, workflow_activate 等。