n8n 本机部署与 MCP 接入记录

2026-10-13

功能说明

这份文档记录本机 n8n 的部署方式、账号初始化、API Key 接入方式、MCP 配置位置，以及后续继续使用时的注意事项。

目标不是教人从零安装 Docker 版，而是把这台机器上已经跑通的这一套留下来，后面遇到重启、迁移、排障，不用再重新踩坑。

当前部署结果

  • 部署方式：npx -y n8n@latest start
  • 访问地址：http://127.0.0.1:5678
  • 健康检查：/healthz 返回 {"status":"ok"}
  • Owner 账号：已创建
  • n8n API Key：已创建并已写入 n8n MCP 配置文件
  • n8n MCP Bridge：已验证可正常调用

项目结构 / 关键路径

n8n 相关

  • n8n 用户目录：C:\Users\用户名\.local\share\n8n
  • n8n 数据库：C:\Users\用户名\.local\share\n8n\.n8n\database.sqlite
  • n8n Web 地址：http://127.0.0.1:5678

n8n MCP 相关

  • MCP env 文件：C:\Users\用户名\.config\n8n-mcp\env
  • 关键配置项：
  • N8N_BASE_URL=http://127.0.0.1:5678
  • N8N_API_KEY=***
  • N8N_MCP_TIMEOUT=30
  • N8N_CONTAINER_NAME=n8n
  • N8N_MCP_ALLOW_DOCKER_LOGS=false

本次修改记录

1. 本机启动 n8n

使用 Node / npx 直接启动，没有走 Docker。

参考启动方式：

export N8N_USER_FOLDER="$HOME/.local/share/n8n"
npx -y n8n@latest start

实际验证结果：

  • 5678 端口可访问
  • /healthz 返回正常
  • 浏览器首次打开进入 /setup

2. 初始化 owner 账号

已完成首次 owner 设置。

注意：账号和密码属于敏感认证信息，不要写进公开文档、Git 仓库或截图里。

3. 创建 API Key

通过 n8n 登录态创建了 API Key，并确认该 key 对官方 API 可用。

实际验证过的接口：

GET /api/v1/workflows
Header: X-N8N-API-KEY: ***

返回结果：200 OK，空库时返回：

{"data":[],"nextCursor":null}

4. 写入 n8n MCP 配置

已将可用 API Key 写入：

C:\Users\用户名\.config\n8n-mcp\env

5. 验证 MCP Bridge

重启 Hermes / 重载 MCP 后验证通过：

  • health：api_ok = true
  • list_workflows：200 OK
  • list_executions：200 OK

空库时 workflows / executions 返回空数组属正常现象，并非错误。

注意事项

1. 不要把 API Key、密码写进文档或 Git

API Key 一旦泄露，他人即可直接操作你的 n8n 实例。

必须遵守：

  • 不写进 .md
  • 不提交到 Git
  • 不贴到群里
  • 不放进截图里

只允许放在：

  • C:\Users\用户名\.config\n8n-mcp\env
  • 或其他本地受控密钥文件

2. MCP 改了 env 以后，通常要重启 Hermes / reload MCP

本次已确认：

  • env 文件写对了，不代表 MCP 立刻生效
  • Hermes / MCP 进程可能还拿着旧配置

如果出现这种情况：

  • n8n 官方 API 直接 curl 调用正常
  • 但 n8n-mcp health 还报 401

优先处理：

  1. 重启 Hermes
  2. 或执行 /reload-mcp
  3. 再重新执行 health 检查

3. 空 workflows / executions 不代表坏了

如果返回：

{"data":[],"nextCursor":null}

这通常仅表示尚未创建工作流，并非认证失败。

4. Docker 相关配置先别当真

当前这套不是 Docker 部署，所以：

  • N8N_CONTAINER_NAME=n8n 只是兼容配置占位
  • N8N_MCP_ALLOW_DOCKER_LOGS=false 保持关闭即可

不要拿 Docker 日志当主要排障入口。

5. n8n 首次初始化卡住时，先怀疑进程状态或数据库残留

本次实际遇到过：

  • setup 请求挂起
  • 旧进程异常占着端口
  • 数据库需要重新初始化

如果下次再遇到“点击 Next 无响应”：

优先排查：

  1. 5678 端口是不是被异常 node 进程占着
  2. n8n 进程是否处于假死状态
  3. database.sqlite 是否处于坏状态或半初始化状态

不必优先怀疑密码格式或浏览器问题，优先检查进程状态和数据目录，可节省排查时间。

测试方法

1. 检查 n8n 服务是否运行

curl http://127.0.0.1:5678/healthz

期望结果：

{"status":"ok"}

2. 验证 API Key 是否可用

curl -H 'X-N8N-API-KEY: ***' http://127.0.0.1:5678/api/v1/workflows

