MCP Proxy Server

Name: MCP Proxy Server
Author: ptbsare

本地服务

github.com/ptbsare开发工具19666 周前更新

代码仓库

关于 MCP Proxy Server

MCP Proxy Server 汇集多个后端 MCP 服务，并通过统一端点提供其工具和资源，适合需要集中管理 Stdio、SSE 或 Streamable HTTP 服务的运维者；可选网页管理界面和端点身份验证。

主要功能

01连接 Stdio、SSE 和 HTTP 后端
02汇集工具与资源
03将请求路由至后端服务
04可选网页管理界面
05配置工具的可见性和名称
06HTTP 端点身份验证

适用场景

01通过单一端点提供多个 MCP 服务
02禁用或重命名指定后端工具
03在浏览器中管理服务配置
04使用 API 密钥或令牌保护 HTTP 端点

MCP 相关

它通过 Stdio、SSE 和 Streamable HTTP 连接后端 MCP 服务，再通过 SSE、Streamable HTTP 或 Stdio 向 MCP 客户端提供汇集的工具和资源。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "proxy-server-ptbsare": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "pull"
      ]
    }
  }
}

启动命令docker run -i --rm pull

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

ocipullstdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

MCP 代理服务

简体中文

✨ 主要功能亮点

🌐 Web UI 管理： 通过直观的 Web 界面轻松管理所有已连接的 MCP 服务（可选，需启用）。
🔧 精细化工具控制： 启用或禁用单个工具，并通过 Web UI 覆盖工具名称和描述。
🛡️ 灵活的端点身份验证： 使用灵活的身份验证选项（Authorization: Bearer <token> 或 X-API-Key: <key>）保护基于 HTTP 的端点（/sse、/mcp）。
🔄 稳健的会话处理与并发支持：
- 改进 SSE 会话处理，支持客户端重新连接（依赖服务端发送的 endpoint 事件），并支持并发连接。
- Streamable HTTP 端点（/mcp）也支持客户端并发交互。
🚀 多功能 MCP 操作（服务与代理）：
- 作为代理运行： 连接并聚合多个不同类型的后端 MCP 服务（Stdio、SSE、Streamable HTTP）。
- 作为服务运行： 通过自身的 Streamable HTTP（/mcp）和 SSE（/sse）端点公开聚合后的功能。也可在纯 Stdio 模式下运行。
✨ 实时安装输出：直接在 Web UI 中监控 Stdio 服务的安装进度（stdout/stderr）。
✨ Web 终端：在管理 UI 中访问命令行终端，直接与服务交互（可选；由于存在安全风险，请谨慎使用）。

此服务充当模型上下文协议（MCP）资源服务的中心枢纽。它可以：

连接并管理多个后端 MCP 服务（Stdio、SSE 和 Streamable HTTP 类型）。
通过统一的 SSE 接口、Streamable HTTP 接口公开这些服务聚合后的功能（工具、资源），或作为独立的基于 Stdio 的 MCP 服务运行。
将请求路由到相应的后端服务。
根据需要聚合响应（但主要用作代理）。
支持多个 SSE 客户端同时连接，并可选用 API 密钥进行身份验证。

功能

通过代理管理资源与工具

发现并连接 config/mcp_server.json 中定义的多个 MCP 资源服务。
聚合所有已连接的活动服务中的工具和资源。
将工具调用和资源访问请求路由到正确的后端服务。
保持 URI 方案一致。

✨ 可选 Web 管理界面（`ENABLE_ADMIN_UI=true`）

提供基于浏览器的界面，用于管理代理服务配置和已连接的工具。功能包括：

服务配置：查看、添加、编辑和删除服务条目（mcp_server.json）。支持 Stdio、SSE 和 HTTP 服务类型及相关选项（类型、命令、参数、环境变量、URL、API 密钥、Bearer 令牌、安装配置）。
工具配置：查看从活动后端服务发现的所有工具。启用或禁用特定工具。覆盖每个工具的显示名称和描述（tool_config.json）。
实时重载：触发配置重载即可应用服务和工具配置变更，无需重启整个代理服务进程。
Stdio 服务安装：对于 Stdio 服务，可以在配置中定义安装命令。管理界面允许你：
- 触发这些安装命令的执行。
- 实时监控安装进度，并在界面中直接接收实时的 stdout 和 stderr 输出。
Web 终端：访问集成的基于 Web 的终端，获取代理服务运行环境的 Shell 访问权限。
- 安全警告： 此功能可授予较高权限，应极其谨慎地使用，尤其是在管理界面对外公开时。

