mcp-proxy

• mcp-proxy
  • 关于
  • 1. stdio 到 SSE/可流式传输HTTP
    • 1.1 配置
    • 1.2 示例用法
  • 2. SSE 到 stdio
    • 2.1 配置
    • 2.2 示例用法
  • 命名服务器
  • 安装
    • 通过 PyPI 安装
    • 通过 GitHub 仓库安装（最新版本）
    • 作为容器安装
    • 故障排除
  • 扩展容器镜像
  • Docker Compose 设置
  • 命令行参数
    • 示例配置文件
  • 测试

关于

mcp-proxy 是一个工具，允许您在不同的服务器传输之间切换。支持两种模式：

1. stdio 到 SSE/可流式传输HTTP
2. SSE 到 stdio

1. stdio 到 SSE/可流式传输HTTP

运行一个从 stdio 连接到远程 SSE 服务器的代理服务器。

此模式允许客户端如 Claude Desktop 通过 SSE 与远程服务器通信，即使它不原生支持 SSE。

graph LR
    A["Claude Desktop"] <--> |stdio| B["mcp-proxy"]
    B <--> |SSE| C["外部 MCP 服务器"]

    style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
    style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px
    style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px

1.1 配置

此模式需要提供 MCP 服务器 SSE 端点的 URL 作为程序的第一个参数。如果服务器使用可流式传输 HTTP 传输，请确保在 mcp-proxy 侧通过传递 --transport=streamablehttp 来强制执行。

参数

名称	必需	描述	示例
command_or_url	是	要连接的 MCP 服务器 SSE 端点	http://example.io/sse
--headers	否	用于 MCP 服务器 SSE 连接的头部	Authorization 'Bearer my-secret-access-token'
--transport	否	决定连接 MCP 服务器时使用的传输协议。可以是 'sse' 或 'streamablehttp'	streamablehttp
--client-id	否	用于身份验证的 OAuth2 客户端 ID	your_client_id
--client-secret	否	用于身份验证的 OAuth2 客户端密钥	your_client_secret
--token-url	否	用于身份验证的 OAuth2 令牌端点 URL	https://auth.example.com/oauth/token

环境变量

名称	必需	描述	示例
API_ACCESS_TOKEN	否	可以代替 --headers Authorization 'Bearer <API_ACCESS_TOKEN>' 使用	YOUR_TOKEN

1.2 示例用法

mcp-proxy 应该由 MCP 客户端启动，因此必须相应地进行配置。

对于 Claude Desktop，配置项可以如下所示：

{
  "mcpServers": {
    "mcp-proxy": {
      "command": "mcp-proxy",
      "args": [
        "http://example.io/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "access-token"
      }
    }
  }
}

2. SSE 到 stdio

运行一个暴露 SSE 服务器的代理服务器，该 SSE 服务器连接到本地 stdio 服务器。

这允许远程连接到本地 stdio 服务器。mcp-proxy 打开一个端口来监听 SSE 请求，并启动一个处理 MCP 请求的本地 stdio 服务器。

graph LR
    A["LLM 客户端"] <-->|SSE| B["mcp-proxy"]
    B <-->|stdio| C["本地 MCP 服务器"]

    style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
    style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px
    style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px

2.1 配置

此模式需要设置 --sse-port 参数。可以通过设置 --sse-host 参数来指定 SSE 服务器将监听的主机 IP 地址。可以使用 --env 参数将额外的环境变量传递给本地 stdio 服务器。本地 stdio 服务器的命令行参数必须在 -- 分隔符之后传递。

参数

名称	必需	描述	示例
command_or_url	是	要启动 MCP stdio 服务器的命令	uvx mcp-server-fetch
--port	否，随机可用端口	MCP 服务器监听的端口	8080
--host	否，默认为 127.0.0.1	MCP 服务器将监听的主机 IP 地址	0.0.0.0
--env	否	传递给 MCP stdio 服务器的额外环境变量。可以多次使用。	FOO BAR
--cwd	否	传递给 MCP stdio 服务器进程的工作目录。	/tmp
--pass-environment	否	在启动服务器时传递所有环境变量	--no-pass-environment
--allow-origin	否	允许的 SSE 服务器来源。可以多次使用。默认不允许 CORS。	--allow-origin "*"
--stateless	否	启用可流式传输 HTTP 传输的状态无关模式。默认为 False	--no-stateless
--named-server NAME COMMAND_STRING	否	定义一个命名 stdio 服务器。	--named-server fetch 'uvx mcp-server-fetch'
--named-server-config FILE_PATH	否	指向定义命名 stdio 服务器的 JSON 文件路径。	--named-server-config /path/to/servers.json
--sse-port (已弃用)	否，随机可用端口	SSE 服务器监听的端口	8080
--sse-host (已弃用)	否，默认为 127.0.0.1	SSE 服务器将监听的主机 IP 地址	0.0.0.0

