n8n-mcp接入Windsurf:让AI带着2412个节点的知识帮你搭工作流
把 n8n-mcp 连进 Windsurf,AI 助手就不再是"凭印象写配置",而是能直接查到 n8n 全部 2412 个节点的参数、操作和真实示例。做完这套接入,你在聊天面板里就能让 AI 搜节点、验配置、建工作流,还能连上自己的 n8n 实例直接创建和测试。
价值速览
接入完成后,你的 Windsurf 聊天窗口会多出一组 MCP 工具,大致能干这些事:
| 能力 | 你实际能得到什么 |
|---|---|
| 查节点 | 全文检索 2412 个节点(829 核心 + 1583 社区),参数覆盖率 99% |
| 找模板 | 在 2352 个工作流模板里按任务、复杂度、目标人群筛选 |
| 验配置 | validate_node 做 required 字段快检(<100ms),validate_workflow 做整链校验 |
| 管实例 | 配置 API Key 后可直接创建、更新、删除、测试工作流,共 16 个管理工具 |
不想从零搭的话,还可以叠加官方的 Claude Skills 技能包,教 AI 按"模板优先、多级验证"的流程干活。
前置条件
动手前确认这几样,缺哪个补哪个:
- Node.js v16 或更高(
node -v看一眼) - Windsurf IDE 已安装并打开一个项目
- 想调实例管理工具的话,需要一个能访问的 n8n 实例 + API Key(Settings → API 里创建)
- 只用文档检索类工具的话,连 n8n 实例都可以没有,npx 拉包即跑
打开MCP入口
- 打开 Windsurf 右上角设置图标,进入 Settings
- 定位到 Windsurf Settings 下的 MCP Servers > Manage Plugins
- 点 View Raw Config,进入原始配置编辑区
这个入口是 Windsurf 管理所有 MCP 服务器的统一位置,后面每次改配置都回这里。
填入服务器配置
在 Raw Config 里添加下面这段。npx n8n-mcp 会现场拉包启动,无需全局安装:
{
"mcpServers": {
"n8n-mcp": {
"command": "npx",
"args": ["n8n-mcp"],
"env": {
"MCP_MODE": "stdio",
"LOG_LEVEL": "error",
"DISABLE_CONSOLE_OUTPUT": "true"
}
}
}
}
三个 env 变量各有分工:MCP_MODE=stdio 声明走标准输入输出通道;LOG_LEVEL=error 只留错误日志;DISABLE_CONSOLE_OUTPUT=true 关掉一切终端杂音——stdio 模式下多打的字会污染协议,这是官方推荐的最小配置。
如果本地调试,也可以克隆仓库后 npm install 再 npm run build,用构建产物替代 npx:
git clone https://gitcode.com/GitHub_Trending/n8/n8n-mcp
cd n8n-mcp
npm install
打通n8n实例
想让 AI 不只"查资料"而是"动手建",就在上面的 env 里追加两行:
"N8N_API_URL": "https://your-n8n-instance.com",
"N8N_API_KEY": "your-api-key"
把 URL 换成你实例的实际地址,API Key 从 n8n 的 Settings → API 里创建。保存后点配置区的刷新按钮让服务器重启,不用重启整个 Windsurf。
落一份项目约定
AI 的表现很大程度取决于你怎么"使唤"它,官方给了一套现成的项目指令:
- 在项目根目录新建
.windsurfrules文件 - 把 README 的 Claude Project Setup 章节里的系统指令整段粘进去
- 按需增删——比如团队有固定命名规范,就补进指令
这份指令的核心是三条:先查模板再从零建(2352 个模板可用)、validate_node(minimal) → validate_node(full) → validate_workflow 三级验证、永远显式写全参数(默认值是运行时故障的头号来源)。
跑通验证
做没做对,看两个可观察的信号:
- 打开命令面板(Ctrl+Shift+P / Cmd+Shift+P),输入并执行
n8n-mcp: View tools - 看到类似下图的服务器卡片:
Status: ✓ connected,Tools: 39 tools
数字对得上就说明链路通了:7 个核心工具(文档检索、节点检索、模板检索、两级验证等)+ 实例管理工具,合计 39 个。
再加一道实测:在聊天里直接问"用 search_nodes 找一个 Slack 节点,给出它的必填参数"。AI 能调用工具并返回结构化参数列表,接入才算真正闭环。
避坑速查
- 状态一直转圈 / 显示 disconnected → 多半是 npx 拉包超时或网络问题;检查 Node 版本是否 ≥16,必要时配代理
- View tools 里没有 n8n_ 管理工具* →
N8N_API_URL/N8N_API_KEY没写或没刷新配置;两个变量必须同时存在才会注册管理工具 - 调管理工具报 401/403 → API Key 失效或权限不足;去 n8n Settings → API 重新签发
- AI 调用工具时面板刷大量日志 →
DISABLE_CONSOLE_OUTPUT没设为true,stdio 模式下会干扰协议解析 - 想限制 AI 的写权限 → 加
DISABLED_TOOLS环境变量禁用写入类工具(如n8n_create_workflow、n8n_delete_workflow),再配一个只读 API Key 做双保险,配方见 HTTP 部署文档
不止Windsurf
同一套配置换个入口就能复用到别的环境:Cursor 是项目根目录建 .cursor/mcp.json,配置 JSON 一字不差;Codex 走 ~/.codex/config.toml 的 TOML 格式。
各 IDE 的分步指南都在 docs 目录下:Windsurf、Cursor、Claude Code、Codex。
接入只需十几分钟,换来的是 AI 从"会说话"到"懂 n8n"的质变:查得到参数、验得了配置、建得出工作流。下一步建议读一遍 自托管指南,看看 npx / Docker / HTTP 三种部署形态怎么选;想改工具行为的话,源码在 src/mcp/ 目录。配置完去聊天面板里让 AI 建一个你的第一条工作流吧。
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考






