Hermes n8n MCP Plus

用于从 Hermes Agent 管理 n8n 的本地 stdio MCP 桥接器——现已支持写入工具。

这是 CyberSamuraiX/hermes-n8n-mcp 的一个分支，在原有只读/运维工具集的基础上扩展了 create_workflow、update_workflow 和 delete_workflow。它让 Hermes 拥有完整的 n8n 工作流管理能力，同时无需将 n8n 暴露到公网，也无需在 Hermes 配置中存放 API 密钥。

功能

暴露以下 MCP 工具：

• health — 检查 n8n API 可达性及可选的 Docker 容器状态

• list_workflows — 列出工作流，可按激活状态过滤

• get_workflow — 检查单个工作流，含敏感字段的字段会被脱敏

• find_workflows — 搜索工作流元数据

• list_executions — 列出最近的执行记录

• get_execution — 检查单次执行；默认不返回负载数据

• recent_failures — 最近的失败/错误执行

• export_workflow — 获取脱敏后的工作流 JSON，用于备份/审查

• activate_workflow — 按 ID 激活工作流

• deactivate_workflow — 按 ID 停用工作流

• container_logs — 可选的 Docker 日志，带行级脱敏

• create_workflow — 从 JSON 定义创建工作流。默认试运行。

• update_workflow — 按 ID 修补现有工作流（名称、节点、连接、设置、标签）。应用前先预览当前状态。默认试运行。

• delete_workflow — 按 ID 永久删除工作流。删除前先预览导出备份。默认试运行。

所有三个写入工具都需要显式传入 confirm=true 参数才会真正执行变更。以 confirm=false（默认值）调用时，它们只返回将要发生什么的预览，不会发起任何改变 n8n 的 API 调用。

Related MCP server: n8n-ops-mcp

安全态势

• 仅 stdio。无 HTTP 服务器。无公开端口。

• API 密钥从环境变量或本地 dotenv 文件加载。

• .env 已被 gitignore。

• 示例配置使用 REPLACE_ME，绝不使用真实密钥。

• 工具响应会脱敏明显的凭据、令牌、密钥、密码和授权字段。

• 执行负载数据在 get_execution 中默认禁用。

• 工作流激活/停用、创建、更新和删除都是生产级变更操作。请像对待上了膛的武器一样对待它们。

• 写入工具默认试运行预览；除非调用方显式传入 confirm=true，否则不会创建、修补或删除任何内容。

• delete_workflow 在确认删除执行前，始终先获取工作流的导出/备份预览。

要求

• Python 3.10+

• 启用了原生 MCP 的 Hermes Agent

• n8n API 密钥

• 运行 Hermes 的机器可访问 n8n，通常为 http://127.0.0.1:5678

关键依赖锁定：mcp==1.29.0

官方 mcp PyPI 包于 2026-07-28 发布了破坏性变更的 v2.0.0，完全移除了 mcp.server.fastmcp（重命名为 MCPServer，移动了模块路径，将 httpx 换成了 httpx2 等）。如果 requirements.txt 使用宽松约束（如 mcp>=1.29.0），pip install 会解析到 2.0.0，服务器将在导入时崩溃并报错：

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

本仓库将 mcp==1.29.0（v2 之前最后一个稳定版本）锁定为硬性固定版本，而非下限。在代码库迁移到 v2 MCPServer API 之前，不要放宽此约束。如果你看到上述错误，请检查 pip show mcp——如果报告版本为 2.0.0 或更高，请运行：

pip uninstall -y mcp
pip install "mcp==1.29.0"

安装

git clone https://github.com/csenguttuvan/hermes-n8n-mcp-plus.git
cd hermes-n8n-mcp-plus
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

在继续之前，请验证安装是否正确落在预期的 SDK 版本上：

pip show mcp
python -c "from mcp.server.fastmcp import FastMCP; print('OK')"

存储你的 n8n 密钥

手动版本：

install -d -m 700 ~/.config/n8n-mcp-plus
cat > ~/.config/n8n-mcp-plus/env <<'EOF'
N8N_BASE_URL=http://127.0.0.1:5678
N8N_API_KEY=REPLACE_ME
N8N_MCP_TIMEOUT=30
N8N_CONTAINER_NAME=n8n
N8N_MCP_ALLOW_DOCKER_LOGS=true
EOF
chmod 600 ~/.config/n8n-mcp-plus/env

在本地替换 REPLACE_ME。不要提交真实文件。

