TBXark/mcp-proxy 构建你的 MCP 代理服务器

TBXark/mcp-proxy 教程：构建你的 MCP 代理服务器

项目地址: https://github.com/TBXark/mcp-proxy

项目简介

mcp-proxy 是一个强大的 MCP (Model Context Protocol) 代理服务器，旨在简化和统一对多个 MCP 资源服务器的访问。通过将多个 MCP 服务器聚合到一个单一的 HTTP 入口点，mcp-proxy 极大地简化了客户端配置和管理，尤其是在复杂的 AI 应用场景中。

什么是 MCP？

MCP (Model Context Protocol) 是一种用于在不同系统或服务之间传递上下文信息的协议。在人工智能领域，MCP 充当桥梁，允许在模型的不同组件之间高效地共享数据、配置和状态信息。这对于构建模块化、可扩展且易于维护的 AI 系统至关重要。

为什么需要 MCP 代理服务器？

在微服务架构盛行的今天，一个 AI 应用可能依赖于多个独立的 MCP 服务器来提供不同的功能。直接与这些服务器交互会带来以下挑战：

配置复杂性: 客户端需要维护多个服务器的地址和认证信息。
管理困难: 难以对多个 MCP 服务器进行统一的管理和监控。
安全风险: 每个客户端都需要单独进行权限控制，增加了安全漏洞的风险。

mcp-proxy 通过以下方式解决了这些问题：

统一入口: 将多个 MCP 服务器聚合到一个地址，客户端只需与代理服务器交互。
简化配置: 客户端只需要配置一个代理服务器地址，无需关心后端多个 MCP 服务器的细节。
灵活管理: 可以对 MCP 服务器进行统一的管理和控制，例如权限控制、流量控制、日志记录等。
增强安全性: 集中进行身份验证和授权，降低安全风险。

功能特性

多 MCP 客户端代理: 连接到多个 MCP 资源服务器，并将它们的功能整合到一个统一的接口中。
SSE (Server-Sent Events) 支持: 提供 SSE 服务器，允许客户端接收来自 MCP 服务器的实时更新。这对于需要实时反馈的应用场景非常有用。
灵活的配置选项: 支持多种客户端类型 (stdio, sse 和 streamable-http)，并提供丰富的配置选项，以满足不同的需求。
工具过滤: 允许你根据需要选择性地启用或禁用特定的工具，从而增强系统的安全性并减少不必要的资源消耗。
认证和授权: 支持基于令牌的身份验证，确保只有授权的客户端才能访问 MCP 服务器。
日志记录: 记录所有请求和响应，方便进行故障排除和性能分析。
可扩展性: 易于扩展，可以添加新的 MCP 服务器和功能。

安装

mcp-proxy 提供了多种安装方式，你可以根据自己的需求选择最适合的方式。

1. 从源码构建

这是最灵活的安装方式，允许你自定义构建过程。

git clone https://github.com/TBXark/mcp-proxy.git
cd mcp-proxy
make build
./build/mcp-proxy --config path/to/config.json

详细步骤：

克隆代码仓库: 使用 git clone 命令将 mcp-proxy 的代码仓库克隆到你的本地机器上。
进入项目目录: 使用 cd 命令进入 mcp-proxy 目录。
构建项目: 使用 make build 命令编译项目。这将会生成一个可执行文件 mcp-proxy 在 build 目录下。
运行代理服务器: 使用 ./build/mcp-proxy --config path/to/config.json 命令运行 mcp-proxy，并指定配置文件的路径。

依赖:

Go 语言环境 (>= 1.18)
Make

2. 使用 Go 安装

如果你已经安装了 Go 语言环境，可以使用 go install 命令快速安装 mcp-proxy。

1	go install github.com/TBXark/mcp-proxy@latest

这将会将 mcp-proxy 安装到你的 $GOPATH/bin 目录下。确保 $GOPATH/bin 目录已经添加到你的 PATH 环境变量中。

3. 使用 Docker

Docker 是一个流行的容器化平台，可以让你轻松地部署和管理 mcp-proxy。

1
2
3

docker run -d -p 9090:9090 -v /path/to/config.json:/config/config.json ghcr.io/tbxark/mcp-proxy:latest
# 或者
docker run -d -p 9090:9090 ghcr.io/tbxark/mcp-proxy:latest --config https://example.com/path/to/config.json

详细说明：

-d: 在后台运行容器。
-p 9090:9090: 将主机的 9090 端口映射到容器的 9090 端口。你可以根据需要修改端口号。
-v /path/to/config.json:/config/config.json: 将主机上的配置文件挂载到容器中。你需要将 /path/to/config.json 替换为你实际的配置文件路径。
ghcr.io/tbxark/mcp-proxy:latest: mcp-proxy 的 Docker 镜像。
--config https://example.com/path/to/config.json: 你也可以使用一个 URL 作为配置文件。

注意:

你需要将 /path/to/config.json 替换为你实际的配置文件路径。
确保 Docker 已经正确安装并运行。

配置

mcp-proxy 使用 JSON 格式的配置文件。以下是一个示例配置：

{
  "mcpProxy": {
    "baseURL": "https://mcp.example.com",
    "addr": ":9090",
    "name": "MCP Proxy",
    "version": "1.0.0",
    "options": {
      "panicIfInvalid": false,
      "logEnabled": true,
      "authTokens": [
        "DefaultTokens"
      ]
    }
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      },
      "options": {
        "toolFilter": {
          "mode": "block",
          "list": [
            "create_or_update_file"
          ]
        }
      }
    },
    "fetch": {
      "command": "uvx",
      "args": [
        "mcp-server-fetch"
      ],
      "options": {
        "panicIfInvalid": true,
        "logEnabled": false,
        "authTokens": [
          "SpecificTokens"
        ]
      }
    },
    "amap": {
      "url": "https://mcp.amap.com/sse?key=<YOUR_TOKEN>"
    }
  }
}

