内容
# mcp-proxy
一个支持OAuth的MCP客户端与远程MCP服务器连接的Go语言实现代理。
## 功能特点
- **双模式运行**: 标准输入输出（默认）或HTTP/SSE服务器
- **OAuth 2.0**: 完整支持PKCE、动态客户端注册和令牌刷新
- **传输灵活性**: HTTP和SSE，具有可配置的备用策略
- **工具过滤**: 阻止特定工具暴露给客户端
## 安装
### Homebrew（macOS/Linux）
```bash
brew install mikluko/tap/mcp-proxy
```
### Go
```bash
go install github.com/mikluko/mcp-proxy/cmd/mcp-proxy@latest
```
### 二进制发布
从 [GitHub Releases](https://github.com/mikluko/mcp-proxy/releases) 下载。
## 使用
### 标准输入输出模式（默认）
MCP客户端通过标准输入输出通信的默认模式（Claude Code，Claude Desktop，Cursor，Windsurf）。
#### Claude Code
```bash
claude mcp add remote-example mcp-proxy https://remote.mcp.server/sse
```
#### Claude Desktop，Cursor，Windsurf
```json
{
"mcpServers": {
"remote-example": {
"command": "mcp-proxy",
"args": [
"https://remote.mcp.server/sse"
]
}
}
}
```
### HTTP/SSE服务器模式
作为接受MCP客户端通过SSE连接的HTTP服务器。适用于：
- 基于Web的MCP客户端
- 在多个客户端之间共享单个上游连接
- 标准输入输出不可用的环境
```bash
# 监听端口8080
mcp-proxy https://remote.mcp.server/sse --listen :8080
# 监听特定接口
mcp-proxy https://remote.mcp.server/sse --listen localhost:8080
```
客户端连接通过：
- **SSE端点**: `GET /sse` - 建立SSE流以发送服务器→客户端的消息
- **消息端点**: `POST /message` - 发送客户端→服务器的消息
### 自定义头部
```json
{
"mcpServers": {
"remote-example": {
"command": "mcp-proxy",
"args": [
"https://remote.mcp.server/sse",
"--header",
"Authorization:Bearer ${AUTH_TOKEN}"
],
"env": {
"AUTH_TOKEN": "your-token"
}
}
}
}
```
### 标志
| 标志 | 描述 | 默认值 |
| --- | --- | --- |
| `--listen`, `-l` | HTTP模式的监听地址（例如：:8080） | - |
| `--header`, `-H` | 自定义头部（KEY:VALUE） | - |
| `--transport` | 上游传输策略（http-first，sse-first，http-only，sse-only） | http-first |
| `--host` | OAuth回调主机名 | localhost |
| `--allow-http` | 允许非HTTPS连接 | false |
| `--log-level` | 日志级别（debug，info，warn，error） | info |
| `--enable-proxy` | 使用HTTP_PROXY/HTTPS_PROXY | false |
| `--ignore-tool` | 忽略匹配模式的工具（通配符） | - |
| `--auth-timeout` | OAuth回调超时（秒） | 30 |
| `--resource` | OAuth资源参数 | - |
| `--static-oauth-client-metadata` | 静态OAuth客户端元数据（JSON或@file） | - |
| `--static-oauth-client-info` | 静态OAuth客户端信息（JSON或@file） | - |
### 传输策略
控制mcp-proxy如何连接到上游服务器：
- `http-first`（默认）：尝试HTTP，404时回退到SSE
- `sse-first`：尝试SSE，405时回退到HTTP
- `http-only`/`sse-only`：无回退
### 多个实例
使用 `--resource` 隔离OAuth会话：
```json
{
"mcpServers": {
"tenant1": {
"command": "mcp-proxy",
"args": [
"https://mcp.example.com/sse",
"--resource",
"https://tenant1.example.com/"
]
},
"tenant2": {
"command": "mcp-proxy",
"args": [
"https://mcp.example.com/sse",
"--resource",
"https://tenant2.example.com/"
]
}
}
}
```
### 缓存位置
OAuth令牌和客户端注册存储在：
- **Linux**: `~/.cache/mcp-proxy/`
- **macOS**: `~/Library/Caches/mcp-proxy/`
- **Windows**: `%LocalAppData%\mcp-proxy\`
清除身份验证状态：
```bash
rm -rf ~/.cache/mcp-proxy # Linux
rm -rf ~/Library/Caches/mcp-proxy # macOS
```
---
## 架构
```
┌─────────────────────────────────────────┐
│ mcp-proxy │
│ │
┌──────────┐ │ ┌────────────┐ ┌────────────────┐ │ ┌──────────┐
│ 客户端 │──────▶│ │ 下游传输 │──────│ 代理 │─│──────▶│ 上游服务器 │
│ （标准输入 │ │ │ │ │ （过滤， │ │ │ │
│ 输出或SSE） │◀──────│ │ │◀─────│ 修改） │◀│───────│ │
└──────────┘ │ └────────────┘ └────────────────┘ │ └──────────┘
│ 标准输入输出或 HTTP或 │
│ HTTP/SSE SSE │
└─────────────────────────────────────────┘
```
### 目录结构
```
cmd/
└── mcp-proxy/ # 主CLI二进制文件
internal/
├── auth/ # OAuth 2.0实现（PKCE，令牌，回调服务器）
├── config/ # 跨平台缓存目录管理
├── proxy/ # 双向JSON-RPC代理与工具过滤
├── server/ # HTTP/SSE服务器用于下游客户端连接
├── stdio/ # 标准输入输出传输用于下游客户端连接
└── transport/ # HTTP和SSE传输用于上游连接
pkg/
└── jsonrpc/ # JSON-RPC 2.0消息类型
```
### OAuth流程
1. `auth.Provider.Initialize()` 加载现有令牌或准备身份验证
2. 在401时：启动回调服务器，打开浏览器到授权URL
3. 回调接收代码，通过PKCE交换令牌
4. 令牌持久存储到缓存目录，过期时自动刷新
### 发布
通过goreleaser + GitHub Actions发布。创建：
- 多平台二进制文件（linux/darwin/windows × amd64/arm64）
- `mikluko/homebrew-tap`中的Homebrew公式
---
## 先前的工作
- [geelen/mcp-remote](https://github.com/geelen/mcp-remote) - 原始TypeScript实现
- [sparfenyuk/mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) - Python实现
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP规范
## 许可证
[MIT](./LICENSE)