本分支的工具还直接从环境中读取 N8N_API_KEY / N8N_API_URL，而不仅仅从 dotenv 文件读取，因此你也可以选择使用 ${N8N_API_KEY} 插值直接从 ~/.hermes/config.yaml 注入——见下文。

Hermes 配置

在 ~/.hermes/config.yaml 的 mcp_servers 下添加此项。如果原始的 n8n 桥接器已注册，请将其作为第二个独立条目（n8n_plus）添加，而不是替换它——这样可以保留一个安全的只读回退方案：

mcp_servers:
  n8n:
    command: /Users/admin/.hermes/mcp-installs/n8n/.venv/bin/python
    args:
      - /Users/admin/.hermes/mcp-installs/n8n/server.py
    enabled: true
    env:
      N8N_API_KEY: "${N8N_API_KEY}"
      N8N_API_URL: "http://localhost:5678/api/v1"

  n8n_plus:
    command: /Users/admin/projects/hermes-n8n-mcp-plus/.venv/bin/python
    args:
      - /Users/admin/projects/hermes-n8n-mcp-plus/server.py
    enabled: true
    env:
      N8N_API_KEY: "${N8N_API_KEY}"
      N8N_API_URL: "http://localhost:5678/api/v1"

缩进很重要。n8n: 和 n8n_plus: 必须位于同一缩进级别，直接放在 mcp_servers: 之下，中间不能有其他顶级键打断该块。在重新加载前，请验证文件能正确解析：

python3 -c "import yaml; d = yaml.safe_load(open('/Users/admin/.hermes/config.yaml')); print(list(d.get('mcp_servers', {}).keys()))"

然后在 Hermes 中重新加载 MCP：

/reload-mcp

或从 shell 执行：

hermes mcp test n8n_plus

工具以服务器名称前缀注册，例如 mcp__n8n_plus__create_workflow、mcp__n8n_plus__health，与原始桥接器的 mcp__n8n__* 工具区分开来（如果两者并行运行的话）。

在 Hermes 之外进行冒烟测试

. .venv/bin/activate
python -m py_compile server.py
python -c "import server; print('imported OK')"
hermes mcp test n8n_plus

如果 import server 挂起或抛出 ModuleNotFoundError: No module named 'mcp.server.fastmcp'，请重新检查上面的 mcp==1.29.0 锁定——这几乎总是依赖版本问题，而不是代码问题。

使用写入工具

所有三个写入工具都遵循相同的默认试运行模式。create_workflow 的示例流程：

Call mcp__n8n_plus__create_workflow with workflow={"name": "test", "nodes": [], "connections": {}} and confirm=false.

返回预览，不进行任何变更：

{
  "ok": false,
  "error": "Dry run only. Set confirm=true to create the workflow.",
  "workflow_preview": { "name": "test", "nodes": [], "connections": {} }
}

当预览看起来正确后，使用 confirm=true 重新运行以实际创建。同样的模式适用于 update_workflow（预览当前状态和提议的补丁）和 delete_workflow（删除前预览导出备份）。

任何新环境的推荐测试顺序：先 create_workflow，然后 list_workflows 确认已创建，接着 update_workflow，最后 delete_workflow——每一步都使用一次性工作流，并在 n8n UI 中逐步验证。

Docker 日志

container_logs 通过 shell 调用 Docker。如果运行 Hermes 的用户无法访问 Docker，请设置：

N8N_MCP_ALLOW_DOCKER_LOGS=false

其余 API 工具仍可正常工作。

生产使用注意事项

• 将 n8n 绑定到回环地址，置于反向代理之后。

• 不要通过 Caddy、nginx 或 Docker 端口暴露此 MCP 桥接器。

• 如果 n8n API 密钥曾出现在聊天日志、终端、CI 输出、截图或问题跟踪器中，请轮换密钥。

• 在变更工作流之前先备份。update_workflow 和 delete_workflow 在确认前都会预览状态，但在传入 confirm=true 之前，请务必自行检查预览。

• 未经针对 MCPServer v2 API 的测试，切勿放宽 requirements.txt 中的 mcp==1.29.0 锁定。

路线图

• 待 v2 API 稳定且本分支的工具集验证兼容后，从 FastMCP（v1.x）迁移到 MCPServer（v2.x）。

• 考虑添加 run_workflow 作为第四个写入工具，用于手动触发执行。

许可证

MIT。参见 LICENSE。