AI导哈

协议桥接工具

MCP Bridge是一个通用的传输桥接工具，用于在基于stdio的MCP客户端和远程HTTP/SSE服务器之间建立连接。

  • by geosp
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 geosp/mcp_bridge

使用说明

MCP桥

适用于模型上下文协议（MCP）的通用传输桥接器——通过HTTP/SSE将基于stdio的MCP客户端连接到远程服务器。

什么是MCP桥？

MCP Bridge 解决了一个常见的集成难题： MCP客户端（如Claude Desktop）期望建立stdio连接，但许多MCP服务器通过HTTP/SSE进行远程运行这座桥位于中间，能够无缝地在这几种协议之间进行转换。

graph LR
    A[Claude Desktop/MCP Client] <-->|stdio| B[MCP Bridge]
    B <-->|HTTP/SSE| C[Remote MCP Server]

用例

  • 将Claude Desktop连接到远程/容器化MCP服务器
  • 从本地客户端访问云托管的MCP服务
  • 连接到认证后的MCP服务器桥接
  • 使任何基于stdio的MCP客户端能够使用HTTP/SSE服务器

安装

使用 pip（推荐）

pip install mcp-bridge

使用紫外线

pip install uv
uv pip install mcp-bridge

来自源头

git clone https://github.com/geosp/mcp-bridge.git
cd mcp-bridge
uv pip install -e .

安装后，验证其是否正常工作：

mcp-bridge --version

快速入门

1. 初始化配置

创建你的第一个配置文件：

mcp-bridge init

这产生了 ~/.config/mcp-bridge/config.json 附带一个示例配置。

2. 编辑配置

使用您的服务器详细信息编辑配置文件：

# macOS/Linux
vi ~/.config/mcp-bridge/config.json

# Or use your preferred editor
code ~/.config/mcp-bridge/config.json

配置格式：

{
  "url": "http://your-mcp-server.example.com/mcp-endpoint",
  "headers": {
    "Authorization": "Bearer your-token-here"
  }
}

配置选项：

  • url （必填）：您远程MCP服务器的HTTP/SSE端点
  • headers （可选）：在请求中包含的HTTP头部（例如，身份验证令牌）

3. 测试桥梁

使用一个简单的初始化请求来测试您的配置：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | mcp-bridge

你应该会从服务器收到一个JSON格式的响应。

多服务器配置

你可以使用命名配置来设置多个服务器：

# Create configs for different servers
mcp-bridge init --name weather
mcp-bridge init --name database
mcp-bridge init --name analytics

# List all configs
mcp-bridge list-configs

# Use a specific config
mcp-bridge --config weather.json

与Claude桌面版的使用

单服务器设置

  1. 首先，创建并配置您的桥接配置：
mcp-bridge init
# Edit ~/.config/mcp-bridge/config.json with your server details
  1. 将此添加到您的Claude桌面配置文件中：

macOS（苹果电脑操作系统）: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "remote-server": {
      "command": "mcp-bridge",
      "args": []
    }
  }
}
  1. 重启Claude桌面版

多服务器设置

对于多个远程服务器：

  1. 为每台服务器创建命名配置：
mcp-bridge init --name weather
mcp-bridge init --name database
# Edit each config file with appropriate server details
  1. 更新Claude桌面配置：
{
  "mcpServers": {
    "weather-server": {
      "command": "mcp-bridge",
      "args": ["--config", "weather.json"]
    },
    "database-server": {
      "command": "mcp-bridge",
      "args": ["--config", "database.json"]
    }
  }
}
  1. 重启Claude桌面版

每个桥接实例将独立地与其配置的远程服务器建立连接。

它是如何运作的

  1. 标准I/O接口监听来自 Claude Desktop 的 JSON-RPC 消息，通过标准输入流（stdin）接收
  2. HTTP 翻译通过HTTP POST将请求转发到远程MCP服务器
  3. SSE 流媒体从HTTP连接中读取服务器发送的事件响应
  4. 会话管理在请求之间保持会话ID
  5. 响应转发将响应写回客户端的标准输出

已知问题及解决方法

Claude 桌面端参数序列化漏洞

问题在调用MCP工具时，Claude Desktop错误地序列化了复杂对象参数。对象和数组参数被转换为JSON字符串，而不是在发送给MCP服务器的JSON-RPC有效载荷中保留为对象。

错误示例:

// Expected by MCP servers:
{"arguments": {"filter": {"lastName": "Fajardo"}}}