配置

配置主要通过环境变量和位于 ./config 目录中的 JSON 文件完成。

1. 服务连接（`config/mcp_server.json`）

此文件定义代理应连接的后端 MCP 服务。

config/mcp_server.json 示例：

{
  "mcpServers": {
    "unique-server-key1": {
      "type": "stdio",
      "name": "My Stdio Server",
      "active": true,
      "command": "/path/to/server/executable",
      "args": ["--port", "1234"],
      "env": {
        "API_KEY": "server_specific_key"
      },
      "installDirectory": "/custom_install_path/unique-server-key1",
      "installCommands": [
        "git clone https://github.com/some/repo unique-server-key1",
        "cd unique-server-key1 && npm install && npm run build"
      ]
    },
    "another-sse-server": {
      "type": "sse",
      "name": "My SSE Server",
      "active": true,
      "url": "http://localhost:8080/sse",
      "apiKey": "sse_server_api_key"
    },
    "http-mcp-server": {
      "type": "http",
      "name": "My Streamable HTTP Server",
      "active": true,
      "url": "http://localhost:8081/mcp",
      "bearerToken": "some_secure_token_for_http_server"
    },
    "stdio-default-install": {
        "type": "stdio",
        "name": "Stdio Server with Default Install Path",
        "active": true,
        "command": "my_other_server",
        "installCommands": ["echo 'Installing to default location...'"]
    }
  }
}

字段：

mcpServers：（必填）一个对象，其中的每个键都是后端服务的唯一标识符。
name：（可选）服务的易读显示名称（用于管理界面）。
active：（可选，默认值：true）设为 false 可阻止代理连接到此服务。
type：（必填）指定传输类型。必须为 "stdio"、"sse" 或 "http" 之一。
command：（当 type 为 "stdio" 时必填）要执行的服务进程命令。
args：（当 type 为 "stdio" 时可选）要传递给命令的字符串参数数组。
env：（当 type 为 "stdio" 时可选）要为服务进程设置的环境变量对象（KEY: "value"）。这些变量会与代理服务的环境变量合并。
url：（当 type 为 "sse" 或 "http" 时必填）后端服务端点的完整 URL（例如，"sse" 类型的 SSE 端点或 "http" 类型的 MCP 端点）。
apiKey：（当 type 为 "sse" 或 "http" 时可选）代理连接到此特定后端服务时，在 X-Api-Key 标头中发送的 API 密钥。
bearerToken：（当 type 为 "sse" 或 "http" 时可选）连接到此特定后端服务时，在 Authorization: Bearer <token> 标头中发送的令牌。（如果同时提供 apiKey 和 bearerToken，通常会优先使用 bearerToken 连接此特定后端。）
installDirectory：（当 type 为 "stdio" 时可选）服务本身的安装绝对路径（例如，/opt/my-server-files）。供管理界面的安装功能使用。
- 如果在 mcp_server.json 中提供了此项，则使用该确切路径。
- 如果省略，则实际目录取决于 TOOLS_FOLDER 环境变量（参见“环境变量”部分）。
  - 如果设置了 TOOLS_FOLDER 且其值不为空，服务将安装在此文件夹内以服务键命名的子目录中（例如，${TOOLS_FOLDER}/<server_key>）。
  - 如果 TOOLS_FOLDER 也为空或未设置，则默认安装在代理服务工作目录下的 tools 子目录中（例如，./tools/<server_key>）。
- 确保目标安装路径的父目录（例如，TOOLS_FOLDER 或 ./tools）可由运行代理服务的用户写入。
installCommands：（Stdio 类型可选）如果目标服务目录（根据 installDirectory 确定，或使用默认值）不存在，则由管理界面的安装功能按顺序执行的 Shell 命令数组。这些命令将在目标服务安装目录的父目录中执行（例如，如果 installDirectory 解析为 /opt/tools/my-server，则命令会在 /opt/tools/ 中运行）。由于存在安全风险，请务必谨慎使用。

2. 工具配置（`config/tool_config.json`）

此文件可用于覆盖从后端服务发现的工具属性。主要通过管理界面进行管理，也可以手动编辑。

config/tool_config.json 示例：

{
  "tools": {
    "unique-server-key1__tool-name-from-server": {
      "enabled": true,
      "displayName": "My Custom Tool Name",
      "description": "A more user-friendly description."
    },
    "another-sse-server__another-tool": {
      "enabled": false
    }
  }
}

