n8n MCP Server

n8n MCP 服务

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

概述

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

安装

前提条件

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

从 npm 安装

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

从源代码安装

# Clone the repository
git clone https://github.com/leonardsellem/n8n-mcp-server.git
cd n8n-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Optional: Install globally
npm install -g .

Docker 安装

你也可以使用 Docker 运行该服务：

# Pull the image
docker pull leonardsellem/n8n-mcp-server

# Run the container with your n8n API configuration
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. 重启服务。
   • 如果你在 AI 助手的 MCP 配置中直接使用 node build/index.js 之类的命令运行服务，请确认路径仍然正确。使用 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.example 作为模板，在运行服务的目录中创建 .env 文件：

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. 前往 Settings > API > API Keys
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": {
    // Give your server a unique name
    "n8n-local": {
      // Use 'node' to execute the built JavaScript file
      "command": "node",
      // Provide the *absolute path* to the built index.js file
      "args": [
        "/path/to/your/cloned/n8n-mcp-server/build/index.js"
        // On Windows, use double backslashes:
        // "C:\\path\\to\\your\\cloned\\n8n-mcp-server\\build\\index.js"
      ],
      // Environment variables needed by the server
      "env": {
        "N8N_API_URL": "http://your-n8n-instance:5678/api/v1", // Replace with your n8n URL
        "N8N_API_KEY": "YOUR_N8N_API_KEY", // Replace with your key
        // Add webhook credentials only if you plan to use webhook tools
        // "N8N_WEBHOOK_USERNAME": "your_webhook_user",
        // "N8N_WEBHOOK_PASSWORD": "your_webhook_password"
      },
      // Ensure the server is enabled
      "disabled": false,
      // Default autoApprove settings
      "autoApprove": []
    }
    // ... other servers might be configured here
  }
}

要点：

• 将 /path/to/your/cloned/n8n-mcp-server/ 替换为克隆并构建该仓库的实际绝对路径。
• 使用适用于你操作系统的路径分隔符（macOS/Linux 使用正斜杠 /，Windows 使用双反斜杠 \\）。
• 确保提供正确的 N8N_API_URL（包含 /api/v1）和 N8N_API_KEY。
• 助手运行 build/index.js 文件前，需要先构建服务（npm run build）。

可用工具

该服务提供以下工具：

使用 Webhook

此 MCP 服务支持通过 n8n Webhook 执行工作流。使用此功能的步骤如下：

1. 在 n8n 中创建由 Webhook 触发的工作流。
2. 在 Webhook 节点上设置 Basic Authentication。
3. 使用 run_webhook 工具触发工作流，只需传入工作流名称。

示例：

const result = await useRunWebhook({
  workflowName: "hello-world", // Will call <n8n-url>/webhook/hello-world
  data: {
    prompt: "Hello from AI assistant!"
  }
});

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 Server 是一个由社区推动的项目，未来的发展方向将由你的反馈和贡献共同塑造！

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

欢迎参与塑造此工具的未来：

• 提出功能建议： 想到了新的工具、资源或改进点？
• 讨论优先级： 想对我们接下来应重点关注的事项发表意见？

请在我们的 GitHub Issues 页面提交你的想法、功能请求和建议。让我们一起为 AI 助手打造强大的工具！

开发

构建

npm run build

在开发模式下运行

npm run dev

测试

npm test

代码检查

npm run lint

贡献

我们欢迎社区贡献，也很期待了解你如何帮助改进 n8n MCP Server！无论是修复错误、提出新功能，还是改进文档，你的帮助都弥足珍贵。

报告错误

如果你遇到错误，请在我们的 GitHub Issues 页面提交问题。

提交错误报告时，请提供以下信息：

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

提出改进建议

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

请提供：

• 清晰且具有描述性的建议标题。
• 对拟议改进内容及其益处的详细说明。
• 任何潜在的用例或示例。

提交拉取请求

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

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

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

许可证

MIT

🚀 加入我们的团队：招募共同维护者！

这是一个充满活力、由社区驱动的工具，AI 爱好者和开发者都在积极使用。目前，该项目由一位热情的个人兼职维护；他并非资深工程师，但致力于将 AI 与工作流自动化相结合。为了推动项目蓬勃发展、确保其长远健康，并跟上不断增长的用户群体，我们正在寻找热心的共同维护者加入团队！

为什么要贡献？

• 学习与成长： 提升你在 TypeScript、Node.js、API 集成和 AI 工具开发等领域的技能。
• 协作： 与其他积极投入的开发者和 AI 用户一起合作。
• 发挥影响： 直接塑造项目的未来，帮助为 AI 社区打造有价值的工具。
• 开源： 积累参与开源项目的经验。

你可以如何提供帮助

我们欢迎各种形式的贡献！以下是一些可以发挥重要作用的领域：

• 修复 Bug： 帮助我们发现并修复 Bug，提升稳定性。
• 功能开发： 根据用户需求和你的想法，实现新的工具和功能。
• 文档： 改进指南、示例和 API 参考，让项目更易于使用。
• 测试： 完善测试套件（单元测试、集成测试），确保代码质量和可靠性。
• CI/CD： 帮助简化开发和部署流水线。
• 代码审查： 为拉取请求提供反馈，帮助维护代码规范。
• 社区支持： 协助解答用户问题并帮助管理讨论。

快来参与！

如果你对 AI 与工作流自动化的结合感兴趣，并且正在寻找有意义的开源机会，我们很期待听到你的声音！

准备好贡献了吗？

1. 查看我们的 GitHub Issues 页面，寻找现有任务、提出新想法，或表达你成为共同维护者的意愿。
2. 你可以创建标题为 "Co-maintainer Application" 的 issue 正式申请，也可以直接开始为现有 issue 做贡献。
3. 你也可以随时联系现有维护者，提出问题。

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

感谢社区的支持！