n8n-mcp HTTP Streamable 部署实战用 n8n-nodes-mcp 社区节点连接 n8n MCP Server【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp本篇技术指南基于 n8n-mcp 开源仓库完整讲解如何将 n8n MCP Server 以HTTP Streamable 传输方式对外暴露并通过 n8n 官方社区节点n8n-nodes-mcp在 n8n 工作流内建立 MCP 客户端连接、列出工具并调用工具。读完本文你将掌握从服务编排、Bearer Token 认证、MCP 凭证创建到 JSON-RPC 请求排错的全套落地流程并理解 HTTP Streamable 传输在仓库源码层面的实现原理。背景与适用场景n8n-mcp 是一个为 AI 编码助手Claude Desktop / Claude Code / Windsurf / Cursor提供的 Model Context ProtocolMCP服务器用于帮助 AI 构建 n8n 工作流。它本身以两种模式运行stdio 模式面向本地单进程客户端如 Claude Desktop通过标准输入输出进行 JSON-RPC 通信HTTP 模式通过 HTTP 对外提供服务适合容器化部署与远程访问也是本文的主角。当你想让n8n 本身作为 MCP 客户端去调用 n8n-mcp 暴露的工具例如在某个 n8n 工作流里动态查询节点文档、校验节点配置就需要把 n8n-mcp 以 HTTP 模式跑起来在 n8n 中安装n8n-nodes-mcp社区节点用 MCP API 凭证 MCP Client 节点建立 Streamable HTTP 连接。本文的配置全部以仓库内的 docker-compose.n8n.yml 为基准与仓库当前的实际部署方式保持一致。前置条件开始之前需要完成两件事。1. 安装 n8n-nodes-mcp 社区节点在 n8n 界面中进入Settings → Community Nodes设置 → 社区节点搜索并安装n8n-nodes-mcp如系统提示重启 n8n 使节点生效。2. 设置环境变量以允许工具调用n8n 默认出于安全考虑禁止社区节点调用工具必须显式放行。为 n8n 容器设置环境变量N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGEtrue在仓库提供的 docker-compose.n8n.yml 中n8n 服务本身并未内置该变量你需要在启动前通过.env文件或在environment段追加该配置。从源码看这个开关是 n8n 侧对社区节点工具能力的授权机制未开启时 MCP Client 节点无法真正执行工具调用。快速开始四步完成端到端部署Step 1启动服务仓库根目录下的 docker-compose.n8n.yml 同时编排了两个服务n8nn8nio/n8n:latest默认映射宿主机${N8N_PORT:-5678}:5678n8n-mcp使用仓库 Dockerfile 构建以N8N_MODEtrue、MCP_MODEhttp运行默认映射${MCP_PORT:-3000}:3000。启动前先清理旧的同名容器避免端口冲突# 停止并移除旧容器如果存在 docker stop n8n n8n-mcp docker rm n8n n8n-mcp # 以 HTTP Streamable 配置启动 docker-compose -f docker-compose.n8n.yml up -d启动完成后两个服务分别位于n8nhttp://localhost:5678n8n-mcphttp://localhost:3000注意该 compose 文件中的几个关键细节均可从 docker-compose.n8n.yml 源码确认配置项值说明N8N_MODEtruen8n-mcp 容器启用面向 n8n 的 N8N API 集成模式MCP_MODEhttpn8n-mcp 容器选择 HTTP 传输而非 stdioPORT${MCP_PORT:-3000}n8n-mcp 容器HTTP 监听端口默认 3000MCP_AUTH_TOKEN/AUTH_TOKEN同一变量两者被同时注入供 HTTP 模式认证使用N8N_API_URLhttp://n8n:5678n8n-mcp 容器通过 compose 内部网络访问 n8ndepends_on: n8n: condition: service_healthyn8n-mcp等待 n8n 健康检查通过后才启动两个服务共享同一个n8n-network桥接网络这正是后文 MCP Client 节点用容器名http://n8n-mcp:3000/mcp访问的原因——在 compose 网络内部容器名即 DNS 主机名。Step 2在 n8n 中创建 MCP 凭证打开 n8n 界面http://localhost:5678进入Credentials → Add credential凭证 → 添加凭证搜索MCP选择MCP API类型按如下配置字段Credential Name凭证名称n8n MCP ServerHTTP Stream URLhttp://localhost:3000/mcp从 n8n 外部访问时使用 localhost从工作流内访问走容器网络见 Step 3Messages Post Endpoint留空HTTP Streamable 传输不依赖独立的消息回发端点单一/mcpPOST 端点即可承载全部 JSON-RPC 交互Additional Headers附加请求头{ Authorization: Bearer test-secure-token-123456789 }保存凭证。凭证与容器内实际令牌的一致性AUTH_TOKEN是 n8n-mcp HTTP 模式的强制要求。从 docker-entrypoint.sh 的启动校验逻辑看当MCP_MODEhttp且既无AUTH_TOKEN也无AUTH_TOKEN_FILE时容器会直接报错退出此处 n8n 凭证里的 Bearer Token 必须与 compose 中注入的MCP_AUTH_TOKEN完全一致否则后续调用会收到 401。Step 3配置 MCP Client 节点向工作流中添加一个MCP Client节点配置如下Connection Type连接类型HTTP StreamableHTTP Streamable URLhttp://n8n-mcp:3000/mcp使用 compose 网络内的容器名而非 localhostAuthentication认证方式Bearer AuthCredentials凭证选择上一步创建的凭证Operation操作选择具体操作如List Tools或Call Tool这里的关键坑点在于 URL 主机名在 n8n 工作流运行时请求发生在 n8n 容器内部localhost指向的是 n8n 容器自身而非宿主机。必须使用 compose 服务名n8n-mcp由n8n-network桥接网络完成 DNS 解析与路由。Step 4测试连接执行工作流。连接成功的标志是 MCP Client 节点返回工具列表或工具调用结果若失败可按文末「故障排查」章节逐项核对。可用操作List Tools 与 Call Tooln8n-mcp 在 HTTP 模式下暴露的工具集与 stdio 模式一致。以List Tools操作可看到部分tools_documentationlist_nodesget_node_infosearch_nodesget_node_essentialsvalidate_node_config以及更多……这些工具均可在仓库源码中确认例如search_nodes定义于 src/mcp/tool-docs/discovery/search-nodes.tstools_documentation定义于 src/mcp/tool-docs/system/tools-documentation.ts两者同时被注册进 src/mcp/tools.ts 的最终工具列表。调用示例示例一获取节点信息get_node_infoTool Nameget_node_infoArguments{ nodeType: n8n-nodes-base.httpRequest }示例二搜索节点search_nodesTool Namesearch_nodesArguments{ query: webhook, limit: 5 }在Call Tool操作下MCP Client 会把上述参数以 JSON-RPCtools/call请求发送到服务端服务端执行后返回结果文本。导入预配置工作流仓库examples/目录当前仅包含 enhanced-documentation-demo.js 演示脚本并未内置文档所描述的n8n-mcp-streamable-workflow.json文件。若你本地已有该预配置工作流可按如下方式导入进入Workflows → Add workflow → Import from File工作流 → 添加工作流 → 从文件导入选择工作流 JSON 文件更新其中的凭证引用替换为你的 Bearer Token。故障排查Connection Refused连接被拒绝用docker ps确认两个容器都在运行查看 n8n-mcp 日志docker logs n8n-mcp确认工作流内使用的是http://n8n-mcp:3000/mcp容器名而非localhost。容器内部localhost指向自身跨容器访问必须走 compose 网络的服务名。Authentication Failed认证失败核对 n8n 凭证中的 Bearer Token 与 compose 注入的MCP_AUTH_TOKEN是否完全一致含前后空格检查 CORS 配置是否允许 n8n 的源。仓库 HTTP 服务默认通过Access-Control-Allow-Origin头放行跨域可用CORS_ORIGIN环境变量收紧docker-compose.n8n.yml 未显式覆盖该项。手动测试端点在宿主机上可以直接用 curl 验证服务与端点状态# 健康检查无需认证 curl http://localhost:3000/health # 手动测试 MCP 端点无 JSON-RPC 请求体时应返回解析错误 curl -X POST http://localhost:3000/mcp \ -H Authorization: Bearer test-secure-token-123456789 \ -H Content-Type: application/json第一条命令返回服务健康状态含status: ok、版本、运行时长等字段第二条命令因缺少合法 JSON-RPC 2.0 请求体会返回错误响应这本身即证明端点在收包、认证链路正常。架构原理从源码看 HTTP Streamable 的实现传输与协议Transport传输层HTTP Streamable即 MCP SDK 的StreamableHTTPServerTransportProtocol协议JSON-RPC 2.0 over HTTP POSTAuthentication认证Authorization: Bearer token请求头Endpoint端点单一/mcp端点承载所有操作初始化、工具列举、工具调用会话模型默认的固定实现中每个请求新建 MCP Server 实例无状态而仓库自 v2.31.8 起默认启用SingleSessionHTTPServersrc/http-server-single-session.ts按initialize握手创建会话、以Mcp-Session-Id请求头复用会话并带会话超时回收机制。认证链路Bearer Token 校验仓库的 HTTP 服务在收到/mcpPOST 请求后会按顺序执行认证检查Authorization头是否存在缺失则返回 401 并附带WWW-Authenticate质询头检查是否以Bearer前缀开头提取 token 后调用 src/utils/auth.ts 中的AuthManager.timingSafeCompare做恒定时间比较防止时序侧信道攻击对应安全加固项 CRITICAL-02校验失败统一返回 JSON-RPC 错误码-32001Unauthorized。这意味着 n8n 凭证中配置的 Bearer Token 必须与AUTH_TOKEN严格匹配且服务端并不接受空令牌——容器启动时若检测不到有效令牌会直接退出见 docker-entrypoint.sh 的环境校验。工具分发与执行在 src/http-server.ts 的/mcp路由处理逻辑中服务端按 JSON-RPC method 分发initialize与客户端协商 MCP 协议版本见 src/utils/protocol-version.ts 的negotiateProtocolVersion返回serverInfo与capabilitiestools/list返回文档工具列表当检测到已配置 n8n APIisN8nApiConfigured()时还会追加 n8n 管理类工具tools/call通过mcpServer.executeTool(toolName, toolArgs)执行具体工具结果封装为 MCP 兼容的contentvalidate_*系列校验工具还会附加structuredContent并对超大响应做 1MB 截断保护未知 method返回-32601Method not found。这也解释了文档中「单一/mcp端点处理所有操作」的架构结论路由层根据 JSON-RPC 方法名在服务端内部完成分发客户端无需配置多个端点。为什么选择 HTTP StreamableMCP 官方推荐HTTP Streamable 是 MCP 规范推荐的传输方式性能更优相较 SSE 长连接HTTP POST 请求模型更高效且支持流式响应实现更简单单一 POST 端点即可完成全部交互无需维护独立的消息通道面向未来SSE 在 MCP 规范中已进入弃用状态。补充一点仓库侧的事实依据旧版startFixedHTTPServersrc/http-server.ts已在注释中明确标注 deprecated原因正是「不支持 OpenAI Codex 等客户端所需的 SSE 流式响应」见该文件头部与 src/mcp/index.ts 中对USE_FIXED_HTTPtrue的弃用警告。当前默认的SingleSessionHTTPServer同时支持 Streamable HTTP 与 SSE 两种传输路径这从侧面印证了文档「Streamable 为推荐传输、SSE 为兼容保留」的判断。小结将 n8n-mcp 以 HTTP Streamable 模式接入 n8n 工作流的完整链路为compose 编排两个服务n8n n8n-mcp→ n8n 安装n8n-nodes-mcp社区节点并放行工具调用 → 创建带 Bearer Token 的 MCP API 凭证 → 用 MCP Client 节点以容器网络地址连接并调用工具。排错时抓住三个关键点AUTH_TOKEN一致、N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGEtrue已设置、工作流内使用容器名n8n-mcp而非localhost。整个认证与分发流程均有仓库源码可查可作为你在生产环境实施同类集成时的权威参考。【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考