Claude Bridge MCP：通过MCP协议远程调用Claude Code CLI的完整指南

1. 项目概述Claude Bridge MCP一个让Claude Code订阅随处可用的桥梁如果你和我一样是Claude Code的重度用户每个月花着100刀MAX或200刀PRO的订阅费但同时又对AI Agent生态里的各种新工具比如OpenClaw垂涎欲滴那你肯定遇到过这个核心痛点你的Claude Code订阅被牢牢锁在了本地命令行里而新兴的、功能强大的MCP客户端却无法直接调用它。这感觉就像你有一台顶级跑车的发动机却只能装在自行车上骑。claude-bridge-mcp这个项目就是为了解决这个“发动机与车架不匹配”的问题而生的。简单来说它是一个MCP服务器能把你在本地电脑上运行的Claude Code CLI命令行界面通过HTTP和SSEServer-Sent Events协议暴露出来。这样一来任何支持MCP协议的客户端——无论是OpenClaw这样的开源Agent框架还是Claude Desktop应用甚至是自己写的自动化脚本——都能通过网络远程调用你本地的Claude Code能力。它的核心价值在于订阅复用与能力扩展。你不再需要为每个想用Claude Code的环境单独付费或寻找替代品。你的一个高级订阅通过这个“桥梁”就能赋能你所有的AI工作流。这对于需要在多台机器比如家里的主力机、公司的办公机、云上的开发服务器上工作或者希望将Claude Code的强大代码能力集成到自定义自动化流程中的开发者来说是一个游戏规则的改变者。2. 核心原理与架构设计拆解要理解这个桥接器为什么有效以及如何安全地使用它我们需要先拆解几个关键概念MCP、Claude Code CLI的工作方式以及桥接器自身的设计哲学。2.1 MCPAI工具的“通用插座”Model Context Protocol简称MCP你可以把它想象成AI世界的“USB-C”接口标准。在MCP出现之前每个AI应用比如Claude Desktop、Cursor想要接入外部工具如文件系统、数据库、搜索引擎都需要开发者为其编写特定的插件或适配器这导致了大量的重复劳动和生态割裂。MCP定义了一套标准的通信协议让AI客户端如Claude Desktop和工具服务器如一个提供文件读写能力的服务可以相互发现和调用。claude-bridge-mcp扮演的角色正是一个“工具服务器”。它遵循MCP标准对外宣称“我这里提供了claude_execute、claude_query等工具。” 当远程的OpenClaw Agent需要写一段代码时它就会通过MCP协议向这个桥接器发送一个claude_execute的调用请求。2.2 Claude Code CLI能力之源桥接器本身并不包含AI模型它只是一个“翻译官”和“调度员”。真正的算力和智能来自于你本地安装并认证好的claude命令行工具。当你运行claude命令时它会调用Anthropic的API并使用你账户绑定的Claude Code订阅额度。桥接器的工作流程是这样的收到远程MCP客户端的工具调用请求例如“请帮我修复这个文件的语法错误”。将这个请求“翻译”成claudeCLI能够理解的命令和参数。在你的本地系统上启动一个新的claude命令行进程并将翻译好的指令喂给它。捕获claude进程的输出包括流式的token输出再通过MCP协议和网络实时地传回给远程的客户端。这个过程实现了能力的“远程投射”。你的本地电脑成为了一个Claude Code能力的“主机”而其他设备则成为了可以随时接入的“终端”。2.3 桥接器的核心架构安全与效率的平衡作为一个需要处理远程请求、执行本地命令的服务桥接器的设计在安全性和资源管理上做了很多考量这也是它比简单写一个脚本转发请求要复杂和可靠得多的地方。执行队列与并发控制这是防止你的电脑被“打爆”的关键设计。想象一下如果多个远程请求同时到达每个都启动一个耗时的claude进程你的CPU和内存可能瞬间就不够用了。桥接器内部维护了一个FIFO先进先出队列并通过BRIDGE_MAX_CONCURRENT环境变量默认2严格控制同时运行的claude进程数量。超出的请求会在队列中等待如果等待时间超过BRIDGE_QUEUE_TIMEOUT默认30秒则会被拒绝。这保证了服务的稳定性。请求处理与流式响应MCP协议支持Server-Sent Events这是一种允许服务器向客户端主动推送数据的技术。这对于AI生成这种“边想边输出”的场景至关重要。桥接器在调用claudeCLI时会实时读取其标准输出并将每一块新生成的内容立即通过SSE通道推送给客户端。这样你在OpenClaw里就能看到代码像在本地终端里一样一个字一个字地“流”出来体验非常顺畅。网络通信层桥接器使用HTTP服务器来提供/sse和/messages端点。MCP客户端通过HTTP连接到/sse建立一个持久的、单向的服务器到客户端的数据流。而具体的工具调用请求JSON-RPC格式则通过向/messages端点发送POST请求来完成。这种设计分离了事件流和控制流是MCP协议的标准实现方式。3. 从零开始的详细部署与配置指南理解了原理我们来动手把它搭起来。整个过程可以分为三步环境准备、桥接器部署、客户端连接。我会以macOS/Linux环境为例Windows用户操作逻辑类似注意路径的差异即可。3.1 环境准备打好地基第一步安装Node.js和npm桥接器是Node.js应用所以这是必需品。建议安装Node.js 18或更高版本以获得最佳兼容性。# 在macOS上使用Homebrew安装是最简单的方式 brew install node # 在Ubuntu/Debian上 curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt-get install -y nodejs # 安装完成后验证版本 node --version # 应显示 v18.x 或更高 npm --version第二步安装并认证Claude Code CLI这是整个项目的“心脏”。你需要一个有效的Claude CodeMAX或PRO订阅。访问 Anthropic 官方文档的 Claude Code 安装指南。根据你的操作系统按照指引安装claude命令行工具。通常也是一条npm命令。安装完成后在终端中首次运行claude。它会自动打开浏览器引导你完成登录和授权流程。请确保你登录的是拥有Claude Code订阅的账户。授权成功后在终端里简单问个问题测试一下例如claude hello确认它能正常返回响应。注意Claude Code CLI的认证信息通常保存在本地如~/.config/claude目录下。桥接器进程会继承运行它的用户的权限和环境因此只要能以你的用户身份运行claude命令它就能使用你的订阅。第三步规划网络与安全这是部署中最关键的一步决定了谁可以访问你的桥接器。仅本地使用如果你只想在同一台电脑上让Claude Desktop等本地MCP客户端调用桥接器那么最简单几乎无需额外配置使用localhost即可。跨设备远程使用如果你想从办公室电脑访问家里的桥接器或者从云服务器访问本地的桥接器就必须考虑网络安全。强烈不建议直接将桥接器暴露在公网IP上。作者推荐使用Tailscale这是一个基于WireGuard的零配置组网工具能在你的所有设备间建立一个加密的虚拟局域网就像它们都在同一个安全的家庭路由器后面一样。去Tailscale官网注册并在你的“主机”运行桥接器的电脑和“客户端”想远程连接的电脑上都安装Tailscale客户端并登录同一账户。在主机上运行tailscale ip -4获取你的Tailscale内网IP通常是100.x.x.x格式。后续连接就使用这个IP。3.2 部署与运行桥接器有了基础环境安装桥接器本身非常简单。# 方法一直接使用npx运行无需安装适合尝鲜 npx claude-bridge-mcp # 方法二全局安装适合长期使用 npm install -g claude-bridge-mcp claude-bridge-mcp运行后你会看到类似下面的输出说明服务已经启动在0.0.0.0:3100Server running on http://0.0.0.0:3100打开另一个终端测试健康检查接口curl http://localhost:3100/health如果返回{status:ok}说明服务运行正常。3.3 深度配置打造坚固的堡垒默认配置是开放的适合本地测试。但用于远程连接前必须通过环境变量进行加固。我强烈建议创建一个.env文件来管理配置。创建配置文件# 进入桥接器项目目录如果是全局安装可以在任意位置创建 # 假设我们专门创建一个目录来管理 mkdir ~/claude-bridge cd ~/claude-bridge # 将示例配置文件复制过来 # 你需要先找到示例文件的位置对于全局安装可能需要从npm全局目录找或者直接从项目仓库下载 # 更简单的方式直接新建一个 .env 文件并填入以下内容编辑.env文件下面是一个结合了安全性和实用性的配置示例# .env 文件内容 BRIDGE_HOST0.0.0.0 BRIDGE_PORT3100 # 1. 设置一个强壮的API令牌这是第一道锁 BRIDGE_API_TOKENyour_super_strong_secret_token_here_change_me # 2. IP白名单只允许你的远程设备连接。如果你用了Tailscale这里填你远程设备的Tailscale IP。 # 你可以设置多个IP用逗号分隔例如BRIDGE_ALLOWED_IPS100.101.102.103,100.104.105.106 BRIDGE_ALLOWED_IPS100.101.102.103 # 3. 目录白名单限制Claude可以访问的文件路径。这是防止越权访问的关键。 # 只允许访问你的项目目录用逗号分隔多个路径。 BRIDGE_ALLOWED_DIRS/Users/yourname/Projects,/Users/yourname/Documents/code # 4. 执行超时防止单个任务运行过久 BRIDGE_TIMEOUT300000 # 5分钟 # 5. 并发控制根据你的电脑性能调整默认2比较稳妥 BRIDGE_MAX_CONCURRENT2 BRIDGE_QUEUE_TIMEOUT60000 # 队列等待超时1分钟实操心得关于目录白名单的路径解析BRIDGE_ALLOWED_DIRS的检查是基于解析后的真实路径realpath。这意味着如果你设置/home/user/project那么访问/home/user/project/../other会被拒绝因为realpath解析后是/home/user/other不在白名单内。同样符号链接symlink也会被解析到其指向的真实路径后再进行判断。这有效防止了路径遍历攻击。使用配置文件启动 在启动命令前指定环境变量文件。如果你使用npm install -g安装的可以这样运行env $(grep -v ^# .env | xargs) claude-bridge-mcp或者更清晰的方式是写一个启动脚本start_bridge.sh#!/bin/bash cd /path/to/your/claude-bridge-directory export $(grep -v ^# .env | xargs) claude-bridge-mcp然后给脚本执行权限chmod x start_bridge.sh以后每次启动就运行./start_bridge.sh。3.4 客户端连接配置服务端配置好后我们需要在MCP客户端如OpenClaw或Claude Desktop中配置连接。连接OpenClawOpenClaw的配置通常位于~/.openclaw/openclaw.json。你需要添加一个新的MCP服务器配置。{ mcpServers: { claude-bridge: { command: npx, args: [ -y, mcp-remote, http://100.101.102.103:3100/sse ], env: { MCP_REMOTE_TOKEN: your_super_strong_secret_token_here_change_me } } } }关键解释command: npx和args: [-y, mcp-remote, ...]这是告诉OpenClaw不要直接启动一个本地命令而是使用mcp-remote这个工具去连接一个远程的SSE端点。npx -y确保会自动安装所需的mcp-remote包。http://100.101.102.103:3100/sse将这里的IP替换成你运行桥接器的主机IP如果是Tailscale就是Tailscale IP。MCP_REMOTE_TOKEN这个环境变量对应我们之前在服务端设置的BRIDGE_API_TOKEN。mcp-remote工具会使用这个Token来构建请求头Authorization: Bearer token。这是身份验证的关键一步。连接Claude DesktopClaude Desktop的MCP配置文件路径因系统而异macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json在配置文件中添加的段落与OpenClaw类似{ mcpServers: { claude-bridge: { command: npx, args: [ -y, mcp-remote, http://100.101.102.103:3100/sse ], env: { MCP_REMOTE_TOKEN: your_super_strong_secret_token_here_change_me } } } }保存配置文件后需要完全重启Claude Desktop应用新的MCP服务器配置才会被加载。配置完成后在你的客户端如OpenClaw中你应该能看到新可用的工具。例如在OpenClaw的对话中你可以尝试让Agent使用claude_query工具来分析一段代码。4. 核心工具详解与实战应用场景桥接器暴露了四个核心工具它们对应着Claude Code CLI最常用和强大的功能。理解每个工具的用途和最佳实践场景能让你更好地利用这座“桥梁”。4.1claude_execute全能代码执行引擎这是最强大、最常用的工具。你可以把它理解为将整个Claude Code的交互式会话通过一个指令来驱动。工作原理当你调用claude_execute并提供一个任务描述如“在项目根目录下创建一个新的React组件Button.jsx”时桥接器会在后台启动一个claude进程并将这个任务描述传递给它。Claude Code会像在本地终端中一样分析上下文通过claude_read_file等工具获取然后生成执行计划读写文件、运行命令等并逐一执行。参数与使用 调用时你主要需要提供task参数即清晰的任务描述。越具体、上下文越丰富效果越好。// 一个假设的MCP工具调用请求结构 { tool: claude_execute, args: { task: 请检查当前目录下的app.js文件修复其中的语法错误并优化其性能。 } }实战场景举例自动化代码重构你可以让OpenClaw Agent定期扫描项目使用claude_execute对指定文件或目录进行代码风格统一和优化。复杂项目初始化“请在当前目录下基于Next.js 14和Tailwind CSS搭建一个博客项目的基本结构包含首页、文章页和导航组件。”交互式调试虽然是一次性任务描述但你可以通过连续调用模拟对话。例如先让Claude执行“运行测试并找出失败原因”再根据结果执行“修复第X行提到的类型错误”。注意事项执行边界与安全claude_execute的能力非常强大几乎等同于你本人在终端里操作。因此BRIDGE_ALLOWED_DIRS的配置至关重要。务必将其限制在必要的项目目录内避免Claude意外修改或删除系统关键文件。此外Claude Code本身有安全策略不会执行明显危险的命令如rm -rf /但双重限制MCP目录白名单 Claude自身安全机制能提供更稳妥的保障。4.2claude_query快速的只读分析专家这个工具用于向Claude Code提问但它是“只读”模式。它不会修改任何文件也不会执行任何命令仅仅是对提供的代码或问题进行思考和分析。工作原理claude_query同样启动一个Claude进程但它只传递问题和上下文通常是文件内容并请求一个回答。整个过程不涉及文件系统操作因此速度通常比claude_execute更快。参数与使用 主要参数是query你的问题和可选的context相关代码或文本。{ tool: claude_query, args: { query: 请解释下面这段Python代码中装饰器的作用和工作原理。, context: retry(stopstop_after_attempt(3))\ndef fetch_data(url):\n response requests.get(url)\n response.raise_for_status()\n return response.json() } }实战场景举例代码审查将新写的代码片段或Pull Request中的变更提交给claude_query让它从代码风格、潜在bug、性能问题、安全漏洞等角度进行分析。学习与理解遇到一段复杂的开源库代码可以直接让Claude逐行解释其逻辑和设计模式。技术方案咨询描述你遇到的技术难题和现有代码结构让Claude提供几种可能的解决方案并分析利弊。4.3claude_read_file与claude_git_status上下文提供者这两个工具通常不是被最终用户直接调用而是作为claude_execute和claude_query的“眼睛”为Claude Code提供执行任务或回答问题所需的上下文。claude_read_file读取指定路径的文件内容。Claude Code在执行任务前可能会自动调用此工具来了解当前文件的状态。claude_git_status获取当前工作目录的Git状态信息包括分支名、暂存区变更、未跟踪文件等。这对于需要理解项目版本历史的操作如基于最新分支进行开发至关重要。配置联动claude_read_file的读取范围同样受到BRIDGE_ALLOWED_DIRS的严格限制。这意味着即使Claude想读取一个白名单之外的文件来获取上下文也会被桥接器拒绝从而保证了文件的隐私性。5. 高级部署模式与性能调优当你熟悉了基础部署后可以考虑一些更高级、更稳定的运行方式以适应不同的使用场景。5.1 使用PM2进行进程守护在开发机上如果你希望桥接器能像系统服务一样在后台稳定运行即使终端关闭也不会停止PM2是一个绝佳选择。它是一个强大的Node.js进程管理器。# 1. 全局安装PM2 npm install -g pm2 # 2. 使用PM2启动桥接器并注入.env文件中的环境变量 # 假设你的启动脚本是 start_bridge.sh pm2 start start_bridge.sh --name claude-bridge # 或者直接使用pm2的生态系统配置文件更规范 # 创建 ecosystem.config.js module.exports { apps: [{ name: claude-bridge, script: claude-bridge-mcp, // 如果是全局安装 // 如果是从项目目录运行可能是script: index.js, interpreter: none, // 如果script是全局命令 env: { NODE_ENV: production, BRIDGE_API_TOKEN: your_token, BRIDGE_ALLOWED_IPS: 100.101.102.103, BRIDGE_ALLOWED_DIRS: /path/to/projects, // ... 其他环境变量 }, log_date_format: YYYY-MM-DD HH:mm:ss, error_file: ~/.pm2/logs/claude-bridge-error.log, out_file: ~/.pm2/logs/claude-bridge-out.log }] };然后使用pm2 start ecosystem.config.js启动。PM2提供了监控、日志、开机自启等一系列强大功能。5.2 在云服务器VPS上部署你可以将桥接器部署在24小时运行的云服务器上这样你就拥有了一个“永远在线”的Claude Code服务端。步骤与本地类似但需注意服务器选择选择一家云服务商如AWS Lightsail, DigitalOcean Droplet, Linode创建一个最基础的Linux虚拟机如Ubuntu 22.04 LTS。1核1GB内存的配置通常就足够因为计算负载实际在你的本地Claude Code上服务器只做转发。安全组/防火墙在云平台控制台务必严格配置防火墙。只开放Tailscale所需的端口通常是UDP 41641以及你可能用于管理的SSH端口22。绝对不要将3100端口暴露给公网0.0.0.0/0。所有访问都应通过Tailscale虚拟网络进行。在服务器上安装# 安装Node.js, Claude CLI # 配置Tailscale tailscale up # 安装并配置 claude-bridge-mcp npm install -g claude-bridge-mcp # 创建 .env 文件BRIDGE_ALLOWED_IPS 设置为你的本地电脑的Tailscale IP # 使用PM2守护进程连接方式此时你的本地电脑和云服务器都在同一个Tailscale网络里。你本地OpenClaw的配置中服务器地址就应该是云服务器的Tailscale IP如http://100.xx.xx.xx:3100/sse。5.3 性能调优参数解析桥接器的几个环境变量直接影响了其并发处理能力和稳定性需要根据实际使用场景调整。环境变量默认值调优建议与场景BRIDGE_MAX_CONCURRENT2这是同时执行的claude进程数上限。这是最重要的参数。调高可以处理更多并发请求但会显著增加CPU/内存负载。建议值•轻量使用1-2。•团队或个人多任务根据CPU核心数设置为2-4。•注意Claude Code订阅本身可能有并发限制设置过高可能导致API调用失败。BRIDGE_QUEUE_TIMEOUT30000 (30秒)请求在队列中等待的最长时间。如果所有执行槽都被占用新请求会排队超过这个时间则被拒绝。对于交互式应用30秒尚可。如果预期有长时间任务可以适当增加如1200002分钟。BRIDGE_TIMEOUT120000 (2分钟)单个claude任务执行的最长时间。对于简单的代码生成或问答2分钟足够。但对于复杂的重构、大型文件分析可能需要增加。建议设置为3000005分钟或更长具体取决于你的任务类型。超时的任务会被强制终止。BRIDGE_ALLOWED_DIRS空当前目录这不仅关乎安全也影响性能。如果允许的目录范围非常大Claude在尝试理解上下文时可能会扫描更多文件。将其精确限制在项目目录能减少不必要的文件系统访问让响应更聚焦、更快速。监控与日志定期检查桥接器的日志如果用了PM2用pm2 logs claude-bridge和/metrics端点curl http://localhost:3100/metrics可以了解请求量、队列长度、执行时间等信息为调优提供数据支持。6. 故障排查与常见问题实录在实际部署和使用过程中你难免会遇到一些问题。下面是我在搭建和使用过程中遇到的一些典型情况及其解决方法希望能帮你快速排雷。6.1 连接类问题问题客户端无法连接提示“Connection refused”或超时。检查1服务是否在运行# 在运行桥接器的主机上执行 curl http://localhost:3100/health如果失败说明桥接器进程可能没启动或崩溃了。检查启动命令和日志。检查2防火墙是否阻止了端口在主机上检查3100端口是否在监听并且监听地址是否正确0.0.0.0表示监听所有网络接口。# Linux/macOS sudo lsof -i :3100 # 或 netstat -an | grep 3100如果只看到127.0.0.1:3100说明只监听本地回环远程无法访问。确保启动时BRIDGE_HOST0.0.0.0。检查3IP白名单是否配置正确确认客户端机器的IP地址是否包含在BRIDGE_ALLOWED_IPS中。如果使用了Tailscale务必使用tailscale ip -4在客户端机器上查到的IP而不是公网IP或本地局域网IP。检查4Tailscale网络是否通畅在客户端机器上ping一下主机的Tailscale IP。ping 100.101.102.103如果不通检查两台机器的Tailscale客户端状态tailscale status确保它们都显示为“Connected”。问题连接成功但调用工具时提示“Unauthorized”或认证失败。检查1API令牌是否匹配确保服务端.env文件中的BRIDGE_API_TOKEN和客户端配置如OpenClaw的MCP_REMOTE_TOKEN环境变量的值完全一致包括大小写和任何特殊字符。一个常见的错误是复制粘贴时多了空格或换行符。检查2令牌是否包含特殊字符如果令牌中包含$,#,等shell特殊字符在.env文件中可能需要用引号括起来或者在启动脚本中做转义处理。6.2 工具执行类问题问题claude_execute执行失败提示“Claude CLI error”或没有权限。检查1Claude CLI是否已正确安装和登录在主机上直接运行claude hello看是否能正常返回。确保运行桥接器的用户和手动测试claude命令的用户是同一个并且该用户有权限执行claude。检查2目录白名单是否包含目标路径当Claude尝试读取或写入一个文件时如果该文件的真实路径经过realpath解析后不在BRIDGE_ALLOWED_DIRS列表中操作会被拒绝。仔细检查错误信息中提及的路径并将其父目录添加到白名单中。检查3是否达到并发上限如果BRIDGE_MAX_CONCURRENT设置得较低而同时有多个请求新的请求可能会因为队列超时BRIDGE_QUEUE_TIMEOUT而被拒绝。查看桥接器日志或/metrics端点确认当前活跃执行数和队列长度。问题工具调用响应非常慢或者流式输出中断。检查1网络延迟。如果客户端和服务器之间的网络延迟很高比如跨国连接SSE流可能会受到影响。尽量让两者处于地理位置相近的网络或使用低延迟的组网工具如Tailscale通常能建立P2P直连延迟较低。检查2任务本身过于复杂。一个非常庞大的代码生成或重构任务Claude Code本身就需要很长时间思考。可以尝试将大任务拆分成多个小任务通过多次claude_execute调用来完成。检查3服务器资源不足。登录主机查看CPU和内存使用情况。如果claude进程占用了大量资源可能导致响应变慢。考虑升级主机配置或降低BRIDGE_MAX_CONCURRENT。6.3 环境与配置问题问题在Docker容器中运行桥接器无法调用宿主机的claude命令。这是一个典型的环境隔离问题。Docker容器默认有自己独立的文件系统和进程空间。解决方案需要将宿主机的claude命令及其可能依赖的配置、缓存目录挂载到容器内并以相同用户身份运行。# Dockerfile 示例 (不完整仅展示思路) FROM node:18-alpine # 安装claude CLI在容器内不更好的方式是挂载。 # 或者运行一个特权容器共享宿主机的网络和文件系统不安全不推荐。更简单且推荐的做法是不要在Docker中运行需要调用本地CLI的桥接器。直接在宿主机上使用PM2等工具守护进程管理起来更简单性能也更好。问题如何更新claude-bridge-mcp到最新版本# 如果是全局安装 npm update -g claude-bridge-mcp # 如果是通过npx运行每次运行都会自动获取最新版本如果有。 # 如果是克隆仓库本地运行 cd /path/to/claude-bridge-mcp git pull origin main npm install npm run build # 如果需要更新后记得重启桥接器进程如pm2 restart claude-bridge。经过以上从原理到实践从部署到调优的完整梳理你应该已经能够驾驭claude-bridge-mcp这个强大的工具了。它的本质是一种“能力解耦”和“资源复用”的思想将昂贵的、绑定的Claude Code订阅通过标准化协议MCP和安全的网络隧道变成了一个可被多种AI前端共享的通用后端服务。这种模式在未来AI工具深度集成的工作流中可能会变得越来越常见。