mcp-proxy

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

关于

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

1. stdio 转 SSE/StreamableHTTP
2. SSE 转 stdio

1. stdio 转 SSE/StreamableHTTP

运行一个从 stdio（标准输入输出）连接到远程 SSE（Server-Sent Events）服务器的代理服务器。

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

graph LR
    A["Claude Desktop"] <--> |stdio| B["mcp-proxy"]
    B <--> |SSE| C["External MCP Server"]

    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 作为程序的第一个参数。如果服务器使用 Streamable 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 Token 端点 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 服务器以连接到本地 stdio 服务器。

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

graph LR
    A["LLM Client"] <-->|SSE| B["mcp-proxy"]
    B <-->|stdio| C["Local MCP Server"]

    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 (Server-Sent Events) 服务器将监听的主机 IP 地址。可以使用 --env 参数向本地 stdio (标准输入/输出) 服务器传递额外的环境变量。本地 stdio 服务器的命令行参数必须在 -- 分隔符之后传递。

参数

名称	必需	描述	示例
command_or_url	是	启动 MCP (Model Context Protocol) 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 "*"
--expose-header	否	添加到 Access-Control-Expose-Headers 的头部。可多次使用。默认为 mcp-session-id。	--expose-header Custom-Header
--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 (JavaScript 对象表示法) 文件路径。	--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

# 启用 CORS 和自定义暴露头启动 MCP 服务器
mcp-proxy --port=8080 --allow-origin='*' --expose-header Custom-Header uvx mcp-server-fetch

命名服务器

• 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 (JavaScript 对象表示法) 配置文件格式：

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 (Model Context Protocol) 客户端配置中，但在加载命名服务器时目前被 mcp-proxy 忽略。传输类型隐式为 "stdio"。

安装

通过 PyPI 安装

该包的稳定版本可在 PyPI (Python 包索引) 仓库获取。您可以使用以下命令进行安装：

# Option 1: With uv (recommended)
uv tool install mcp-proxy

# Option 2: With pipx (alternative)
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，但您可以创建包含它的自定义镜像：

# file: mcp-proxy.Dockerfile

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

# Install the 'uv' package
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 ...]]
                 [--expose-header HEADER]
                 [command_or_url] [args ...]

Start the MCP proxy in one of two possible modes: as a client or a server.

positional arguments:
  command_or_url        Command or URL to connect to. When a URL, will run an SSE/StreamableHTTP client. Otherwise, if --named-server is not used, this will be the command for the default stdio client. If --named-server is used, this argument is ignored for stdio mode unless no default server is desired. See corresponding options for more details.

options:
  -h, --help            show this help message and exit
  --version             Show the version and exit

SSE/StreamableHTTP client options:
  -H, --headers KEY VALUE
                        Headers to pass to the SSE server. Can be used multiple times.
  --transport {sse,streamablehttp}
                        The transport to use for the client. Default is SSE.
  --verify-ssl [VALUE]  Control SSL verification when acting as a client. Use without a value to force verification, pass 'false' to disable, or provide a path to a PEM bundle.
  --no-verify-ssl       Disable SSL verification (alias for --verify-ssl false).
  --client-id CLIENT_ID
                        OAuth2 client ID for authentication
  --client-secret CLIENT_SECRET
                        OAuth2 client secret for authentication
  --token-url TOKEN_URL
                        OAuth2 token URL for authentication

stdio client options:
  args                  Any extra arguments to the command to spawn the default server. Ignored if only named servers are defined.
  -e, --env KEY VALUE   Environment variables used when spawning the default server. Can be used multiple times. For named servers, environment is inherited or passed via --pass-environment.
  --cwd CWD             The working directory to use when spawning the default server process. Named servers inherit the proxy's CWD.
  --pass-environment, --no-pass-environment
                        Pass through all environment variables when spawning all server processes.
  --log-level LEVEL     Set the log level. Default is INFO.
  --debug, --no-debug   Enable debug mode with detailed logging output. Equivalent to --log-level DEBUG. If both --debug and --log-level are provided, --debug takes precedence.
  --named-server NAME COMMAND_STRING
                        Define a named stdio server. NAME is for the URL path /servers/NAME/. COMMAND_STRING is a single string with the command and its arguments (e.g., 'uvx mcp-server-fetch --timeout 10'). These servers inherit the proxy's CWD and environment from --pass-environment.
  --named-server-config FILE_PATH
                        Path to a JSON configuration file for named stdio servers. If provided, this will be the exclusive source for named server definitions, and any --named-server CLI arguments will be ignored.