期望结果：

  • 返回 200 OK
  • 空库时返回空数组

3. 验证 MCP Bridge 是否可用

验证项：

  • mcp_n8n_bridge_health
  • mcp_n8n_bridge_list_workflows
  • mcp_n8n_bridge_list_executions

期望结果：

  • api_ok = true
  • status_code = 200

故障排查

情况 1：n8n 页面打不开

排查顺序：

  1. 检查 5678 端口是否监听
  2. 检查 node/n8n 进程是否还在
  3. 重新启动 n8n

情况 2：页面能开，但 /setup 或登录卡死

排查顺序：

  1. 检查是否有旧 node 进程异常占用 5678 端口
  2. 检查数据库是否残留半初始化状态
  3. 必要时停进程后重建数据库

情况 3：curl 调用官方 API 正常，但 MCP 还是 401

根因通常不是 key 错，而是 MCP 没重载配置。

处理：

  1. 检查 C:\Users\用户名\.config\n8n-mcp\env
  2. 确认 N8N_BASE_URL 和 N8N_API_KEY 正确
  3. 重启 Hermes 或 reload MCP
  4. 再执行 health 检查

情况 4：MCP health 正常，但列表为空

这是正常的，说明认证通了，只是还没创建任何 workflow / execution。

恢复方案

方案 A：仅重启服务

重新运行：

export N8N_USER_FOLDER="$HOME/.local/share/n8n"
npx -y n8n@latest start

方案 B：保留数据，仅重配 MCP

如果只是 key 变了：

  1. 更新 C:\Users\用户名\.config\n8n-mcp\env
  2. 重启 Hermes / reload MCP
  3. 重新执行 health 检查

方案 C：重建本地 n8n 初始化状态

这个动作有数据损失风险，只适合明确要重建时做。

核心思路：

  1. 停掉 n8n 进程
  2. 备份或删除 database.sqlite
  3. 重启 n8n
  4. 重新走 owner setup
  5. 重新生成 API Key
  6. 重新写入 n8n-mcp\env

方案 D：完整恢复检查清单

  • 服务地址是否仍是 http://127.0.0.1:5678
  • 数据目录是否仍在 C:\Users\用户名\.local\share\n8n
  • database.sqlite 是否存在
  • C:\Users\用户名\.config\n8n-mcp\env 是否存在
  • API Key 是否已更新
  • Hermes 是否已重启 / MCP 是否已重载

后续建议

下一步最值得做的只有两个：

  1. 建一个最小测试工作流，确认 UI 创建、保存、执行链路都通
  2. 把 n8n 做成稳定启动方式（如脚本 / 服务化），别每次手搓启动

目前虽已跑通，但仍处于“可用”阶段，尚未达到“省心”。

启动 / 停止 / 重启速查

以下为速查命令，便于日后直接查阅。

1. 前台启动（临时调试用）

export N8N_USER_FOLDER="$HOME/.local/share/n8n"
npx -y n8n@latest start

适合：

  • 看启动日志
  • 排查启动失败
  • 临时验证配置

缺点：

  • 关掉终端就没了
  • 不适合长期挂着

2. 后台启动（当前实际可用思路）

如果以后还想在 Hermes 里后台拉起，核心命令就是：

export N8N_USER_FOLDER="$HOME/.local/share/n8n"
npx -y n8n@latest start

需将其置于后台进程运行，避免关闭终端窗口。

3. 停止 n8n

先找占用 5678 端口的进程：

netstat -ano | grep 5678

如果看到监听 PID，再结束它：

taskkill //F //PID <PID>

Windows 下不建议直接套用 Linux 的 kill 命令，可能无法准确终止目标进程，直接使用 taskkill 更可靠。

4. 重启 n8n

推荐顺序：

  1. 先停掉占用 5678 的进程
  2. 再重新执行启动命令
  3. 用 /healthz 验证

验证命令：

curl http://127.0.0.1:5678/healthz

期望返回：

{"status":"ok"}

5. 改了 API Key 之后怎么处理

如果重新生成了 n8n API Key，需同步更新两处配置。

正确顺序：

  1. 更新 C:\Users\用户名\.config\n8n-mcp\env
  2. 重启 Hermes 或执行 /reload-mcp
  3. 再测 MCP health

不然很容易出现：

  • curl 调官方 API 正常
  • MCP 还是 401

这通常不是 Key 错误，而是旧配置未重载。

6. 建议以后补一个本地脚本

如果后面要长期用，建议单独做 3 个脚本：

  • start-n8n.bat
  • stop-n8n.bat
  • restart-n8n.bat

这样以后就不用每次手打命令。当前文档先把流程记清楚，后续真要常用，再把脚本落地，比提前过度设计更稳妥。

← 返回文章列表