使用说明

MCP网关

用Go编写的高性能MCP（模型上下文协议）网关，将多个下游MCP服务器连接到多个上游WebSocket端点。

特性

🚀 高性能：原生Go与goroutines并发
🔌 多种运输方式：支持stdio、HTTP、SSE和StreamableHTTP
🔄 自动重新连接：具有抖动的指数回退
📊 工具聚合：聚合来自多个MCP服务器的工具
🛡️ 稳健的错误处理：优雅的关机和流程管理
📝 结构化日志记录：在详细模式下使用Go 1.21+slog
🌐 多上游支持：使用独立的MCP服务器配置连接多个上游
🔧 环境变量：支持 ${VAR} 配置文件中的语法

建筑

┌─────────────────┐      WebSocket       ┌──────────────────┐
│  Upstream AI 1  │ ◄─────────────────► │                  │
│  (xiaozhi-1)    │                      │                  │
└─────────────────┘                      │   mcp-gateway    │
                                         │                  │
┌─────────────────┐      WebSocket       │                  │
│  Upstream AI 2  │ ◄─────────────────► │                  │
│  (xiaozhi-2)    │                      └────────┬─────────┘
└─────────────────┘                               │
                                    ┌─────────────┼─────────────┐
                                    ▼             ▼             ▼
                              ┌──────────┐ ┌──────────┐ ┌──────────┐
                              │ stdio    │ │  HTTP    │ │  SSE     │
                              │ adapter  │ │ adapter  │ │ adapter  │
                              └────┬─────┘ └────┬─────┘ └────┬─────┘
                                   │            │            │
                              ┌────▼────┐ ┌────▼────┐ ┌────▼────┐
                              │calculator│ │web-search│ │smartrun │
                              └─────────┘ └─────────┘ └─────────┘

备注：每个上游都有自己的独立MCP服务器配置，允许每个上游使用不同的令牌/凭据。

快速开始

1.克隆和构建

cd mcp-gateway
go mod tidy
go build -o mcp-gateway ./cmd/mcp-gateway

2.配置

# 复制示例配置文件
cp configs/mcp_config.example.json configs/mcp_config.json
cp run_local.example.sh run_local.sh
cp deploy_remote.example.sh deploy_remote.sh

# 编辑配置文件，填入你的 token
vim configs/mcp_config.json
vim run_local.sh
vim deploy_remote.sh

# 添加执行权限
chmod +x run_local.sh deploy_remote.sh

3.跑步

# 本地 macOS 运行
./run_local.sh build    # 编译
./run_local.sh start    # 启动
./run_local.sh status   # 查看状态
./run_local.sh logs     # 查看日志
./run_local.sh check    # 检查 MCP 服务器状态和工具列表

# 远程 Linux 部署
./deploy_remote.sh deploy   # 编译 + 上传 + 启动
./deploy_remote.sh status   # 远程状态
./deploy_remote.sh logs     # 远程日志

check命令

使用 check 命令可以验证配置并检查所有 MCP 服务器的连接状态和可用工具：

# 通过脚本运行
./run_local.sh check

# 或直接运行二进制
./mcp-gateway -check -config configs/mcp_config.json

# JSON 格式输出（方便脚本解析）
./mcp-gateway -check -config configs/mcp_config.json -output json

# 自定义超时时间
./mcp-gateway -check -config configs/mcp_config.json -timeout 60s

输出示例：

==================================================
         MCP Gateway Configuration Check
==================================================

📡 Upstream: xiaozhi-agent
   Endpoint: wss://api.xiaozhi.me/mcp/?token=***

   ✅ [tencentdocs] (http)
      URL: https://docs.qq.com/openapi/mcp
      Status: Connected
      Server: mcp-McpserverService v1.0.0
      Tools (12):
        • create_word_by_markdown      通过Markdown格式创建在线Word文档...
        • get_content                  获取文档完整内容...
        ...

   ❌ [local-mcp] (stdio)
      Command: python mcp_server.py
      Status: Failed
      Error: start failed: exec: "python": not found

--------------------------------------------------
📊 Summary
--------------------------------------------------
   Total Upstreams:    1
   Total MCP Servers:  2
     • Healthy:        1
     • Failed:         1
   Total Tools:        12
==================================================

配置

环境变量

# Optional: WebSocket endpoint (can be used with ${MCP_ENDPOINT} in config)
export MCP_ENDPOINT='wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN'

# Optional: Log level
export MCP_LOG_LEVEL=debug

配置文件格式

看 configs/mcp_config.example.json 例如：