SSE server options:
  --port PORT           Port to expose an SSE server on. Default is a random port
  --host HOST           Host to expose an SSE server on. Default is 127.0.0.1
  --stateless, --no-stateless
                        Enable stateless mode for streamable http transports. Default is False
  --sse-port SSE_PORT   (deprecated) Same as --port
  --sse-host SSE_HOST   (deprecated) Same as --host
  --allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]
                        Allowed origins for the SSE server. Can be used multiple times. Default is no CORS allowed.
  --expose-header HEADER
                        Headers to expose via Access-Control-Expose-Headers. Defaults to 'Mcp-Session-Id'. Can be used multiple times.

Examples:
  mcp-proxy http://localhost:8080/sse
  mcp-proxy --no-verify-ssl https://server.local/sse
  mcp-proxy --transport streamablehttp http://localhost:8080/mcp
  mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse
  mcp-proxy --client-id CLIENT_ID --client-secret CLIENT_SECRET --token-url https://auth.example.com/token http://localhost:8080/sse
  mcp-proxy --port 8080 -- your-command --arg1 value1 --arg2 value2
  mcp-proxy --named-server fetch 'uvx mcp-server-fetch' --port 8080
  mcp-proxy your-command --port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE
  mcp-proxy your-command --port 8080 --allow-origin='*'
  mcp-proxy your-command --port 8080 --allow-origin='*' --expose-header Custom-Header

示例配置文件

{
  "mcpServers": {
    "fetch": {
      "enabled": true,
      "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"
    }
  }
}

测试

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

# Run the stdio server called mcp-server-fetch behind the proxy over SSE
mcp-proxy --port=8080 uvx mcp-server-fetch &

# Connect to the SSE proxy server spawned above using another instance of mcp-proxy given the URL of the SSE server
mcp-proxy http://127.0.0.1:8080/sse

# Send CTRL+C to stop the second server

# Bring the first server to the foreground
fg

# Send CTRL+C to stop the first server

MCP-Proxy 快速上手指南

简介

mcp-proxy 是一个用于在服务器传输协议之间切换的工具。它主要支持以下两种模式：

1. stdio 到 SSE/StreamableHTTP：允许客户端（如 Claude Desktop）通过 stdio 协议连接到远程 SSE 服务器。
2. SSE 到 stdio：将本地的 stdio 服务器暴露为 SSE 服务，允许远程客户端连接。

环境准备

• 系统要求：Python 环境（推荐 Python 3.8+）。
• 网络要求：能够访问 PyPI 仓库及目标 MCP 服务器地址。
• 前置依赖：无需额外系统级依赖，确保 pip 可用即可。

安装步骤

方式一：通过 PyPI 安装（推荐）

pip install mcp-proxy

💡 提示：国内用户如遇下载缓慢，建议使用镜像源加速：

pip install mcp-proxy -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：通过 GitHub 安装最新版

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

方式三：容器化部署

支持作为 Docker 容器运行，具体镜像构建请参考官方文档中的 Extending the container image 章节。

基本使用

场景 1：连接远程 SSE 服务器 (stdio to SSE)

此模式适用于让不支持 SSE 的客户端连接远程 MCP 服务。

基础命令：

mcp-proxy http://example.io/sse

配置示例 (Claude Desktop)：

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

场景 2：暴露本地 Stdio 服务器 (SSE to stdio)

此模式允许通过 HTTP/SSE 端口访问本地运行的 MCP 服务器。

基础命令：

mcp-proxy uvx mcp-server-fetch

指定端口与主机：

mcp-proxy --port=8080 --host=0.0.0.0 uvx mcp-server-fetch

传递参数给后端服务器： 注意使用 -- 分隔符区分 proxy 参数与后端服务器参数。

mcp-proxy --port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent

多服务器管理 (Named Servers)

可通过配置文件定义多个命名服务器，并在 /servers/<server-name>/ 路径下访问。

配置文件示例：

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "transportType": "stdio"
    }
  }
}

启动命令：

mcp-proxy --port=8080 --named-server-config ./servers.json

常用命令行参数

参数	说明	示例
--port	设置监听端口	--port=8080
--host	设置监听 IP	--host=0.0.0.0
--headers	设置请求头（用于认证）	--headers Authorization 'Bearer token'
--transport	指定传输协议	--transport streamablehttp
--named-server	定义命名服务器	--named-server fetch 'uvx mcp-server-fetch'