键的格式为 <server_key><separator><original_tool_name>，其中 <separator> 是 SERVER_TOOLNAME_SEPERATOR 环境变量的值（默认为 __）。
enabled：（可选，默认值：true）设为 false 可对连接代理的客户端隐藏此工具。
displayName：（可选）覆盖工具在客户端界面中的名称。
description：（可选）覆盖工具的描述。

3. 环境变量

PORT：代理服务的基于 HTTP 的端点（/sse、/mcp，以及启用时的管理界面）使用的端口。默认值：3663。注意： 仅在以会启动 HTTP 服务的模式运行时使用（例如，通过 npm run dev:sse 或 Docker 容器）。npm run dev 脚本以 Stdio 模式运行。
```
export PORT=8080
```
ALLOWED_KEYS：（可选）以逗号分隔的 API 密钥列表，用于保护代理服务的基于 HTTP 的端点（/sse、/mcp）。如果未设置 ALLOWED_KEYS 和 ALLOWED_TOKENS，这些端点将不启用身份验证。客户端必须通过 X-Api-Key 请求头或 ?key= 查询参数提供密钥。
```
export ALLOWED_KEYS="client_key1,client_key2"
```
ALLOWED_TOKENS：（可选）以逗号分隔的 Bearer Token 列表，用于保护代理服务的基于 HTTP 的端点（/sse、/mcp）。如果未设置 ALLOWED_KEYS 和 ALLOWED_TOKENS，则不启用身份验证。客户端必须通过 Authorization: Bearer <token> 请求头提供令牌。如果同时配置了 ALLOWED_KEYS 和 ALLOWED_TOKENS，将优先尝试 Bearer Token 身份验证。
```
export MCP_PROXY_SSE_ALLOWED_TOKENS="your_bearer_token_1,your_bearer_token_2"
```
ENABLE_ADMIN_UI：（可选）设为 true 可启用 Web 管理界面（仅适用于 SSE 模式）。默认值：false。
```
export ENABLE_ADMIN_UI=true
```
ADMIN_USERNAME：（启用管理界面时必需）管理界面登录用户名。默认值：admin。
ADMIN_PASSWORD：（启用管理界面时必需）管理界面登录密码。默认值：password（请修改！）。
```
export ADMIN_USERNAME=myadmin
export ADMIN_PASSWORD=aVerySecurePassword123!
```
SESSION_SECRET：（可选，建议在启用管理界面时设置）用于签署会话 Cookie 的密钥。如果未设置，则会使用默认的、较不安全的密钥，并发出警告。如果未通过环境变量提供安全密钥，首次运行时会自动生成并保存到 config/.session_secret。
```
# 建议：生成强密钥（例如，openssl rand -hex 32）
export SESSION_SECRET='your_very_strong_random_secret_here'
```
TOOLS_FOLDER：（可选）指定通过管理界面发起的 Stdio 服务安装的基础目录；当特定服务的 mcp_server.json 中未显式设置 installDirectory 时使用。
- 如果设置（例如，/custom/tools_path），未指定 installDirectory 的服务将安装到此文件夹内以服务键命名的子目录中（例如，${TOOLS_FOLDER}/<server_key>）。
- 如果未设置 TOOLS_FOLDER 或其值为空，此类服务将默认安装到代理服务工作目录下的 tools 子目录中（例如，./tools/<server_key>）。
- Dockerfile 默认将其设为 /tools。
```
export TOOLS_FOLDER=/srv/mcp_tools
```
SERVER_TOOLNAME_SEPERATOR：（可选）定义生成工具唯一键时用于组合服务名称和工具名称的分隔符（例如，server-key__tool-name）。此键供内部使用，也会写入 tool_config.json 文件。
- 默认值：__。
- 长度至少为 2 个字符，且只能包含字母（a-z、A-Z）、数字（0-9）、连字符（-）和下划线（_）。
- 如果提供的值无效，将使用默认值（__），并记录警告。
```
export SERVER_TOOLNAME_SEPERATOR="___" # 示例：使用三个下划线
```
LOGGING：（可选）控制服务输出的最低日志级别。
- 可选值（不区分大小写）：error、warn、info、debug。
- 将显示指定级别及所有更高级别的日志。
- 默认值：info。
```
export LOGGING="debug"
```
RETRY_SSE_TOOL_CALL：（可选）控制是否为 SSE 工具调用启用重试。设为 "true" 可启用，设为 "false" 可禁用。默认值：true。详情请参阅“增强可靠性功能”部分。
```
export RETRY_SSE_TOOL_CALL="true"
```
SSE_TOOL_CALL_MAX_RETRIES：（可选）SSE 工具调用的最大重试次数（不包括首次失败）。默认值：2。详情请参阅“增强可靠性功能”部分。
```
export SSE_TOOL_CALL_MAX_RETRIES="2"
```
SSE_TOOL_CALL_RETRY_DELAY_BASE_MS：（可选）SSE 工具调用重试的基础延迟（毫秒），用于指数退避。默认值：300。详情请参阅“增强可靠性功能”部分。
```
export SSE_TOOL_CALL_RETRY_DELAY_BASE_MS="300"
```
RETRY_HTTP_TOOL_CALL：（可选）控制是否在 HTTP 工具调用发生连接错误时重试。设为 "true" 可启用，设为 "false" 可禁用。默认值：true。详情请参阅“增强可靠性功能”部分。
```
export RETRY_HTTP_TOOL_CALL="true"
```
HTTP_TOOL_CALL_MAX_RETRIES：（可选）HTTP 工具调用的最大重试次数（不包括首次失败）。默认值：2。详情请参阅“增强可靠性功能”部分。
```
export HTTP_TOOL_CALL_MAX_RETRIES="3"
```
HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS：（可选）HTTP 工具调用重试的基础延迟（毫秒），用于指数退避。默认值：300。详情请参阅“增强可靠性功能”部分。
```
export HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS="500"
```
RETRY_STDIO_TOOL_CALL：（可选）控制是否在 Stdio 工具调用发生连接错误时重试（尝试重启进程）。设为 "true" 可启用，设为 "false" 可禁用。默认值：true。详情请参阅“增强可靠性功能”部分。
```
export RETRY_STDIO_TOOL_CALL="true"
```
STDIO_TOOL_CALL_MAX_RETRIES：（可选）Stdio 工具调用的最大重试次数（不包括首次失败）。默认值：2。详情请参阅“增强可靠性功能”部分。
```
export STDIO_TOOL_CALL_MAX_RETRIES="5"
```
STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS：（可选）Stdio 工具调用重试的基础延迟（毫秒），用于指数退避。默认值：300。详情请参阅“增强可靠性功能”部分。
```
export STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS="1000"
```