{
  "upstreams": [
    {
      "name": "xiaozhi-agent-1",
      "endpoint": "${MCP_ENDPOINT}",
      "reconnect": {
        "enabled": true,
        "initialBackoff": "1s",
        "maxBackoff": "10m",
        "multiplier": 2
      },
      "keepalive": {
        "interval": "30s",
        "timeout": "10s"
      },
      "mcpServers": {
        "tencentdocs": {
          "type": "http",
          "url": "https://docs.qq.com/openapi/mcp",
          "headers": {
            "Authorization": "your-token"
          },
          "timeout": "60s",
          "disabled": false
        },
        "web-search": {
          "type": "http",
          "url": "http://127.0.0.1:3000/mcp",
          "timeout": "120s"
        }
      }
    },
    {
      "name": "xiaozhi-agent-2",
      "endpoint": "wss://api.xiaozhi.me/mcp/?token=ANOTHER_TOKEN",
      "reconnect": { "enabled": true },
      "keepalive": { "interval": "30s", "timeout": "10s" },
      "mcpServers": {
        "xxx-mcp": {
          "type": "http",
          "url": "https://xxx-mcp.123.com/mcp",
          "headers": { "Authorization": "Bearer your-smartrun-token" },
          "timeout": "180s"
        }
      }
    }
  ],
  "logging": {
    "level": "info",
    "format": "text",
    "verbose": false
  },
  "metrics": {
    "enabled": false,
    "port": 9090
  }
}

配置结构

字段	描述
`upstreams`	上游配置阵列，每个配置都有独立的MCP服务器
`upstreams[].name`	上游实例的唯一名称
`upstreams[].endpoint`	WebSocket URL（支持 `${VAR}` 环境变量扩展）
`upstreams[].reconnect`	重新连接设置（启用、初始回退、最大回退、倍数）
`upstreams[].keepalive`	保持活动设置（间隔、超时）
`upstreams[].mcpServers`	此上游的MCP服务器配置图
`logging.verbose`	何时 `true`，记录完整的请求参数和响应内容

服务器类型

类型	描述
`stdio`	具有stdin/stdout通信的本地进程
`http`	HTTP/StreamableHTTP端点
`sse`	服务器发送事件端点

多上游用例

每个上游都可以有自己的一组具有不同配置的MCP服务器：

不同的AI代理：同时连接多个AI助手
不同的凭据：每个上游可以为同一MCP服务使用不同的令牌
独立路由：每个上游MCP服务器的工具都是独立路由的

文件结构

mcp-gateway/
├── cmd/mcp-gateway/              # Main entry point
│   └── main.go                   # Application bootstrap
├── internal/
│   ├── adapter/                  # MCP server adapters (stdio, http, sse)
│   ├── checker/                  # Configuration check & validation
│   ├── config/                   # Configuration management
│   ├── protocol/                 # MCP protocol definitions
│   ├── router/                   # Message routing & tool aggregation
│   └── upstream/                 # WebSocket upstream client
├── pkg/retry/                    # Retry utilities with backoff
├── configs/
│   ├── mcp_config.example.json   # ⭐ 配置示例（提交到 git）
│   └── mcp_config.json           # 🔒 实际配置（不提交）
├── run_local.example.sh          # ⭐ 本地运行脚本示例
├── run_local.sh                  # 🔒 本地运行脚本（含环境变量）
├── deploy_remote.example.sh      # ⭐ 远程部署脚本示例
├── deploy_remote.sh              # 🔒 远程部署脚本（含服务器信息）
├── go.mod                        # Go module definition
└── .gitignore                    # Git ignore rules

安全说明

⚠️ 敏感信息处理：

以下文件包含 token 等敏感信息，不要提交到 git：

configs/mcp_config.json
run_local.sh
deploy_remote.sh
.env

请使用 .example 后缀的示例文件作为模板，复制后填入你的实际配置。

建筑

# Development build
go build -o mcp-gateway ./cmd/mcp-gateway

# Production build with optimizations
CGO_ENABLED=0 go build -ldflags="-s -w" -o mcp-gateway ./cmd/mcp-gateway

# Cross-compile for Linux
GOOS=linux GOARCH=amd64 go build -o mcp-gateway-linux ./cmd/mcp-gateway

与Python版本的比较

特性	Python（mcp_pipe.py）	Go（mcp网关）
性能	单线程异步	本机goroutines
内存	~50-100MB	~10-20MB
启动	2-3s	<100ms
部署	Python+venv+deps	单个二进制文件
流程管理	子流程+mcp_proxy	处理中
稳定性	基本错误处理	强健的恢复

许可证

麻省理工学院