AI导哈

MCP协议代理工具

一个用于桥接基于stdio的MCP客户端和可流式HTTP MCP服务器的代理工具，实现协议透明转换。

  • by lattenwald
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 lattenwald/mcp-stdio-proxy

使用说明

mcp stdio代理

用于模型上下文协议（MCP）的最小stdio到流式HTTP代理。

目的

此代理弥合了基于stdio的MCP客户端（如Claude Code）和可流式HTTP MCP服务器（如MCP-hub）之间的差距。它透明地处理协议转换。

建筑

Claude Code (stdio) → mcp-stdio-proxy → mcp-hub (Streamable HTTP) → Backend MCP Servers

特性

  • 最小化：单个二进制文件，不需要配置文件
  • 符合协议：实现MCP 2025-03-26可流式HTTP规范
  • 会话管理：自动处理Mcp会话Id标头
  • 智能自动发现：自动查找项目本地mcp中心实例并确定其优先级
  • 快速：基于Go的、低延迟、最小内存占用

安装

快速安装（推荐）

cd ~/projects/go/mcp-stdio-proxy
make          # Build and install to ~/bin (or /usr/local/bin if root)

手动构建

cd ~/projects/go/mcp-stdio-proxy
go build -o mcp-stdio-proxy

生成文件目标

  • make 或 make all -构建和安装（默认）
  • make build -仅构建二进制文件
  • make install -安装到 ~/bin （用户）或 /usr/local/bin （根）
  • make lint -跑步门楣（fmt、兽医、golangci lint）
  • make test -运行测试
  • make clean -删除构建工件
  • make help -显示可用目标

用法

# Basic usage with explicit URL
./mcp-stdio-proxy http://localhost:37373/mcp

# Auto-discover local mcp-hub port (recommended!)
./mcp-stdio-proxy --mcp-hub

# With custom timeout (default: 120 seconds)
./mcp-stdio-proxy --timeout 300 http://localhost:37373/mcp

# With debug logging
./mcp-stdio-proxy --debug http://localhost:37373/mcp
./mcp-stdio-proxy --mcp-hub --debug

# Get help
./mcp-stdio-proxy --help

# Use with Claude Code in .claude.json
{
  "mcpServers": {
    "hub": {
      "command": "/path/to/mcp-stdio-proxy",
      "args": ["--mcp-hub"]
    }
  }
}

# Or with explicit URL
{
  "mcpServers": {
    "hub": {
      "command": "/path/to/mcp-stdio-proxy",
      "args": ["http://localhost:37373/mcp"]
    }
  }
}

# Enable debug logging in Claude Code
{
  "mcpServers": {
    "hub": {
      "command": "/path/to/mcp-stdio-proxy",
      "args": ["--mcp-hub", "--debug"]
    }
  }
}

选项

  • --mcp-hub -自动发现本地mcp集线器端口（无需URL！）
  • --timeout -HTTP请求超时（秒）（默认值：120）
  • --debug / -v / --verbose -启用stderr的调试日志记录
  • --help / -h -显示帮助消息

端口自动发现

这 --mcp-hub flag会自动查找本地计算机上运行的mcp-hub：

  1. 进程列表搜索：扫描 mcp-hub 加工和提取 --port 论点
  2. 智能优先级：当发现多个mcp-hub实例时，优先考虑项目本地配置
  3. 网络套接字回退：用途 ss 或 netstat 查找侦听端口

这消除了手动跟踪mcp-hub在哪个端口上运行的需要，在mcp-hub动态选择端口时尤其有用。

智能实例选择

当多个mcp-hub实例正在运行时，代理会智能地选择最相关的一个：

优先级逻辑：

  • ✅ 更喜欢项目本地配置 全球 ~/.mcp-hub/ 配置
  • ✅ 按距离得分 到当前工作目录
  • ✅ 家长目录奖励 -支持父目录中的配置（典型的项目结构）
  • ✅ 显示评分详细信息 随着 --debug 旗帜

示例场景：

# Two mcp-hub instances running:
# 1. Port 37373 - global config: ~/.mcp-hub/config.json
# 2. Port 40808 - project config: ~/myproject/.mcphub/servers.json

# When running from ~/myproject/src/
./mcp-stdio-proxy --mcp-hub --debug

# Output (debug mode):
# [DISCOVERY] Instance scoring:
#   Instance 1 (port 40808): score=500 - project-local config
#   Instance 2 (port 37373): score=0 - global config only
# [DISCOVERY] Selected instance with port 40808

这允许在项目之间无缝切换-代理根据您当前的目录自动连接到特定于项目的mcp-hub实例。

流程可见性

使用时 --mcp-hub 模式下，代理使用丰富的参数重新执行自身，使连接详细信息在中可见 ps 输出：

# User runs:
./mcp-stdio-proxy --mcp-hub

# After auto-discovery, appears in ps as:
./mcp-stdio-proxy --mcp-hub-config /path/to/.mcphub/servers.json http://localhost:40808/mcp

优点：

  • ✅ 易于识别 每个代理连接到哪个mcp集线器实例
  • ✅ 请参阅配置路径 了解正在使用哪个项目的配置
  • ✅ 调试多实例设置 随着 ps aux | grep mcp-stdio-proxy

示例 ps 输出：

$ ps aux | grep mcp-stdio-proxy
user  12345  ./mcp-stdio-proxy --mcp-hub-config ~/.mcp-hub/config.json http://localhost:37373/mcp
user  12346  ./mcp-stdio-proxy --mcp-hub-config ~/project/.mcphub/servers.json http://localhost:40808/mcp
user  12347  ./mcp-stdio-proxy http://localhost:9999/mcp

调试日志记录也可以通过环境变量启用：

DEBUG=1 ./mcp-stdio-proxy http://localhost:37373/mcp
DEBUG=1 ./mcp-stdio-proxy --mcp-hub

需求

  • 转到1.21或更高版本
  • 使用流式HTTP传输运行MCP服务器

兼容性

支持的服务器

✅ 符合MCP规范的服务器

mcp集线器兼容性

⚠️ mcp-hub v4.2.1（当前版本）

  • 目前 不支持 （使用非标准运输）
  • mcp-hub使用自定义的两端点SSE模式（GET/mcp+POST/messages）
  • 看 docs/MCP-HUB-QUIRKS.md 了解技术细节

🎉 mcp-hub（即将推出-PR#128合并后）

  • 将得到全力支持 无需更改代理！
  • 产品编号128 添加了标准的Streamable HTTP支持
  • 与传统SSE传输向后兼容
  • 发布时升级mcp-hub： npm install -g @ravitemer/mcp-hub@latest

使用带有mcp-hub PR#128的代理（测试）

如果你想在正式发布之前进行测试：

# Clone and checkout PR branch
cd ~/git/mcp-hub
git fetch origin pull/128/head:pr-128
git checkout pr-128
npm install
npm start

# Then use proxy as normal (no special flags needed!)
./mcp-stdio-proxy http://localhost:37373/mcp

时间线

  • 现在：适用于符合MCP规范的服务器
  • 等待：PR#128合并（增加mcp-hub兼容性）
  • 合并后：与mcp集线器开箱即用
  • 第四阶段已取消: --mcp-hub-mode 不再需要标志（节省4-6小时的开发时间）

文档

许可证

麻省理工学院

相关 MCP