增强可靠性功能

MCP Proxy Server 包含多项功能，可提升自身的弹性以及与后端 MCP 服务交互的可靠性，从而确保操作更顺畅、工具执行更稳定。

1. 错误传播

代理服务会确保将后端 MCP 服务产生的错误一致地传递给请求客户端。这些错误会被格式化为标准 JSON-RPC 错误响应，使客户端能够以统一的方式处理。

2. SSE 工具调用重试

向基于 SSE 的后端服务发起 tools/call 操作时，如果底层连接断开或发生错误（包括超时），代理服务会实施重试机制。

重试机制： 如果首次 SSE 工具调用因连接错误或超时而失败，代理会尝试重新连接 SSE 后端。如果重新连接成功，代理随后会使用指数退避策略重试原始 tools/call 请求，方式与 HTTP 和 Stdio 重试类似。这意味着每次后续重试前的延迟都会呈指数增长，并会加入少量抖动（随机性）。

配置： 这些设置主要由环境变量控制。若设置了环境变量，config/mcp_server.json 中 proxy 对象下这些特定键的值将被环境变量覆盖。

RETRY_SSE_TOOL_CALL（环境变量）：
- 设置为 "true" 可启用 SSE 工具调用重试。
- 设置为 "false" 可禁用此功能。
- 默认行为： true（如果未设置环境变量、值为空或值无效）。
SSE_TOOL_CALL_MAX_RETRIES（环境变量）：
- 指定首次失败后最多重试的次数。例如，若设置为 "2"，则会先进行一次初始尝试，之后最多重试两次，总共最多尝试三次。
- 默认行为： 2（如果未设置环境变量、值为空或不是有效整数）。
SSE_TOOL_CALL_RETRY_DELAY_BASE_MS（环境变量）：
- 指数退避计算中使用的基础延迟，单位为毫秒。第 n 次重试（从 0 开始计数）前的延迟大致为 SSE_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter。
- 默认行为： 300（毫秒）（如果未设置环境变量、值为空或不是有效整数）。

示例（环境变量）：

export RETRY_SSE_TOOL_CALL="true"
export SSE_TOOL_CALL_MAX_RETRIES="3"
export SSE_TOOL_CALL_RETRY_DELAY_BASE_MS="500"

3. 工具调用的 HTTP 请求重试