// Actual from Claude Desktop:
{"arguments": {"filter": "{\"lastName\": \"Fajardo\"}"}}

影响：

  • MCP服务器以“输入验证错误”拒绝这些调用
  • 任何带有对象或数组参数的MCP工具都无法正常工作
  • 影响工具，如数据库过滤器、复杂配置、嵌套数据结构

MCP桥接解决方案（或：MCP桥接变通方法）： 这座桥 自动检测并修复 在将请求转发到您的MCP服务器之前，将参数转换为字符串。解决方法：

  1. 检测参数值是否为JSON字符串而非对象/数组
  2. 安全地将它们反序列化回正确的类型
  3. 将修正后的参数转发到您的MCP服务器
  4. 在进行更正时记录日志（可在标准错误日志中查看）

这对您来说意味着什么：

  • ✅ 您的带有对象/数组参数的MCP工具将正常工作
  • ✅ 无需对您的MCP服务器代码进行任何更改
  • ✅ 自动且透明 - 无需配置
  • ✅ 安全 - 无效的JSON字符串将保持原样

示例日志输出：

[Bridge] Fixed stringified params: filter:dict, tags:list
[Bridge] Sending: tools/call (id=123)

状态：

  • ✅ 已实施并测试了解决方案（截至v0.2.0版本）
  • ✅ 已确认可与Claude Desktop的字符串化参数一起工作
  • Claude 桌面版存在漏洞（报告待提交给Anthropic）
  • 这个临时解决方案将持续到Claude Desktop修复为止
  • 这个临时解决方案是安全的，并且在问题解决后不会引起任何问题

技术细节反序列化逻辑在 bridge.py:16-63 并应用于 send_message() 在将请求转发到HTTP服务器之前，先使用该方法。

建筑学

flowchart TD
    A["Claude Desktop<br/>(MCP Client)"]
    B["MCP Bridge<br/>• Read stdin<br/>• HTTP client<br/>• SSE parser<br/>• Write stdout"]
    C["Remote MCP<br/>Server"]

    A <-->|"stdio<br/>(JSON-RPC)"| B
    B <-->|HTTP/SSE| C

    style A fill:#4a9eff,color:#000
    style B fill:#ffb347,color:#000
    style C fill:#66bb6a,color:#000

示例配置

查看 examples/ 样本配置目录：

  • examples/local-server.json - 连接到本地MCP服务器
  • examples/authenticated-server.json - 使用承载令牌认证的服务器
  • examples/claude-desktop-config.json - Claude Desktop 配置

故障排除

桥未连接

  • 检查一下 config.json 存在且具有有效的JSON
  • 验证 url 可以从您的机器访问
  • 检查标准错误输出(stderr)的日志以查找错误信息

认证失败

  • 确保您的 Authorization 头部令牌有效
  • 检查令牌是否已过期
  • 验证令牌格式是否符合服务器预期

Claude Desktop 无法找到桥接器

  • 验证 mcp-bridge 在你的PATH环境变量中： which mcp-bridge
  • 如果使用虚拟环境，请使用完整路径：
    {
  "mcpServers": {
    "remote-server": {
      "command": "/full/path/to/mcp-bridge",
      "args": []
    }
  }
}
  • 检查Claude Desktop的日志以查找错误信息

未找到配置文件

# Check what configs exist
mcp-bridge list-configs

# Create a new config if needed
mcp-bridge init

启用调试日志记录

该桥接器将日志记录到标准错误输出。Claude Desktop 会捕获这些日志。您也可以手动进行测试：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | mcp-bridge 2> bridge.log

CLI 命令

# Show version
mcp-bridge --version

# Initialize a new config
mcp-bridge init
mcp-bridge init --name myserver

# List all configs
mcp-bridge list-configs

# Run with default config
mcp-bridge

# Run with specific config
mcp-bridge --config weather.json

未来的改进/增强功能

  • [ ] WebSocket传输支持
  • [x] 多个服务器配置（在v0.2.0中完成）
  • [ ] 请求/响应日志记录选项
  • [ ] 重试逻辑和连接池
  • [ ] 健康检查端点
  • [ ] TLS/SSL 证书配置

贡献

欢迎投稿！请参阅 `CONTRIBUTING.md` 翻译成中文是“贡献指南文件（Markdown格式）”。这个文件通常用于说明如何向项目贡献代码或内容，包括贡献的流程、规范、要求等信息 作为指南。

许可证

MIT 许可证 - 请参阅 许可证 详情请查阅文件。

相关项目

支持

相关 MCP