配置文件结构

配置文件主要分为两个部分：

mcpProxy: 配置代理服务器自身的属性。
mcpServers: 配置需要代理的 MCP 服务器。

`mcpProxy` 配置项

baseURL: 公共可访问的服务器 URL。用于生成客户端的 URL。例如: "https://your-mcp-proxy.com"
addr: 服务器监听的地址。例如: ":9090" (监听所有接口的 9090 端口)
name: 服务器的名称。例如: "My MCP Proxy"
version: 服务器的版本。例如: "1.0.0"
options: mcpServers 的默认选项。

`mcpServers` 配置项

mcpServers 是一个 JSON 对象，每个 key 代表一个 MCP 服务器的名称，value 是该服务器的配置信息。

transportType: MCP 客户端的传输类型。支持以下三种类型：
- stdio: MCP 客户端是一个命令行工具，在子进程中运行。
- sse: MCP 客户端是一个支持 SSE (Server-Sent Events) 的服务器。
- streamable-http: MCP 客户端是一个支持 HTTP 流的服务器。

`stdio` 类型的 MCP 服务器配置

"github": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-github"
  ],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
  },
  "options": {
    "toolFilter": {
      "mode": "block",
      "list": [
        "create_or_update_file"
      ]
    }
  }
}

command: 运行 MCP 客户端的命令。例如: "npx"
args: 传递给命令的参数。例如: ["-y", "@modelcontextprotocol/server-github"]
env: 设置命令的环境变量。例如: {"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"}
options: 客户端特定的选项。

`sse` 类型的 MCP 服务器配置

1
2
3

"amap": {
  "url": "https://mcp.amap.com/sse?key=<YOUR_TOKEN>"
}

url: MCP 客户端的 URL。例如: "https://mcp.amap.com/sse?key=<YOUR_TOKEN>"

`streamable-http` 类型的 MCP 服务器配置

"fetch": {
  "url": "http://localhost:8080/fetch",
  "transportType": "streamable-http",
  "headers": {
    "Authorization": "Bearer <YOUR_TOKEN>"
  },
  "timeout": 30
}

url: MCP 客户端的 URL。例如: "http://localhost:8080/fetch"
transportType: 必须设置为 "streamable-http"。
headers: 随请求发送到 MCP 客户端的 Headers。例如: {"Authorization": "Bearer <YOUR_TOKEN>"}
timeout: 请求超时时间，单位为秒。

`options` 配置项

options 部分包含 mcpProxy 和 mcpServers 的通用选项。

panicIfInvalid: 如果为 true，当客户端无效时，服务器会 panic。默认值为 false。
logEnabled: 如果为 true，服务器会记录客户端的请求。默认值为 false。
authTokens: 客户端的身份验证令牌列表。Authorization header 将根据此列表进行检查。例如: ["token1", "token2"]
toolFilter: 可选的工具过滤配置。此配置仅在 mcpServers 中有效。

`toolFilter` 配置

toolFilter 允许你根据需要选择性地启用或禁用特定的工具。

mode: 指定过滤模式。必须显式设置为 allow 或 block。
- allow: 只允许列表中的工具。
- block: 阻止列表中的工具。
list: 要过滤的工具名称列表。

例如，以下配置只允许 github 服务器使用 get_issue 和 create_issue 工具：

"github": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-github"
  ],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
  },
  "options": {
    "toolFilter": {
      "mode": "allow",
      "list": [
        "get_issue",
        "create_issue"
      ]
    }
  }
}

使用方法

启动 mcp-proxy 后，你可以通过以下 URL 访问代理的 MCP 服务器：

1	http(s)://{baseURL}/{clientName}/sse

{baseURL}: mcpProxy 配置中的 baseURL。
{clientName}: mcpServers 中 MCP 服务器的名称。

例如，如果你的 baseURL 是 https://mcp.example.com，并且你配置了一个名为 github 的 MCP 服务器，那么你可以通过以下 URL 访问该服务器：

1	https://mcp.example.com/github/sse

命令行参数

mcp-proxy 支持以下命令行参数：

Usage of mcp-proxy:
  -config string
        path to config file or a http(s) url (default "config.json")
  -help
        print help and exit
  -version
        print version and exit

-config: 指定配置文件的路径。默认值为 config.json。你也可以使用一个 HTTP(S) URL 作为配置文件。
-help: 打印帮助信息并退出。
-version: 打印版本信息并退出。

最佳实践

使用环境变量管理敏感信息: 不要将敏感信息（例如 API 密钥、访问令牌）直接Hardcode在配置文件中。而是使用环境变量来传递这些信息。
配置日志记录: 启用日志记录可以帮助你诊断问题和监控系统性能。
使用工具过滤: 只允许必要的工具，可以提高系统的安全性。
定期更新: 定期更新 mcp-proxy 到最新版本，以获取最新的功能和安全补丁。
监控系统资源: 监控 mcp-proxy 的 CPU、内存和网络使用情况，确保系统运行稳定。

感谢

该项目受到了 adamwattis/mcp-proxy-server 项目的启发。
如果你对部署有任何疑问，可以参考《在 Docker 沙箱中运行 MCP Server》(@ccbikai)。

许可证

本项目使用 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。

总结

mcp-proxy 是一个功能强大且易于使用的 MCP 代理服务器，可以帮助你更轻松地管理和使用多个 MCP 服务器。希望本教程能够帮助你快速上手 mcp-proxy，并将其应用到你的 AI 项目中。通过合理配置和使用 mcp-proxy，你可以构建更模块化、可扩展和安全的 AI 系统。