对于发送到基于 HTTP 的后端服务的 tools/call 操作，代理会针对连接错误（例如“failed to fetch”、网络超时）实施重试机制。

重试机制： 如果首次 HTTP 请求因连接错误而失败，代理会使用指数退避策略重试请求。这意味着每次后续重试前的延迟都会呈指数增长，并会加入少量抖动（随机性），以防止惊群效应。

配置： 这些设置主要由环境变量控制。

RETRY_HTTP_TOOL_CALL（环境变量）：
- 设置为 "true" 可启用 HTTP 工具调用重试。
- 设置为 "false" 可禁用此功能。
- 默认行为： true（如果未设置环境变量、值为空或值无效）。
HTTP_TOOL_CALL_MAX_RETRIES（环境变量）：
- 指定首次失败后最多重试的次数。例如，若设置为 "2"，则会先进行一次初始尝试，之后最多重试两次，总共最多尝试三次。
- 默认行为： 2（如果未设置环境变量、值为空或不是有效整数）。
HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS（环境变量）：
- 指数退避计算中使用的基础延迟，单位为毫秒。第 n 次重试（从 0 开始计数）前的延迟大致为 HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter。
- 默认行为： 300（毫秒）（如果未设置环境变量、值为空或不是有效整数）。

4. 工具调用的 Stdio 连接重试

对于发往基于 Stdio 的后端服务的 tools/call 操作，代理会针对连接错误（例如进程崩溃或无响应）实施重试机制。

重试机制： 如果初始 Stdio 连接或工具调用失败，代理将尝试重启 Stdio 进程并重试请求。此机制采用与 HTTP 重试类似的指数退避策略。

配置： 这些设置主要由环境变量控制。

RETRY_STDIO_TOOL_CALL（环境变量）：
- 设置为 "true" 可启用 Stdio 工具调用重试。
- 设置为 "false" 可禁用此功能。
- 默认行为： true（如果未设置环境变量、值为空或值无效）。
STDIO_TOOL_CALL_MAX_RETRIES（环境变量）：
- 指定初始失败尝试之后的最大重试次数。例如，如果设置为 "2"，则会先进行一次初始尝试，之后最多重试两次，最多共尝试三次。
- 默认行为： 2（如果未设置环境变量、值为空或不是有效整数）。
STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS（环境变量）：
- 指数退避计算中使用的基础延迟，单位为毫秒。第 n 次重试（从 0 开始计数）前的延迟大致为 STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter。
- 默认行为： 300（毫秒）（如果未设置环境变量、值为空或不是有效整数）。

环境变量解析的一般说明：

布尔型环境变量（RETRY_SSE_TOOL_CALL、RETRY_HTTP_TOOL_CALL、RETRY_STDIO_TOOL_CALL）仅当其小写值恰好为 "true" 时才视为 true。任何其他值（包括空值或未设置）都会采用默认值；如果默认值为 false，则结果为 false（不过这些特定变量的默认值均为 true）。
数值型环境变量（SSE_TOOL_CALL_MAX_RETRIES、SSE_TOOL_CALL_RETRY_DELAY_BASE_MS、HTTP_TOOL_CALL_MAX_RETRIES、HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS、STDIO_TOOL_CALL_MAX_RETRIES、STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS）会按十进制整数解析。如果解析失败（例如，值不是数字，或者变量为空或未设置），则使用默认值。

开发

MCP Proxy Server 包含多项功能，可提升其弹性以及与后端 MCP 服务交互的可靠性，从而确保运行更顺畅、工具执行更稳定。

1. 错误传播

代理服务会确保将源自后端 MCP 服务的错误一致地传递给发起请求的客户端。这些错误会被格式化为标准 JSON-RPC 错误响应，使客户端能够以统一方式处理。

2. 工具调用的 SSE 连接重试

当向基于 SSE 的后端服务发起 tools/call 操作时，如果底层连接断开或发生错误，代理服务会自动尝试：

重新建立与 SSE 后端的连接。
如果重新连接成功，则仅重试一次原始的 tools/call 请求。

此行为有助于缓解可能暂时中断 SSE 连接的瞬时网络问题。

配置： 此功能主要由环境变量 RETRY_SSE_TOOL_CALL_ON_DISCONNECT 控制。

RETRY_SSE_TOOL_CALL_ON_DISCONNECT（环境变量）：
- 设置为 "true" 可启用自动重连和重试。
- 设置为 "false" 可禁用此功能。
- 默认行为： true（如果未设置环境变量、环境变量为空或值无效）。
- 注意：如果 config/mcp_server.json 的 proxy 下也设置了此项，则以环境变量为准。

