mcp-代理
关于
mcp-proxy是一款允许您在服务器传输之间切换的工具。它支持两种模式：
- stdio 到 SSE/StreamableHTTP
- SSE 到 stdio
1. stdio 到 SSE/StreamableHTTP
从 stdio 运行连接到远程 SSE 服务器的代理服务器。
此模式允许 Claude Desktop 等客户端通过 SSE 与远程服务器通信，即使它本身不受支持。
1.1 配置
此模式需要提供 MCP 服务器的 SSE 端点 URL 作为程序的第一个参数。如果服务器使用 Streamable HTTP 传输，请确保在mcp-proxy端通过传递--transport=streamablehttp来强制执行该传输方式。
参数
| 姓名 | 必需的 | 描述 | 例子 |
|---|
command_or_url | 是的 | 要连接的 MCP 服务器 SSE 端点 | http://example.io/sse |
--headers | 不 | 用于 MCP 服务器 SSE 连接的标头 | 授权‘持有者我的秘密访问令牌’ |
--transport | 不 | 决定连接到 MCP 服务器时使用的传输协议。可以是“sse”或“streamablehttp”。 | 流式传输HTTP |
环境变量
| 姓名 | 必需的 | 描述 | 例子 |
|---|
API_ACCESS_TOKEN | 不 | 可以代替--headers Authorization 'Bearer <API_ACCESS_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
运行一个代理服务器，公开一个连接到本地 stdio 服务器的 SSE 服务器。
这允许远程连接到本地 stdio 服务器。mcp mcp-proxy会打开一个端口来监听 SSE 请求，并创建一个本地 stdio 服务器来处理 MCP 请求。
2.1 配置
此模式需要设置--sse-port参数。可以设置--sse-host参数来指定 SSE 服务器将监听的主机 IP 地址。可以使用--env参数将其他环境变量传递给本地 stdio 服务器。本地 stdio 服务器的命令行参数必须在--分隔符后传递。
参数
| 姓名 | 必需的 | 描述 | 例子 |
|---|
command_or_url | 是的 | 启动 MCP stdio 服务器的命令 | uvx mcp 服务器获取 |
--port | 否，随机可用 | MCP 服务器监听的端口 | 8080 |
--host | 否，默认为127.0.0.1 | MCP 服务器监听的主机 IP 地址 | 0.0.0.0 |
--env | 不 | 传递给 MCP stdio 服务器的附加环境变量。可多次使用。 | 福酒吧 |
--cwd | 不 | 传递给 MCP stdio 服务器进程的工作目录。 | /tmp |
--pass-environment | 不 | 生成服务器时传递所有环境变量 | --no-pass-environment |
--allow-origin | 不 | SSE 服务器允许的来源。可多次使用。默认不允许 CORS。 | --allow-origin“*” |
--stateless | 不 | 为可流式传输的 http 传输启用无状态模式。默认值为 False | --无状态 |
--named-server NAME COMMAND_STRING | 不 | 定义一个名为 stdio 服务器。 | --named-server 获取‘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-proxy服务器并连接到本地 MCP 服务器：
# Start the MCP server behind the proxy
mcp-proxy uvx mcp-server-fetch
# Start the MCP server behind the proxy with a custom port
# (deprecated) mcp-proxy --sse-port=8080 uvx mcp-server-fetch
mcp-proxy --port=8080 uvx mcp-server-fetch
# Start the MCP server behind the proxy with a custom host and port
# (deprecated) 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
# Start the MCP server behind the proxy with a custom user agent
# Note that the `--` separator is used to separate the `mcp-proxy` arguments from the `mcp-server-fetch` arguments
# (deprecated) mcp-proxy --sse-port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent
mcp-proxy --port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent
# Start multiple named MCP servers behind the proxy
mcp-proxy --port=8080 --named-server fetch 'uvx mcp-server-fetch' --named-server fetch2 'uvx mcp-server-fetch'
# Start multiple named MCP servers using a configuration file
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"
],
"transportType": "stdio"
}
}
}
mcpServers ：一个字典，其中每个键都是服务器名称（用于 URL 路径，例如/servers/fetch/ ），值是定义服务器的对象。command ：（必需）为 stdio 服务器执行的命令。args ：（可选）命令的参数列表。默认为空列表。enabled ：（可选）如果设置为false ，则跳过此服务器定义。默认为true 。timeout和transportType ：这些字段存在于标准 MCP 客户端配置中，但在加载命名服务器时， mcp-proxy目前会忽略它们。传输类型隐式为“stdio”。
安装
通过 Smithery 安装
要通过Smithery自动为 Claude Desktop 安装 MCP Proxy：
npx -y @smithery/cli install mcp-proxy --client claude
通过 PyPI 安装
该软件包的稳定版本可在 PyPI 仓库中找到。您可以使用以下命令安装它：
# 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 -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --help
故障排除
- 问题：Claude Desktop 无法启动服务器：日志中的 ENOENT 代码解决方案：尝试使用二进制文件的完整路径。为此，请打开终端并运行命令
where 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 [ "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] [-H KEY VALUE] [--transport {sse,streamablehttp}] [-e KEY VALUE] [--cwd CWD] [--pass-environment | --no-pass-environment]
[--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 ...]
Start the MCP proxy.
It can run as an SSE client (connecting to a remote SSE server and exposing stdio).
Or, it can run as an SSE server (connecting to local stdio command(s) and exposing them over SSE).
When running as an SSE server, it can proxy a single default stdio command or multiple named stdio commands (defined via CLI or a config file).
positional arguments:
command_or_url Command or URL.
If URL (http/https): Runs in SSE/StreamableHTTP client mode.
If command string: Runs in SSE server mode, this is the default stdio server.
If --named-server or --named-server-config is used, this can be omitted if no default server is desired.
options:
-h, --help show this help message 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.
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.
--debug, --no-debug Enable debug mode with detailed logging output.
--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. Can be specified multiple times. Ignored if --named-server-config is used.
--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.
Examples:
mcp-proxy http://localhost:8080/sse
mcp-proxy --transport streamablehttp http://localhost:8080/mcp
mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse
mcp-proxy --port 8080 -- my-default-command --arg1 value1
mcp-proxy --port 8080 --named-server fetch1 'uvx mcp-server-fetch' --named-server tool2 'my-custom-tool --verbose'
mcp-proxy --port 8080 --named-server-config /path/to/servers.json
mcp-proxy --port 8080 --named-server-config /path/to/servers.json -- my-default-command --arg1
mcp-proxy --port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE -- my-default-command
mcp-proxy --port 8080 --allow-origin='*' -- my-default-command
示例配置文件
{
"mcpServers": {
"fetch": {
"enabled": true,
"timeout": 60,
"command": "uvx",
"args": [
"mcp-server-fetch"
],
"transportType": "stdio"
},
"github": {
"timeout": 60,
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"transportType": "stdio"
}
}
}
测试
使用mcp-server-fetch服务器运行mcp-proxy服务器来检查它。您可以使用inspector 工具来测试目标服务器。
# 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