内容
# mcp-stdio-proxy
一个小巧、依赖轻量的代理，允许任何本地STDIO的[模型上下文协议](https://modelcontextprotocol.io)客户端通过HTTP与远程MCP服务器通信，包括需要OAuth 2.1身份验证的服务器。
它是适用于仍仅支持stdio的客户端（如Cursor、Claude Desktop、Windsurf、VS Code、Cline、Continue、Highlight、Augment等）的缺失环节，当您希望将它们指向基于HTTP的MCP服务器时。
```
┌──────────────┐ stdio ┌────────────────────┐ HTTP / SSE ┌──────────────────┐
│ MCP客户端 │ ─────────────▶ │ mcp-stdio-proxy │ ─────────────────▶ │ 远程MCP服务器 │
│ (IDE/代理) │ ◀───────────── │ (此软件包) │ ◀───────────────── │ 服务器 │
└──────────────┘ └────────────────────┘ └──────────────────┘
```
---
## ✨ 功能特点
- **STDIO ↔ HTTP/SSE桥接** — 在stdio传输和远程MCP端点之间传输JSON-RPC消息。
- **可流式HTTP和SSE** — 支持MCP规范的现代流式HTTP和传统SSE传输。
- **OAuth 2.1与PKCE** — 打开浏览器，运行本地回调服务器，持久化令牌，自动刷新。
- **静态API密钥** — 传递`API_KEY`环境变量以使用承载身份验证代替OAuth。
- **自动重新连接** — 在连接断开时透明地重新连接远程服务器并重放`initialize`请求。
- **通过`npx`的单个二进制文件** — 无需安装。
---
## 🚀 快速开始
```bash
npx -y mcp-stdio-proxy <https://您的mcp服务器网址>
```
代理从标准输入读取JSON-RPC，将其转发到远程服务器，并将响应写回标准输出。这正是每个MCP客户端期望从stdio服务器获得的结果，因此您可以将其放入任何支持`command` + `args`的客户端配置中。
如果远程服务器需要OAuth，您的默认浏览器将在您第一次运行代理时打开。令牌缓存在磁盘上（在您的操作系统用户配置目录下），因此后续运行将是静默的。
### 环境变量
| 变量名 | 目的 |
|-------------------|-------------------------------------------------------------------------|
| `MCP_SERVER_URL` | 远程URL（如果未给出位置参数，则使用）。 |
| `API_KEY` | 如果设置，则发送为`Authorization: Bearer <API_KEY>`而不是OAuth。 |
| `DEBUG` | 设置为`true`以将详细的JSON-RPC流量打印到标准错误。 |
---
## 🔌 客户端配置
将以下代码段之一放入客户端的MCP配置中。将URL替换为您自己的远程MCP服务器。
### Cursor (`~/.cursor/mcp.json`)
```json
{
"mcpServers": {
"我的远程服务器": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://您的mcp服务器网址"]
}
}
}
```
### Claude Desktop（设置 → 开发者 → *编辑配置*)
```json
{
"mcpServers": {
"我的远程服务器": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://您的mcp服务器网址"]
}
}
}
```
### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
```json
{
"mcpServers": {
"我的远程服务器": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://您的mcp服务器网址"]
}
}
}
```
### VS Code（`.vscode/mcp.json`)
```json
{
"servers": {
"我的远程服务器": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://您的mcp服务器网址"]
}
}
}
```
### Cline / Continue / 其他客户端（`cline_mcp_settings.json`等）
```json
{
"mcpServers": {
"我的远程服务器": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://您的mcp服务器网址"],
"disabled": false,
"autoApprove": []
}
}
}
```
### 静态API密钥
```json
{
"mcpServers": {
"我的远程服务器": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://您的mcp服务器网址"],
"env": { "API_KEY": "sk-..." }
}
}
}
```
---
## 🐳 Docker
```bash
docker build -t mcp-stdio-proxy .
docker run --rm -i mcp-stdio-proxy https://您的mcp服务器网址
```
对于OAuth流程，您需要`--network=host`（Linux）或公开回调端口，以便浏览器可以访问它。对于大多数用户，在主机上通过`npx`运行更简单。
---
## 🛠️ 开发
```bash
npm install
npm run build
node dist/index.js https://您的mcp服务器网址
```
运行并设置`DEBUG=true`以在标准错误中查看每个JSON-RPC帧。
---
## 📄 许可证
MIT — 请参阅[LICENSE](./LICENSE)。
