mcp-代理
关于
mcp-proxy是一款允许您在服务器传输之间切换的工具。它支持两种模式：
- stdio 到 SSE
- SSE 到 stdio
1. stdio 到 SSE
从 stdio 运行连接到远程 SSE 服务器的代理服务器。
此模式允许 Claude Desktop 等客户端通过 SSE 与远程服务器通信，即使它本身不受支持。
1.1 配置
此模式需要将 MCP Server SSE 端点的 URL 作为程序的第一个参数传递。
参数
| 姓名 | 必需的 | 描述 | 例子 |
|---|
command_or_url | 是的 | 要连接的 MCP 服务器 SSE 端点 | http://example.io/sse |
--headers | 不 | 用于 MCP 服务器 SSE 连接的标头 | 授权‘持有者我的秘密访问令牌’ |
环境变量
| 姓名 | 必需的 | 描述 | 例子 |
|---|
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 服务器获取 |
--sse-port | 否，随机可用 | 要监听的 SSE 服务器端口 | 8080 |
--sse-host | 否，默认为127.0.0.1 | SSE 服务器将监听的主机 IP 地址 | 0.0.0.0 |
--env | 不 | 传递给 MCP stdio 服务器的附加环境变量 | 食物=酒吧 |
--pass-environment | 不 | 生成服务器时传递所有环境变量 | --no-pass-environment |
--allow-origin | 不 | 生成服务器时传递所有环境变量 | --allow-cors“*” |
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
mcp-proxy --sse-port=8080 uvx mcp-server-fetch
# Start the MCP server behind the proxy with a custom host and port
mcp-proxy --sse-host=0.0.0.0 --sse-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
mcp-proxy --sse-port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent
这将启动一个可以通过http://127.0.0.1:8080/sse连接的 MCP 服务器
安装
通过 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 --sse-port=8096 --sse-host 0.0.0.0 uvx mcp-server-fetch"
[!NOTE] 不要忘记设置--pass-environment参数，否则您将收到错误“在托管安装或搜索路径中找不到解释器”
命令行参数
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.
--debug, --no-debug Enable debug mode with detailed logging output.
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 工具来测试目标服务器。
# Run the stdio server called mcp-server-fetch behind the proxy over SSE
mcp-proxy --sse-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