示例（环境变量）：

export RETRY_SSE_TOOL_CALL_ON_DISCONNECT="true"

（“代理行为配置”下的 mcp_server.json JSON 示例展示了其他代理设置的位置，但此特定设置最好通过其环境变量进行管理。）

3. 工具调用的 HTTP 请求重试

对于发送到基于 HTTP 的后端服务的 tools/call 操作，代理会针对连接错误（例如，“failed to fetch”、网络超时）实施重试机制。

重试机制： 如果初始 HTTP 请求因连接错误而失败，代理会使用指数退避策略重试请求。这意味着每次后续重试前的延迟都会呈指数增长，并加入少量抖动（随机性），以避免惊群效应。

配置： 这些设置主要由环境变量控制。如果设置了环境变量，则 config/mcp_server.json 的 proxy 对象中这些特定键的值会被环境变量覆盖。

RETRY_HTTP_TOOL_CALL（环境变量）：
- 设置为 "true" 可为 HTTP 工具调用启用重试。
- 设置为 "false" 可禁用此功能。
- 默认行为： true（如果未设置环境变量、环境变量为空或值无效）。
HTTP_TOOL_CALL_MAX_RETRIES（环境变量）：
- 指定初始失败后最多重试的次数。例如，如果设置为 "2"，则会先进行一次初始尝试，之后最多重试两次，总共最多尝试三次。
- 默认行为： 2（如果未设置环境变量、环境变量为空或不是有效整数）。
HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS（环境变量）：
- 指数退避计算中使用的基础延迟，单位为毫秒。第 n 次重试（从 0 开始计数）前的延迟大约为 HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter。
- 默认行为： 300（毫秒）（如果未设置环境变量、环境变量为空或不是有效整数）。

环境变量解析的一般说明：

布尔型环境变量（RETRY_SSE_TOOL_CALL、RETRY_HTTP_TOOL_CALL、RETRY_STDIO_TOOL_CALL）仅当其小写值恰好为 "true" 时才视为 true。任何其他值（包括空值或未设置）都会使用默认值；如果默认值为 false，则结果为 false（不过这些特定变量的默认值均为 true）。
数值型环境变量（SSE_TOOL_CALL_MAX_RETRIES、SSE_TOOL_CALL_RETRY_DELAY_BASE_MS、HTTP_TOOL_CALL_MAX_RETRIES、HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS、STDIO_TOOL_CALL_MAX_RETRIES、STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS）会解析为十进制整数。如果解析失败（例如值不是数字，或变量为空／未设置），则使用默认值。

示例（环境变量）：

export RETRY_HTTP_TOOL_CALL="true"
export HTTP_TOOL_CALL_MAX_RETRIES="3"
export HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS="500"

4. 工具调用的 Stdio 连接重试

对于发往基于 Stdio 的后端服务的 tools/call 操作，代理会针对连接错误（例如进程崩溃或无响应）实施重试机制。

重试机制： 如果初始 Stdio 连接或工具调用失败，代理将尝试重启 Stdio 进程并重试请求。此机制采用与 HTTP 重试类似的指数退避策略。

配置： 这些设置主要由环境变量控制。

RETRY_STDIO_TOOL_CALL（环境变量）：
- 设置为 "true" 可启用 Stdio 工具调用重试。
- 设置为 "false" 可禁用此功能。
- 默认行为： true（如果未设置环境变量、变量值为空或值无效）。
STDIO_TOOL_CALL_MAX_RETRIES（环境变量）：
- 指定初次失败后最多重试的次数。例如，如果设置为 "2"，则会先进行一次初始尝试，之后最多重试两次，总计最多尝试三次。
- 默认行为： 2（如果未设置环境变量、变量值为空或不是有效整数）。
STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS（环境变量）：
- 指数退避计算使用的基础延迟，单位为毫秒。第 n 次重试（从 0 开始计数）前的延迟约为 STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter。
- 默认行为： 300（毫秒）（如果未设置环境变量、变量值为空或不是有效整数）。

环境变量解析的一般说明：

布尔型环境变量（RETRY_SSE_TOOL_CALL、RETRY_HTTP_TOOL_CALL、RETRY_STDIO_TOOL_CALL）的值只有在转换为小写后恰好为 "true" 时，才会被视为 true。任何其他值（包括空值或未设置）都会采用默认值；如果默认值为 false，则结果为 false（不过这些特定变量的默认值为 true）。
数值型环境变量（SSE_TOOL_CALL_MAX_RETRIES、SSE_TOOL_CALL_RETRY_DELAY_BASE_MS、HTTP_TOOL_CALL_MAX_RETRIES、HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS、STDIO_TOOL_CALL_MAX_RETRIES、STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS）会按十进制整数解析。如果解析失败（例如，值不是数字，或变量为空／未设置），则使用默认值。