2.2 示例用法

要启动监听 8080 端口并连接到本地 MCP 服务器的 mcp-proxy 服务器：

# 启动代理后面的 MCP 服务器
mcp-proxy uvx mcp-server-fetch

# 启动具有自定义端口的代理后面的 MCP 服务器
# (已弃用) mcp-proxy --sse-port=8080 uvx mcp-server-fetch
mcp-proxy --port=8080 uvx mcp-server-fetch

# 启动具有自定义主机和端口的代理后面的 MCP 服务器
# (已弃用) mcp-proxy --sse-host=0.0.0.0 --sse-port=8080 uvx mcp-server-fetch
mcp-proxy --host=0.0.0.0 --port=8080 uvx mcp-server-fetch

# 启动具有自定义用户代理的代理后面的 MCP 服务器
# 注意，`--` 分隔符用于分离 `mcp-proxy` 参数和 `mcp-server-fetch` 参数
# (已弃用) mcp-proxy --sse-port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent
mcp-proxy --port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent

# 启动多个命名 MCP 服务器
mcp-proxy --port=8080 --named-server fetch 'uvx mcp-server-fetch' --named-server fetch2 'uvx mcp-server-fetch'

# 使用配置文件启动多个命名 MCP 服务器
mcp-proxy --port=8080 --named-server-config ./servers.json

命名服务器

• NAME 用于 URL 路径 /servers/NAME/ 中。
• COMMAND_STRING 是启动服务器的命令（例如，'uvx mcp-server-fetch'）。
  • 可以多次使用。
  • 如果使用了 --named-server-config，此参数将被忽略。
• FILE_PATH - 如果提供了此参数，则这是命名服务器的唯一来源，且 --named-server CLI 参数将被忽略。

如果指定了默认服务器（即没有 --named-server 或 --named-server-config 的 command_or_url 参数），则可以在根路径下访问（例如，http://127.0.0.1:8080/sse）。

命名服务器（无论是通过 --named-server 还是 --named-server-config 定义的）都可以在 /servers/<server-name>/ 下访问（例如，http://127.0.0.1:8080/servers/fetch1/sse）。/status 端点提供全局状态。

--named-server-config 的 JSON 配置文件格式：

JSON 文件应遵循以下结构：

{
  "mcpServers": {
    "fetch": {
      "disabled": false,
      "timeout": 60,
      "command": "uvx",
      "args": [
        "mcp-server-fetch"
      ],
      "transportType": "stdio"
    },
    "github": {
      "timeout": 60,
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      },
      "transportType": "stdio"
    }
  }
}

• mcpServers：一个字典，其中每个键是服务器名称（用于 URL 路径，例如 /servers/fetch/），值是一个定义服务器的对象。
• command：（必需）要执行的 stdio 服务器命令。
• args：（可选）命令的参数列表。默认为空列表。
• enabled：（可选）如果为 false，则跳过此服务器定义。默认为 true。
• timeout 和 transportType：这些字段存在于标准 MCP 客户端配置中，但在加载命名服务器时被 mcp-proxy 忽略。传输类型隐含为 "stdio"。

安装

通过 PyPI 安装

稳定版本的包可在 PyPI 存储库中获得。您可以使用以下命令安装：

# 选项 1：使用 uv（推荐）
uv tool install mcp-proxy

# 选项 2：使用 pipx（替代方案）
pipx install mcp-proxy

安装后，您可以使用 mcp-proxy 命令运行服务器。参见上面的每种模式的配置选项。

通过 GitHub 仓库安装（最新版本）

可以从 git 仓库安装最新版本的包，使用以下命令：

uv tool install git+https://github.com/sparfenyuk/mcp-proxy

[!NOTE] 如果您已经安装了服务器，可以使用 uv tool upgrade --reinstall 命令更新它。

[!NOTE] 如果您想删除服务器，可以使用 uv tool uninstall mcp-proxy 命令。

作为容器安装

