MCP Proxy Nodejs

🚀 MCP SSE 代理

MCP SSE 代理是一个模型上下文协议（MCP）服务器，作为代理桥梁，将基于标准输入输出（STDIO）的 MCP 客户端与基于服务器发送事件（SSE）的 MCP 服务器连接起来。这使得仅支持 STDIO 传输的 MCP 客户端能够连接到使用 SSE 传输的远程 MCP 服务器。

🚀 快速开始

MCP SSE 代理在两种不同的 MCP 传输协议之间架起了桥梁：

• STDIO 传输：供本地 MCP 客户端（如 Claude Desktop）使用。
• SSE 传输：供可通过 HTTP/HTTPS 访问的远程 MCP 服务器使用。

此代理允许你从仅支持基于 STDIO 的 MCP 连接的应用程序中使用暴露 SSE 端点的远程 MCP 服务器。

✨ 主要特性

• 全面支持 MCP 协议：代理所有 MCP 功能，包括：
  • 工具（列出和调用）
  • 资源（列出和读取）
  • 资源模板（列出）
  • 提示（列出和获取）
• 支持身份验证：为 SSE 端点提供可选的 API 密钥身份验证。
• 错误处理：具备全面的错误处理和详细的日志记录。
• 优雅关闭：在进程终止时进行适当的清理。
• 可配置：可通过命令行参数或环境变量进行灵活配置。

📦 安装指南

前提条件

• Node.js >= 18.0.0
• npm 或 yarn

安装步骤

1. 克隆或下载此仓库。
2. 安装依赖项：

npm install

💻 使用示例

命令行参数

node server/index.js <SERVER_NAME> <SSE_URL> [API_KEY]

参数说明：

• SERVER_NAME：MCP 服务器的显示名称。
• SSE_URL：远程 SSE MCP 服务器端点的 URL。
• API_KEY：（可选）用于身份验证的 API 密钥。

示例：

node server/index.js "My Remote MCP Server" "https://api.example.com/mcp/sse" "your-api-key"

环境变量

你也可以使用环境变量：

export SERVER_NAME="My Remote MCP Server"
export SSE_URL="https://api.example.com/mcp/sse"
export API_KEY="your-api-key"
node server/index.js

MCP 客户端配置

要将此代理与像 Claude Desktop 这样的 MCP 客户端一起使用，请在你的 MCP 配置中添加以下内容：

{
  "mcpServers": {
    "remote-server": {
      "command": "node",
      "args": [
        "/path/to/mcp-proxy-node/server/index.js",
        "Remote Server Name",
        "https://your-remote-server.com/mcp/sse",
        "your-api-key"
      ]
    }
  }
}

身份验证

代理支持 Bearer 令牌身份验证。当提供 API 密钥时，它将在 HTTP 请求中作为 Authorization: Bearer <API_KEY> 头发送，并在 EventSource 连接中作为身份验证头。

创建桌面扩展（.dxt）

此 MCP 代理可以打包为桌面扩展，以便在 Claude Desktop 和其他支持 MCP 的应用程序中一键安装。

完整指南请参阅：Desktop Extensions: One-click MCP server installation for Claude Desktop

前提条件

安装依赖项：

npm install

安装 DXT CLI 工具：

npm install -g @anthropic-ai/dxt

创建 DXT 文件的步骤

1. 初始化 DXT 配置（如有需要）：

dxt init

注意：此项目已包含 manifest.json 文件，因此可能不需要初始化。

2. 验证清单文件：

dxt validate

3. 打包扩展：

dxt pack

4. 测试扩展：

• 该命令将生成一个 .dxt 文件。
• 将 .dxt 文件拖到 Claude Desktop 的设置窗口中。
• 点击“安装”以测试扩展。

快速安装（可选）

如果你不想自己构建扩展，可以直接将预构建的 mcp-proxy-node.dxt 文件拖到 Claude Desktop 的设置窗口中进行立即安装。

截图

MCP SSE 代理扩展在 Claude Desktop 中安装后的样子。用户可以通过直观的界面轻松配置服务器名称、SSE URL 和 API 密钥。

🔧 技术细节

架构

MCP 客户端（STDIO） ←→ MCP SSE 代理 ←→ 远程 MCP 服务器（SSE）

代理由两个主要组件组成：

1. MCP 服务器：接受来自本地 MCP 客户端的 STDIO 连接。
2. MCP 客户端：连接到远程 SSE MCP 服务器。

传输协议

• 输入：STDIO 传输（标准输入/输出）。
• 输出：SSE 传输（通过 HTTP/HTTPS 的服务器发送事件）。

错误处理

代理包含全面的错误处理：

• 与远程 SSE 服务器的连接失败。
• 无效的 URL 格式。
• 身份验证错误。
• 请求/响应解析错误。
• 当远程功能不可用时进行优雅降级。

日志记录

通过 console.error() 提供详细的日志记录，用于调试：

• 连接状态。
• 请求/响应详细信息。
• 带有堆栈跟踪的错误信息。
• 性能指标。

📚 详细文档

MCPSSEProxy 类

构造函数

new MCPSSEProxy(sseUrl, apiKey, serverName)

• sseUrl（字符串）：SSE MCP 服务器的 URL。
• apiKey（字符串，可选）：用于身份验证的 API 密钥。
• serverName（字符串）：代理服务器的显示名称。

方法

• initialize()：初始化客户端和服务器连接。
• run()：启动代理服务器。
• close()：优雅地关闭代理。
• setupProxyHandlers()：配置请求处理程序。

项目结构

mcp-proxy-node/
├── server/
│   └── index.js          # 主代理服务器实现
├── package.json          # 项目配置和依赖项
├── manifest.json         # 用于 MCP 客户端集成的 DXT 清单
├── favicon.png          # 项目图标
└── README.md            # 本文件

依赖项

• @modelcontextprotocol/sdk：官方的 Node.js MCP SDK。

贡献代码

1. 分叉仓库。
2. 创建功能分支。
3. 进行更改。
4. 彻底测试。
5. 提交拉取请求。

故障排除

常见问题

1. 连接被拒绝

• 验证 SSE URL 是否正确且可访问。
• 检查远程服务器是否正在运行。
• 确保防火墙/网络设置允许连接。

2. 身份验证错误

• 验证 API 密钥是否正确。
• 检查远程服务器是否需要身份验证。
• 确保 API 密钥格式符合服务器要求。

3. 没有可用的工具/资源

• 检查远程服务器是否实际提供工具/资源。
• 验证远程服务器是否正常响应。
• 检查代理日志中的错误消息。

4. 性能问题

• 监控到远程服务器的网络延迟。
• 检查远程服务器是否有速率限制。
• 对于高频使用情况，考虑使用连接池。

调试

通过查看控制台输出启用详细日志记录。代理会记录：

• 连接尝试和结果。
• 请求/响应详细信息。
• 带有堆栈跟踪的错误消息。
• 性能计时。

加入我们的社区获取帮助和更新

👉 Slack 社区 - AI in Ads

查看我们的其他项目

👉 Facebook Ads MCP - Facebook Ads MCP 👉 Google Ads MCP - Google Ads MCP

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

如有问题和疑问：

• 查看上述故障排除部分。
• 查看控制台日志以获取错误详细信息。
• 确保你的 Node.js 版本符合要求（>= 18.0.0）。
• 验证远程 SSE 服务器是否与 MCP 协议兼容。

兼容性

• Node.js：>= 18.0.0
• MCP 协议：与 MCP SDK v1.13.2+ 兼容
• 平台：macOS、Windows、Linux
• Claude Desktop：>= 0.10.0

💖 为 MCP 社区精心打造