开发

安装依赖：

npm install
# or yarn install

构建服务（将 TypeScript 编译为 build/ 中的 JavaScript）：

npm run build

在开发模式下运行（使用 tsx 直接执行 TS，并在发生更改时自动重启）：

# Run as a Stdio MCP server (default mode)
npm run dev

# Run as an SSE MCP server (enables SSE endpoint and Admin UI if configured)
# Ensure environment variables (PORT, ENABLE_ADMIN_UI etc.) are set as needed
ENABLE_ADMIN_UI=true npm run dev:sse

监视更改并自动重新构建（不使用 tsx 时很有用）：

npm run watch

使用 Docker 运行

提供了一个 Dockerfile。容器默认以 SSE 模式（使用 build/sse.js）运行服务，并包含所有必需的依赖项。容器内的 TOOLS_FOLDER 环境变量默认为 /tools。

推荐：使用预构建镜像（来自 GHCR）

建议使用 GitHub Container Registry 中的预构建镜像，以便更轻松地进行设置。我们提供两种类型的镜像：

标准镜像（精简版）：这是默认镜像，也是大多数用户的推荐选择。它包含 MCP Proxy Server 的核心功能。

标签：latest、<version>（例如，0.1.2）

# 拉取最新的标准镜像
docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest

# 或拉取指定版本
# docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:0.1.2

捆绑镜像（功能完整）：此镜像包含一组预装的 MCP 服务和 Playwright 浏览器依赖项。镜像体积明显更大，但开箱即用即可访问常用工具。
- 标签：<version>-bundled-mcpservers-playwright（例如，0.1.2-bundled-mcpservers-playwright）或 latest-bundled-mcpservers-playwright
```
# 拉取捆绑版本
# docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest-bundled-mcpservers-playwright
```
捆绑镜像包含以下预装组件（通过 Docker 构建参数安装）：
- PIP 包（PRE_INSTALLED_PIP_PACKAGES_ARG）：
  - mcp-server-time
  - markitdown-mcp
  - mcp-proxy
- NPM 包（PRE_INSTALLED_NPM_PACKAGES_ARG）：
  - g-search-mcp
  - fetcher-mcp
  - playwright
  - time-mcp
  - mcp-trends-hub
  - @adenot/mcp-google-search
  - edgeone-pages-mcp
  - @modelcontextprotocol/server-filesystem
  - mcp-server-weibo
  - @variflight-ai/variflight-mcp
  - @baidumap/mcp-server-baidu-map
  - @modelcontextprotocol/inspector
- 初始化命令（PRE_INSTALLED_INIT_COMMAND_ARG）：
  - playwright install --with-deps chromium

请选择最适合你需求的镜像类型。对于大多数用户，标准镜像已经足够，后端 MCP 服务可以通过 mcp_server.json 配置。

然后，运行所选的容器镜像：

docker run -d \
  -p 3663:3663 \
  -e PORT=3663 \
  -e ENABLE_ADMIN_UI=true \
  -e ADMIN_USERNAME=myadmin \
  -e ADMIN_PASSWORD=yoursupersecretpassword \
  -e ALLOWED_KEYS="clientkey1" \
  -e TOOLS_FOLDER=/my/custom_tools_volume # Optional: Override default /tools for server installations
  -v ./my_config:/mcp-proxy-server/config \
  -v /path/on/host/to/tools:/my/custom_tools_volume `# Mount a volume for TOOLS_FOLDER if overridden` \
  --name mcp-proxy-server \
  ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest

将 ./my_config 替换为包含 mcp_server.json 和可选的 tool_config.json 的主机路径。容器要求配置文件位于 /app/config。
如果通过 Admin UI 为服务安装覆盖 TOOLS_FOLDER，请确保挂载对应的卷（例如，-v /path/on/host/for_tools:/my/custom_tools_volume）。如果使用默认的 /tools（由 Dockerfile 中的 TOOLS_FOLDER 设置），则可以挂载到 /tools（例如，-v /path/on/host/to/tools_default:/tools）。
如果拉取了特定版本，请调整标签（:latest）。
根据需要使用 -e 标志设置其他环境变量。

