使用说明

mcp代理

聚合MCP代理，可将上下文窗口使用率降低约95%，同时提供零延迟工具执行。

运作原理

mcp代理没有将所有工具直接暴露给Claude（消耗约15000多个令牌），而是只暴露了2个元工具：

get_tools_in_category -浏览可用工具的层次树
execute_tool -按路径执行任何工具

这种渐进式披露模式将上下文减少到约800个令牌，同时保持对所有工具的完全访问。

特性

特点	优点
上下文减少95%	约800个代币，而不是约15000个
后台预加载	零冷启动延迟
多运输	stdio、SSE、HTTP流媒体
优雅降级	故障服务器已禁用，不要阻止
秘密整合	可选OpenBao/Vault支持
基于源代码的安装	从git/本地源安装的MCP服务器
便携式配置	机器独立配置的可变扩展

快速开始

# 1. Clone
git clone https://github.com/IAMSamuelRodda/mcp-proxy.git
cd mcp-proxy

# 2. Create your config
cp config/config.template.json config/config.local.json

# 3. Edit config.local.json:
#    - Remove example-* entries
#    - Add your MCP servers with source URLs
#    - Keep ${VARIABLES} as-is (expanded automatically)

# 4. Bootstrap (validates config, installs servers, updates ~/.claude.json)
./scripts/bootstrap.sh

# 5. Restart Claude Code

最小配置示例

{
  "mcpProxy": {
    "hierarchyPath": "${MCP_PROXY_DIR}/hierarchy",
    "options": { "lazyLoad": true, "preloadAll": true }
  },
  "mcpServers": {
    "my-server": {
      "source": { "type": "git", "url": "https://github.com/you/my-mcp.git" },
      "transportType": "stdio",
      "command": "${MCP_SERVERS_DIR}/my-server/.venv/bin/python",
      "args": ["${MCP_SERVERS_DIR}/my-server/server.py"],
      "envFile": "${MCP_SERVERS_DIR}/my-server/.env",
      "env": {},
      "options": { "lazyLoad": true }
    }
  }
}

要点：

使用 ${MCP_SERVERS_DIR} 对于服务器路径（展开为 ~/.claude/mcp-servers)
使用 ${MCP_PROXY_DIR} 对于代理路径（展开为 ~/.claude/mcp-proxy)
添加 envFile 为了 .env 秘密或使用 env: {} 用于内联变量
每台服务器都需要 source 让bootstrap安装它

Bootstrap工作流

引导脚本编排完整的工作站设置：

./scripts/bootstrap.sh [FLAGS]

标志	行为
（无）	默认值：MCP服务器→ mcp代理
`--secure`	包括秘密基础设施（bitwarden警卫、openbao特工）
`--refresh`	仅限配置+层次结构（快速，跳过源代码更新）
`--force`	从源位置重新安装所有MCP服务器

它的作用：

验证配置 -检查缺失/占位符值
安装MCP服务器 -从git克隆，创建venvs
构建mcp代理 -编译Go二进制+结构生成器
部署 -复制到 ~/.claude/mcp-proxy/，展开变量
更新~/.claude.json -自动添加mcp代理条目
（--仅安全） 安装bitwarder警卫+openbao代理

配置

带变量的可移植配置

配置文件使用在部署时展开的变量：

{
  "mcpProxy": {
    "hierarchyPath": "${MCP_PROXY_DIR}/hierarchy"
  },
  "mcpServers": {
    "my-server": {
      "source": {
        "type": "git",
        "url": "https://github.com/user/mcp-server.git"
      },
      "command": "${MCP_SERVERS_DIR}/my-server/.venv/bin/python",
      "args": ["${MCP_SERVERS_DIR}/my-server/server.py"]
    }
  }
}

可用变量：

变量	默认值
`${MCP_SERVERS_DIR}`	`~/.claude/mcp-servers`
`${MCP_PROXY_DIR}`	`~/.claude/mcp-proxy`
`${HOME}`	用户主目录

源类型

每个MCP服务器都可以指定一个安装源：

Git源代码 （推荐）：

