mcp-proxy

• mcp-proxy
  • 关于
  • 1. stdio 到 SSE
    • 1.1 配置
    • 1.2 使用示例
  • 2. SSE 到 stdio
    • 2.1 配置
    • 2.2 使用示例
  • 安装
    • 通过 Smithery 安装
    • 通过 PyPI 安装
    • 通过 Github 仓库安装 (最新)
    • 作为容器安装
  • 扩展容器镜像
  • Docker Compose 设置
  • 命令行参数
  • 测试

关于

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

1. stdio 到 SSE
2. SSE 到 stdio

1. stdio 到 SSE

从 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 作为程序的第一个参数传递。

参数

名称	是否必需	描述	示例
command_or_url	是	要连接的 MCP 服务器 SSE 端点	http://example.io/sse
--headers	否	用于 MCP 服务器 SSE 连接的标头	Authorization 'Bearer my-secret-access-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 服务器，该服务器连接到本地 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
--sse-port	否，随机可用	要侦听的 SSE 服务器端口	8080
--sse-host	否，默认为 127.0.0.1	SSE 服务器将侦听的主机 IP 地址	0.0.0.0
--env	否	要传递到 MCP stdio 服务器的其他环境变量	FOO=BAR
--pass-environment	否	在生成服务器时传递所有环境变量	--no-pass-environment
--allow-origin	否	在生成服务器时传递所有环境变量	--allow-cors "*"

2.2 使用示例

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

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

# 在代理后面启动 MCP 服务器，使用自定义端口
mcp-proxy --sse-port=8080 uvx mcp-server-fetch

# 在代理后面启动 MCP 服务器，使用自定义主机和端口
mcp-proxy --sse-host=0.0.0.0 --sse-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 服务器，该服务器可以在 http://127.0.0.1:8080/sse 上连接。

安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 MCP Proxy：

npx -y @smithery/cli install mcp-proxy --client claude

通过 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 -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --help

扩展容器镜像

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

# file: 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 [ "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 --sse-port=8096 --sse-host 0.0.0.0 uvx mcp-server-fetch"

[!NOTE] 不要忘记设置 --pass-environment 参数，否则您将遇到错误“No interpreter found in managed installations or search path”

命令行参数

usage: mcp-proxy [-h] [-H KEY VALUE] [-e KEY VALUE] [--pass-environment | --no-pass-environment] [--sse-port SSE_PORT] [--sse-host SSE_HOST]
                 [--allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]]
                 [command_or_url] [args ...]

Start the MCP proxy in one of two possible modes: as an SSE or stdio client.

positional arguments:
  command_or_url        Command or URL to connect to. When a URL, will run an SSE client, otherwise will run the given command and connect as a stdio client. See corresponding options for more details.

options:
  -h, --help            show this help message and exit

SSE client options:
  -H KEY VALUE, --headers KEY VALUE
                        Headers to pass to the SSE server. Can be used multiple times.

stdio client options:
  args                  Any extra arguments to the command to spawn the server
  -e KEY VALUE, --env KEY VALUE
                        Environment variables used when spawning the server. Can be used multiple times.
  --pass-environment, --no-pass-environment
                        Pass through all environment variables when spawning the server.

SSE server options:
  --sse-port SSE_PORT   Port to expose an SSE server on. Default is a random port
  --sse-host SSE_HOST   Host to expose an SSE server on. Default is 127.0.0.1
  --allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]
                        Allowed origins for the SSE server. Can be used multiple times. Default is no CORS allowed.

Examples:
  mcp-proxy http://localhost:8080/sse
  mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse
  mcp-proxy --sse-port 8080 -- your-command --arg1 value1 --arg2 value2
  mcp-proxy your-command --sse-port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE
  mcp-proxy your-command --sse-port 8080 --allow-origin='*'

测试

通过使用 mcp-server-fetch 服务器运行 mcp-proxy 服务器来检查它。 您可以使用 inspector tool 来测试目标服务器。

# 在 SSE 上通过代理运行名为 mcp-server-fetch 的 stdio 服务器
mcp-proxy --sse-port=8080 uvx mcp-server-fetch &

# 使用另一个 mcp-proxy 实例连接到上面生成的 SSE 代理服务器，给定 SSE 服务器的 URL
mcp-proxy http://127.0.0.1:8080/sse

# 发送 CTRL+C 以停止第二个服务器

# 将第一个服务器带到前台
fg

# 发送 CTRL+C 以停止第一个服务器