在本地构建镜像（可选）：

docker build -t mcp-proxy-server .

（如果在本地构建，请在上面的 docker run 命令中使用 mcp-proxy-server，而不是 ghcr.io/... 镜像名称。）

与客户端一起安装和使用

此代理服务有两种主要使用方式：

1. 作为 Stdio MCP 服务： 配置 MCP 客户端（例如 Claude Desktop），使用其命令（build/index.js）直接运行代理服务。代理随后会连接 config/mcp_server.json 中定义的后端服务。

Claude Desktop（claude_desktop_config.json）配置示例：

{
  "mcpServers": {
    "mcp-proxy": {
      "name": "MCP Proxy (Aggregator)",
      "command": "/path/to/mcp-proxy-server/build/index.js",
      "env": {
         "NODE_ENV": "production", // Optional: Set environment for the proxy itself
         "TOOLS_FOLDER": "/custom/path/for/proxy/tools" // Optional: If proxy needs to install its own backends
      }
    }
  }
}

将 /path/to/mcp-proxy-server/build/index.js 替换为此代理服务项目构建后入口文件的实际路径。确保 config 目录相对于命令的运行位置正确放置；如有需要，也可以在代理自身的配置中使用绝对路径。

2. 作为 SSE 或 Streamable HTTP MCP 服务： 以会启动 HTTP 服务的模式运行代理服务（例如，使用 npm run dev:sse 或 Docker 容器）。然后，配置 MCP 客户端连接到代理对应的端点： - SSE：http://localhost:3663/sse - Streamable HTTP：http://localhost:3663/mcp

如果代理启用了身份验证（通过 ALLOWED_KEYS 或 ALLOWED_TOKENS），客户端需要提供相应的凭据。

身份验证方式（适用于 /sse 和 /mcp）：

API 密钥： 在客户端配置中提供密钥。对于 /sse 端点，支持使用 URL 查询参数 ?key=...。对于 /sse 和 /mcp，均支持使用 X-Api-Key 标头。
Bearer 令牌： 在客户端配置中设置 Authorization: Bearer <token> 标头。

Claude Desktop（claude_desktop_config.json）连接到 SSE 的配置示例：

{
  "mcpServers": {
    "my-proxy-sse": {
      "type": "sse", // Important for clients that distinguish
      "name": "MCP Proxy (SSE)",
      // If using API Key authentication, append ?key=<your_key>
      "url": "http://localhost:3663/sse?key=clientkey1"
      // If using Bearer Token authentication, the client configuration method may vary.
      // For example, some clients might support setting custom headers:
      // "headers": {
      //   "Authorization": "Bearer your_bearer_token_1"
      // }
    }
  }
}

通用 Streamable HTTP 客户端配置示例：

{
  "mcpServers": {
    "my-proxy-http": {
      "type": "http", // Or the client's specific designation
      "name": "MCP Proxy (Streamable HTTP)",
      "url": "http://localhost:3663/mcp",
      // Authentication headers would be configured according to the client's capabilities
      // e.g., "requestInit": { "headers": { "X-Api-Key": "clientkey1" } }
    }
  }
}

调试

使用 MCP Inspector 调试通信（主要用于 Stdio 模式）：

npm run inspector

此脚本会通过 Inspector 封装构建后服务（build/index.js）的运行。通过控制台输出中提供的 URL 访问 Inspector 界面。对于 SSE 模式，可以使用标准浏览器开发者工具检查网络请求。

参考

此项目最初受到 adamwattis/mcp-proxy-server 的启发，并在此基础上进行了重构。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

MCP Proxy Server

关于 MCP Proxy Server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

MCP 代理服务

✨ 主要功能亮点

功能

通过代理管理资源与工具

✨ 可选 Web 管理界面（ENABLE_ADMIN_UI=true）

配置

1. 服务连接（config/mcp_server.json）

2. 工具配置（config/tool_config.json）

3. 环境变量

增强可靠性功能

1. 错误传播

2. SSE 工具调用重试

3. 工具调用的 HTTP 请求重试

4. 工具调用的 Stdio 连接重试

开发

1. 错误传播

2. 工具调用的 SSE 连接重试

3. 工具调用的 HTTP 请求重试

4. 工具调用的 Stdio 连接重试

开发

使用 Docker 运行

与客户端一起安装和使用

调试

参考

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

✨ 可选 Web 管理界面（`ENABLE_ADMIN_UI=true`）

1. 服务连接（`config/mcp_server.json`）

2. 工具配置（`config/tool_config.json`）