"source": {
  "type": "git",
  "url": "https://github.com/user/mcp-server.git"
}

本地来源 （发展）：

"source": {
  "type": "local",
  "path": "~/repos/my-mcp-server"
}

远程HTTP （无需安装）：

"transportType": "streamable-http",
"url": "https://example.com/mcp"

更新行为

源类型	更新机制
Git	`git pull` 每次引导运行时
本地	清洁替换（rm+cp）保存.vnv
远程	无需安装，直接连接

Venv重建 仅在以下情况下发生 pyproject.toml 或 requirements.txt 更改（基于哈希的检测）。

设置选项

模式	秘密存储	最适合
简单	`.env` 每台服务器的文件数	本地开发，单机
安全	OpenBao+Bitwarden	生产、多机、审计跟踪

简单模式： 使用环境变量配置MCP服务器。看 config.template.json.

安全模式： 与OpenBao、Bitwarden集成的全面秘密管理。看 docs/SECURE_SETUP.md.

Claude代码集成

添加 ~/.claude.json:

{
  "mcpServers": {
    "mcp-proxy": {
      "type": "stdio",
      "command": "~/.claude/mcp-proxy/mcp-proxy",
      "args": ["--config", "~/.claude/mcp-proxy/config.json"]
    }
  }
}

⚠️ 关键： 你的 ~/.claude.json 应包含仅这 mcp-proxy 上面的条目。

删除所有其他MCP服务器条目（cloudflare、joplin等）-代理会处理它们。

同时拥有直接服务器和mcp代理会导致重复连接和浪费上下文。

安装脚本将检测到这一点，并提示您自动清理。

建筑

┌─────────────────────────────────────────────────────┐
│                   Claude Code                        │
│                        │                             │
│                        ▼                             │
│         ┌──────────────────────────────┐            │
│         │         mcp-proxy            │            │
│         │                              │            │
│         │  2 meta-tools (~800 tokens)  │            │
│         │  • get_tools_in_category()   │            │
│         │  • execute_tool()            │            │
│         │                              │            │
│         │  Background: preload all     │            │
│         └──────────────────────────────┘            │
│                        │                             │
│     ┌──────────────────┼──────────────────┐         │
│     ▼                  ▼                  ▼         │
│ [Server 1]        [Server 2]        [Server 3]      │
│   warm              warm              warm          │
└─────────────────────────────────────────────────────┘

项目结构

mcp-proxy/
├── cmd/mcp-proxy/         # Main entry point
├── internal/
│   ├── client/            # MCP client connections
│   ├── config/            # Configuration parsing
│   ├── hierarchy/         # Tool schema management
│   ├── secrets/           # Secrets provider interface
│   └── server/            # Proxy server logic
├── structure_generator/   # Hierarchy generation tool
├── config/                # Configuration templates
│   ├── config.template.json   # Portable template with variables
│   └── config.local.json      # Your local config (gitignored)
├── scripts/
│   ├── bootstrap.sh       # Full setup (MCP servers + proxy) - recommended
│   ├── install.sh         # Binary-only (if servers already installed)
│   └── install-go.sh      # Install Go if missing
└── docs/
    └── SECURE_SETUP.md    # OpenBao + Bitwarden guide

发展

# Build
make build

# Test
go test ./...

# Deploy binary only (keeps existing config)
make deploy

# Full install (binary + config from config.local.json)
make install

# Regenerate hierarchy only
make generate-hierarchy

致谢

这个项目的灵感来自语音树实验室/懒惰mcp，为渐进式工具披露引入了优雅的2兆位模具图案。mcp代理通过后台预加载、多传输支持、secrets集成和生产弹性功能扩展了这一基础。

许可证

MIT许可证

使用说明

mcp代理

运作原理

特性

快速开始

最小配置示例

Bootstrap工作流

配置

带变量的可移植配置

源类型

更新行为

设置选项

Claude代码集成

建筑

项目结构

发展

致谢

许可证

相关 MCP

MCP聚合中间件

飞书MCP代理服务

AI代理工具管理平台

MCP协议中间件

MCP压缩代理

MCP协议中间件