从版本 0.3.2 开始，可以拉取并运行相应的容器镜像：

docker run --rm -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --help

故障排除

• 问题：Claude Desktop 无法启动服务器：日志中的 ENOENT 错误代码

  解决方案：尝试使用二进制文件的完整路径。为此，打开终端并运行命令 which mcp-proxy（macOS、Linux）或 where.exe mcp-proxy（Windows）。然后，将输出路径用作 'command' 属性的值：

    "fetch": {
      "command": "/full/path/to/bin/mcp-proxy",
      "args": [
        "http://localhost:8932/sse"
      ]
    }
  

扩展容器镜像

您可以扩展 mcp-proxy 容器镜像以包含额外的可执行文件。例如，uv 默认情况下未包含，但您可以创建一个带有它的自定义镜像：

# 文件：mcp-proxy.Dockerfile

FROM ghcr.io/sparfenyuk/mcp-proxy:latest

# 安装 'uv' 包
RUN python3 -m ensurepip && pip install --no-cache-dir uv

ENV PATH="/usr/local/bin:$PATH" \
    UV_PYTHON_PREFERENCE=only-system

ENTRYPOINT ["catatonit", "--", "mcp-proxy"]

Docker Compose 设置

使用自定义 Dockerfile，您可以在 Docker Compose 文件中定义服务：

services:
  mcp-proxy-custom:
    build:
      context: .
      dockerfile: mcp-proxy.Dockerfile
    network_mode: host
    restart: unless-stopped
    ports:
      - 8096:8096
    command: "--pass-environment --port=8096 --sse-host 0.0.0.0 uvx mcp-server-fetch"

[!NOTE] 不要忘记设置 --pass-environment 参数，否则您会遇到“未在托管安装或搜索路径中找到解释器”的错误。

命令行参数

usage: mcp-proxy [-h] [--version] [-H KEY VALUE]
                 [--transport {sse,streamablehttp}] [--verify-ssl [VALUE]]
                 [--no-verify-ssl] [-e KEY VALUE] [--cwd CWD]
                 [--client-id CLIENT_ID] [--client-secret CLIENT_SECRET] [--token-url TOKEN_URL]
                 [--pass-environment | --no-pass-environment]
                 [--log-level LEVEL] [--debug | --no-debug]
                 [--named-server NAME COMMAND_STRING]
                 [--named-server-config FILE_PATH] [--port PORT] [--host HOST]
                 [--stateless | --no-stateless] [--sse-port SSE_PORT]
                 [--sse-host SSE_HOST]
                 [--allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]]
                 [command_or_url] [args ...]

启动 MCP 代理，有两种可能的模式：作为客户端或服务器。

位置参数：
  command_or_url        要连接的命令或 URL。当为 URL 时，将运行 SSE/可流式传输HTTP 客户端。否则，如果没有使用 --named-server，则此命令为默认 stdio 客户端的命令。如果使用了 --named-server，则此参数在 stdio 模式下被忽略，除非不需要默认服务器。参见相关选项以获取更多详细信息。

选项：
  -h, --help            显示此帮助信息并退出
  --version             显示版本并退出

SSE/可流式传输HTTP 客户端选项：
  -H, --headers KEY VALUE
                        传递给 SSE 服务器的头部。可以多次使用。
  --transport {sse,streamablehttp}
                        客户端使用的传输协议。默认为 SSE。
  --verify-ssl [VALUE]  当作为客户端时控制 SSL 验证。不带值使用以强制验证，传递 'false' 以禁用，或者提供 PEM 包的路径。
  --no-verify-ssl       禁用 SSL 验证（等同于 --verify-ssl false）。
  --client-id CLIENT_ID
                        用于身份验证的 OAuth2 客户端 ID
  --client-secret CLIENT_SECRET
                        用于身份验证的 OAuth2 客户端密钥
  --token-url TOKEN_URL
                        用于身份验证的 OAuth2 令牌 URL

stdio 客户端选项：
  args                  启动默认服务器的任何额外参数。如果仅定义了命名服务器，则被忽略。
  -e, --env KEY VALUE   启动默认服务器时使用的环境变量。可以多次使用。对于命名服务器，环境是从 --pass-environment 继承或传递的。
  --cwd CWD             启动默认服务器进程时使用的工作目录。命名服务器继承代理的 CWD。
  --pass-environment, --no-pass-environment
                        在启动所有服务器进程时传递所有环境变量。
  --log-level LEVEL