Claude MCP Tunnels 实战：用 mcp-tunnels 插件与 Docker Compose 将私有网络 MCP 服务器安全接入 Claude

AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载本文是 Claude Code 官方插件目录中mcp-tunnels插件的完整实战指南。它讲解如何借助 Anthropic MCP Tunnel 这一零入站端口方案把运行在你自己私有网络内的 MCP 服务器暴露给 Claude全程只建立出站连接无需开放入站端口、无需公网暴露、无需在源站做 IP 白名单。读完本文你将掌握/create-docker-mcp-tunnel命令的完整工作流预检、建隧道、签发证书、注册 CA、编排代理、启动验证、从 Claude 调用以及令牌轮换、证书续期和常见故障的排查方法。一、MCP Tunnels 是什么以及它解决什么问题MCPModel Context Protocol服务器通常运行在需要被 Claude 调用的位置。如果你的 MCP 服务器位于公司内网、家庭网络或云端私有网络传统做法是开放入站端口、配置公网入口并做 IP 白名单——这既增加攻击面又难以维护。MCP Tunnels提供的是一条相反路径流量经由一条仅出站outbound-only的连接流向 Anthropic 的隧道边缘tunnel edge再由 Claude 侧按主机名路由访问源端不需要任何入站端口。插件 README 开篇即点明其价值mcp-tunnels 的 README 将其描述为通过 Anthropic MCP Tunnel 连接位于私有网络中的 MCP 服务器——无需入站端口、无需公网暴露、无需在源站做 IP 白名单流量只走出站连接。需要特别注意的是该项目在 README 中明确标注为Research preview研究预览按原样提供无可用性uptime或支持承诺且依赖第三方传输提供商Cloudflare。在发送任何敏感数据之前应先阅读其官方安全模型文档。这是你在决定是否将生产流量放入隧道前必须了解的前提。二、插件结构与核心命令该插件遵循本仓库的标准插件布局见根目录 README.md 中描述的commands/ README.md LICENSE结构由以下文件组成文件作用commands/create-docker-mcp-tunnel.md命令本体驱动 MCP Tunnels quickstart 从零到通的 10 步完整流程README.md插件说明命令用法、证书跨机复制、容器栈、需求与适用范围LICENSEApache License 2.0插件通过 Claude Code 的插件市场安装/plugin install mcp-tunnelsclaude-plugins-official后即可使用核心命令/create-docker-mcp-tunnel /create-docker-mcp-tunnel ~/work/my-tunnel命令接受一个可选参数[deployment-dir]部署目录默认值为./mcp-tunnel。它会在你的机器上端到端驱动官方 quickstart 流程使用 Docker Compose 手动提供的凭据manual credentials是本地测试的最短路径。命令文档 create-docker-mcp-tunnel.md 的 frontmatter 显示该命令允许使用的工具包括Bash、Read、Write、Edit与AskUserQuestion——也就是说它既会在本地执行命令也会在需要人工操作控制台Console的环节暂停并询问你。三、你会得到什么一个三容器栈命令文档与 README 都描述了最终构建的容器栈核心是三个容器容器角色mcp-proxyAnthropic 的代理。使用你控制的证书终止内层 TLS 握手校验上游 IP按主机名路由cloudflared隧道代理。仅出站连接到 Anthropic 隧道边缘与代理共享网络命名空间hello-mcp可选FastMCP 示例服务器仅在你还没有自己的 MCP 服务器可暴露时使用当整个栈运行起来后被路由的服务器可以从 Claude 通过https://subdomain.your-tunnel-domain/path访问而宿主机没有任何公网端口在监听。四、前置条件与网络要求开始之前请确认以下条件README 的 Requirements 小节与命令文档 Step 0 均列出了它们Docker 与 Docker Compose必须可用Compose v2 优先若仅有 v1 的docker-compose也可使用compose 文件是 v2 兼容的。OpenSSL 1.1.1 或更新证书生成命令使用了-addext扩展参数该参数仅在 1.1.1 可用。Claude Console 中拥有可管理 MCP tunnels 的角色权限。出站连通性能访问api.anthropic.com:443以及隧道边缘198.41.192.0/19、2606:4700:a0::/44的7844 端口TCP 与 UDP。全程不需要打开任何入站端口。五、分步实操从零到 Claude 调用私有 MCP 服务器以下 10 步完整复刻命令文档 create-docker-mcp-tunnel.md 的流程。下文以$DIR指代部署目录默认为./mcp-tunnel。整个流程是本地命令与只有你能在 Console 完成的操作创建隧道、上传 CA的混合——命令会在每一步给出简要说明、执行命令、检查输出失败时给出明确诊断。Step 0 — 预检Preflight先运行以下命令报告缺失项后再继续docker --version docker compose version openssl versionDocker Docker Compose 是必需的openssl1.1.1 是必需的后续命令使用-addext。确认主机具备到api.anthropic.com:443及隧道边缘198.41.192.0/19、2606:4700:a0::/447844 端口 TCP/UDP 的出站访问。不开任何入站端口。Step 1 — 创建隧道Console用户操作这一步需要你在 Claude Console 中操作侧边栏Manage → MCP tunnels → New tunnel并命名关闭Set up programmatic access——本快速流程使用手动凭据。打开隧道后从Connection区域复制两个值Domain形如abcd1234.tunnel.anthropic.comToken点击眼睛图标后复制重要安全约定不要要求用户把 Token 粘贴进聊天记录。Token 是认证出站隧道连接的秘密必须保持它在对话记录之外。命令会创建$DIR/.env文件由你用户自行把 Token 粘贴进去或者让你在运行 compose 的 shell 中export TUNNEL_TOKENeyJ...。Domain 则记录为TUNNEL_DOMAIN供后续步骤使用。Step 2 — 创建部署目录mkdir -p $DIR/{config,data} cd $DIRStep 3 — 凭据文件.env创建$DIR/.envCompose 会自动加载它与 shell 的export不同它能跨重启存活。命令会自己写入TUNNEL_DOMAIN并为秘密留占位符由用户填写TUNNEL_DOMAINthe domain from step 1 TUNNEL_TOKENPASTE_TUNNEL_TOKEN_HERE然后锁定权限并确保它永远不会被提交chmod 600 $DIR/.env printf .env\ndata/\n $DIR/.gitignore暂停并让用户把PASTE_TUNNEL_TOKEN_HERE替换为真实 Token告知确切文件路径。不打印地验证它已设置cd $DIR grep -q ^TUNNEL_TOKENeyJ .env echo token looks set || echo token NOT set — edit .env在本 shell 中加载它供 openssl/config 步骤使用cd $DIR set -a . ./.env set a echo domain: $TUNNEL_DOMAINStep 4 — 生成 CA 与服务器证书代理终止的是由你控制的 CA 所签发证书的内层 TLS 握手。下面同时生成 CA 与服务器证书Linux/macOS 写法官方 quickstart 还提供 Windows PowerShell 变体——如果用户在 Windows 上可提供该变体cd $DIR openssl req -x509 -newkey rsa:2048 -nodes \ -keyout data/ca.key -out data/ca.crt \ -days 3650 -subj /CNmcp-tunnel-ca \ -addext basicConstraintscritical,CA:TRUE \ -addext keyUsagecritical,keyCertSign,cRLSign \ -addext subjectKeyIdentifierhash cat data/tls.ext EOF subjectAltName DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN} authorityKeyIdentifier keyid,issuer extendedKeyUsage serverAuth EOF openssl req -newkey rsa:2048 -nodes \ -keyout data/tls.key -out /tmp/server.csr \ -subj /CN${TUNNEL_DOMAIN} openssl x509 -req -in /tmp/server.csr \ -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \ -out data/tls.crt -days 90 -extfile data/tls.ext chmod 644 data/tls.key为什么用这些参数理解底层原理显式的-addext扩展让 CA 无论发行版openssl.cnf默认值如何都能满足隧道的证书要求。用-extfile而非-copy_extensions后者仅 OpenSSL 3.0 可用是为了在 OpenSSL 1.1.x 上也能工作并补上代理要求的AuthorityKeyIdentifier。chmod 644 data/tls.key是必须的openssl 会把密钥写成0600但代理容器以非 root 用户运行必须能读到它。data/tls.key与data/ca.key是敏感文件——它们位于data/下已被 Step 3 的.gitignore排除。Step 5 — 注册 CAConsole用户操作在隧道详情页滚动到Certificates → Add certificate上传$DIR/data/ca.crt或粘贴其内容——用cat data/ca.crt打印以便复制。一旦注册了证书隧道状态即翻转为 Active在此之前隧道不会出现在 Agent 选择器中。等待用户确认隧道显示Active再继续。Step 6 — 选择上游 MCP 服务器通过提问让用户二选一我已经有 MCP 服务器获取其可达地址为scheme://host:port形式端口必填不允许带路径——代理在加载配置时若上游值带路径会拒绝。它必须能从代理容器访问且解析到 RFC1918 私有地址10/8、172.16/12、192.168/16代理默认拒绝公网/环回上游SSRF 防护。若它作为 Compose 服务运行则把它加进 compose 文件共享网络若它跑在宿主机上见下文host process排查项。与用户一起选一个路由子域名如wiki。使用示例服务器把下面的 FastMCPhello-server作为 Compose 服务hello-mcp搭建路由子域名为echo。示例服务器源码仅在选择该选项时写入$DIR/hello_server.pyfrom mcp.server.fastmcp import FastMCP mcp FastMCP(hello-server, host0.0.0.0, port9000) mcp.tool() def hello(name: str world) - str: Say hello to someone. return fHello, {name}! if __name__ __main__: mcp.run(transportstreamable-http)Step 7 — 代理配置mcp-proxy.yaml写入$DIR/config/mcp-proxy.yaml。tunnel_domain是必填项代理会从入站主机名中剥离它从而在routes中找到子域名。routes是子域名 → 上游 URL 的扁平映射map不是列表listen_addr: :8080 log_level: info tunnel_domain: TUNNEL_DOMAIN tls: cert_file: /data/tls.crt key_file: /data/tls.key routes: echo: http://hello-mcp:9000替换为真实的TUNNEL_DOMAIN若用户自带服务器则把routes:块替换为所选子域名 → 上游的映射例如wiki: http://wiki-mcp.internal:8080且可以保留多个路由。Step 8 — Compose 编排文件写入$DIR/docker-compose.yaml。镜像按 digest 固定版本digest-pinnedservices: mcp-proxy: image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxysha256:6b9adedbf2763143ec72f106ecaf0ce7fd3294e89b208f54a1db97a33d14c5ba command: [-config, /etc/mcp-proxy/config.yaml] volumes: - ./config/mcp-proxy.yaml:/etc/mcp-proxy/config.yaml:ro - ./data:/data:ro restart: unless-stopped cloudflared: image: cloudflare/cloudflaredsha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0 command: tunnel --no-autoupdate run --url http://localhost:8080 environment: - TUNNEL_TOKEN network_mode: service:mcp-proxy restart: unless-stopped几个必须理解的要点--url http://localhost:8080在手动流程中是必需的因为没有在服务端推送 ingress 规则缺了它 cloudflared 会对每个请求返回 503。network_mode: service:mcp-proxy共享代理的网络命名空间这样localhost:8080才能到达代理。environment: - TUNNEL_TOKEN不带值把变量从.env透传进容器。若选择了示例服务器追加该服务hello-mcp: image: python:3.13-slim working_dir: /app volumes: - ./hello_server.py:/app/hello_server.py:ro command: sh -c pip install --quiet mcp python hello_server.py restart: unless-stopped若用户自带服务器且已容器化也应在此追加其服务使其与代理共享 Compose 网络。对于加固的单主机部署——非 root 用户、只读 rootfs、cap_drop: ALL、no-new-privileges——官方文档另有专门的 Compose 部署指南此 quickstart 保持最小化以加速本地测试。Step 9 — 启动并验证cd $DIR docker compose up -d sleep 5 docker compose logs mcp-proxy | grep -i route configured docker compose logs cloudflared | grep -i Registered tunnel connection预期每个路由出现一行route configured以及四行Registered tunnel connection。容器需要几秒启动如果日志为空请重跑 grep不要在第一次空结果就判定失败。若持续为空进入故障排查章节。Step 10 — 从 Claude 调用命令文档提供了两条路径Managed AgentsConsoleManaged Agents → Sessions→ 新会话 → Agent 选择器Create new agent→ MCP Server→ 选择该隧道 →Subdomain 路由echoPathmcpFastMCPstreamable-http在/mcp提供服务。然后提问Use the hello tool to greet tunnel.——预期看到一次工具调用及其结果。Messages API主机为subdomain.tunnel-domain路径取决于上游提供什么FastMCP 为/mcp。使用创建隧道所在工作区的 API keycurl https://api.anthropic.com/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H anthropic-beta: mcp-client-2025-11-20 \ -d { \model\: \claude-opus-4-7\, \max_tokens\: 1024, \mcp_servers\: [{\type\: \url\, \name\: \echo\, \url\: \https://echo.${TUNNEL_DOMAIN}/mcp\}], \tools\: [{\type\: \mcp_toolset\, \mcp_server_name\: \echo\}], \messages\: [{\role\: \user\, \content\: \call hello with nametunnel\}] }安全边界提醒隧道承载加密流量但不对上游做身份认证。如果上游 MCP 服务器自身需要认证你需要像对待任何其他 MCP 服务器一样自行提供。六、把 CA 证书复制到另一台机器你通常在浏览器中于 Console 注册 CA——而这台机器往往与运行整个栈的机器不同例如隧道跑在远端 homespace而你从笔记本/开发机上上传ca.crt。只有证书deployment-dir/data/ca.crt约 1 KB 的 PEM会离开宿主机——data/ca.key与data/tls.key永远不会。文件很小最简方式就是打印并直接粘贴到 Console 的证书字段cat deployment-dir/data/ca.crt # default: ~/mcp-tunnel/data/ca.crt若要作为文件用scp复制从能 SSH 到另一端的机器上执行scp无法在两台远程机器之间中转。从 homespace 拉取到你的开发机——如果你已运行coder config-ssh主机名为coder.workspacescp coder.workspace:deployment-dir/data/ca.crt . # generic form: scp homespace-ssh-host:~/mcp-tunnel/data/ca.crt .或者若宿主机能到达开发机从宿主机推送过去scp deployment-dir/data/ca.crt userdevbox-host:~/七、故障排查矩阵按此顺序诊断命令文档提供了一张完整的排查表覆盖了手动 quickstart 中最常见的坑。诊断顺序建议先查出站连接 → 再查内层 TLS 握手 → 最后查上游路由。以下为完整矩阵症状原因修复调用方看到 HTTP 500cloudflared 日志No ingress rules were definedcloudflared 没有本地目标确保--url http://localhost:8080与network_mode: service:mcp-proxy都在然后docker compose up -d代理退出cannot unmarshal !!seq into map[string]stringroutes被写成 YAML 列表使用routes: { name: http://host:port }而不是对象列表代理退出open /data/tls.key: permission denied密钥为0600而代理以非 root 运行chmod 644 data/tls.key代理日志no route for host调用方得到502 No route configured for hosttunnel_domain缺失或错误设为隧道详情页上的精确域名然后重启代理见下一行改了配置但毫无变化代理不会热加载config.yaml仅热加载tls.cert_filedocker compose restart mcp-proxy——文件内容变化时up -d不会重建它tls handshake failed ... unknown certificate authority该隧道上 CA 未注册或已吊销在 Console 重新上传data/ca.crtStep 5tls handshake failed ... bad certificate服务器证书 SAN ≠*.tunnel-domain或已过期用正确的TUNNEL_DOMAIN重新生成服务器证书Step 4IP validation failed: ip is not a private address上游解析到 RFC1918 之外如127.0.0.1、公网 IP把上游作为 Compose 服务运行在代理网络上或刻意收窄upstream.allowed_ips本地测试之外避免0.0.0.0/0dial tcp ...: connect: connection refused针对host.docker.internalrootless Docker 无法到达宿主网络命名空间把 MCP 服务器作为 Compose 服务运行而非宿主机进程HTTP 502代理日志无request startedcloudflared 尚未完成注册或正在滚动更新等待 ×4Registered tunnel connection后重试隧道在 Agent 的 MCP Server选择器中缺失没有有效证书或工作区不对注册 CA 证书Step 5在隧道所在工作区打开会话curl https://proxy:8080失败wrong version number预期行为——监听器是明文 WSTLS 在 WS 流内部不要直接 curl 代理通过 Managed Agent 或 Messages API 验证两条首要诊断命令是docker compose logs cloudflaredToken / 边缘可达性与docker compose logs mcp-proxy配置 / 证书 / 路由。官方文档另有更多案例。八、运维要点令牌轮换与证书续期命令文档明确提醒这些操作只需简要提及不要未经请求就执行。令牌轮换Token rotationConsole 中Rotate token会立即令旧令牌失效。更新.env中的TUNNEL_TOKEN后执行docker compose up -d cloudflared。证书续期Cert renewal服务器证书有效期 90 天。用同一个 CA 重新签名已注册的 CA 不变并替换data/tls.crt代理会轮询并热加载它无需重启。配置变更始终需要docker compose restart mcp-proxy。九、适用范围与更进一步的部署本插件定位的是手动凭据、单主机、本地测试这条路径。如果你需要以下能力README 明确指向官方部署指南加固的单主机部署非 root、只读 rootfs、dropped capabilitiesKubernetes 部署官方提供 Helm 部署指南程序化访问通过 Workload Identity Federation 以编程方式获取凭据替代手动复制 Token。也就是说mcp-tunnels 插件是通往官方 MCP Tunnels 能力的便捷入口它把最繁琐的本地验证路径自动化但生产级部署仍应参考官方提供的 Compose/Helm 硬化方案。十、总结与文件指引通过本插件你可以在十几分钟内完成一次私有网络 MCP 服务器 → Anthropic 隧道 → Claude 调用的完整闭环全程无入站端口。涉及的关键仓库文件插件说明与命令用法plugins/mcp-tunnels/README.md10 步完整流程、证书命令、Compose 配置与排查矩阵plugins/mcp-tunnels/commands/create-docker-mcp-tunnel.md许可证plugins/mcp-tunnels/LICENSE最后再次强调安全底线Token 是.envchmod 600、已 gitignore中的活体密钥本方案处于研究预览阶段、面向本地测试承载敏感或生产流量前务必先阅读官方安全模型。赞分享AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐Claude Code 接入 Asana V2 MCP 服务器OAuth 应用创建与 claude mcp add 连接配置实战Claude Code 接入 Asana V2 MCP 服务器OAuth 应用创建与 claude mcp add 连接配置实战 本指南围绕本仓库 exterAI 插件开发工具插件系统连接真实 Host用 python-sdk 的 mcp run 命令将 MCP 服务器接入 Claude Desktop、Claude Code、Cursor 与 VS Code连接真实 Host用 python sdk 的 mcp run 命令将 MCP 服务器接入 Claude Desktop、Claude Code、Cursor人工智能MCP 服务MCP Clients连接真实 Host用 python-sdk 将 MCP 服务器接入 Claude Desktop、Claude Code、Cursor 与 VS Code连接真实 Host用 python sdk 将 MCP 服务器接入 Claude Desktop、Claude Code、Cursor 与 VS Code 本人工智能MCP 服务MCP Clients创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考