波特罗
位于Claude Code和多个MCP服务器之间的自托管MCP（模型上下文协议）网关，提供：
- MCP聚合 --连接多个MCP并将其作为一个统一的端点公开
- 数据匿名化 --双向伪造↔隐私的真实数据替换
- 异步2FA审批 --具有任务跟踪功能的非阻塞电报审批流
- 权限策略 --允许/拒绝/要求每个工具的批准
- 远程访问 --HTTPS端点可从任何地方访问
建筑
┌─────────────────────────────────────────────────────────────┐
│ TELEGRAM BOT │
│ /status, /grant, /revoke, /tasks, approval callbacks │
│ Executes approved tasks asynchronously │
└─────────────────────┬───────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────────┐
│ PORTERO │
│ ┌────────────────────────────────────────────────────────┐│
│ │ HTTP Server (Express) ││
│ │ - POST /mcp/message (JSON-RPC, Bearer auth) ││
│ │ - GET /health ││
│ └────────────────────────────────────────────────────────┘│
│ ┌────────────────────────────────────────────────────────┐│
│ │ Middleware Pipeline ││
│ │ 1. Anonymization (fake→real on requests) ││
│ │ 2. Policy Check (allow/deny/require-approval) ││
│ │ 3. If approval needed → create task, return pending ││
│ │ 4. If allowed → route to child MCP immediately ││
│ │ 5. Anonymization (real→fake on responses) ││
│ └────────────────────────────────────────────────────────┘│
│ ┌────────────────────────────────────────────────────────┐│
│ │ Task Store (data/tasks.json) ││
│ │ pending-approval → approved → executing → completed ││
│ └────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
│ stdio
┌─────────────┼─────────────┬─────────────┐
▼ ▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ MCP 1 │ │ MCP 2 │ │ MCP 3 │ │ MCP 4 │
│(github) │ │(filesys)│ │(google) │ │(stripe) │
└─────────┘ └─────────┘ └─────────┘ └─────────┘先决条件
快速开始
1.克隆和安装
git clone
cd portero
npm install2.配置环境
cp .env.example .env
# Edit .env with your settings中的必需设置 .env:
# Generate a secure token
BEARER_TOKEN=$(openssl rand -hex 32)
# Get from @BotFather
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
# Get from @userinfobot
TELEGRAM_ADMIN_CHAT_ID=123456789
# Your real info (for anonymization)
REAL_NAME="Your Name"
REAL_EMAIL="your@email.com"3.配置MCP服务器
编辑 config/mcps.json 定义要连接的MCP服务器：
{
"mcps": [
{
"name": "filesystem",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
"env": {}
},
{
"name": "github",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
]
}4.配置谷歌工作区（可选）
通过添加Gmail、日历和Drive集成 工作区mcp:
- 创建Google Cloud项目 在 console.cloud.google.com
- 启用API：Gmail API、Google Calendar API、Google Drive API
- 创建OAuth 2.0凭据：API和服务→ 凭证→ 创建凭据→ OAuth客户端ID→ 桌面应用程序
- 设置环境变量 在
.env:
GOOGLE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret- 首次运行：工作区mcp服务器将打开浏览器以获得OAuth同意。批准请求的范围。
- 无头/Docker：在本地运行一次以完成OAuth流，然后将令牌缓存复制到容器中。
如果 GOOGLE_OAUTH_CLIENT_ID 和 GOOGLE_OAUTH_CLIENT_SECRET 如果未设置，Portero将跳过Google MCP并在没有它的情况下开始。
Google工具显示为 google/send_email, google/list_events, google/search_files等等。写入操作（发送、创建、删除）需要Telegram批准；默认情况下允许读取。看 config/policies.json 查看完整列表。
5.配置通知（可选）
要添加Notion集成，请执行以下操作：
- 创建Notion集成 在 notion.so/my集成
- 复制内部集成密钥 （开始于
ntn_) - 共享页面/数据库 使用集成：打开一个页面→ ... → 连接→ 添加您的集成
- 设置环境变量 在
.env:
NOTION_API_TOKEN=ntn_your-token-here如果 NOTION_API_TOKEN 如果未设置，Portero将跳过Notion MCP并在没有它的情况下启动。默认情况下允许读取操作（搜索、检索页面/块）；写入操作（创建/更新/删除）需要Telegram批准。
6.配置条纹（可选）
要添加Stripe集成以进行支付管理，请执行以下操作：
- 获取Stripe API密钥 从 dashboard.stripe.com/apikeys
- 设置环境变量 在
.env:
STRIPE_API_KEY=sk_test_your-key-here如果 STRIPE_API_KEY 如果未设置，Portero将跳过Stripe MCP并在没有它的情况下启动。
默认策略：
- 阅读工具 （列出/获取客户、发票、付款、订阅、余额）--
allow - 编写工具 （创建客户、发票、付款、退款、订阅）--
require-approval
7.配置数据匿名化
编辑 config/replacements.json 定义假货↔真实映射：
{
"replacements": [
{
"fake": "John Doe",
"real": "${REAL_NAME}",
"bidirectional": true
},
{
"fake": "john@example.com",
"real": "${REAL_EMAIL}",
"bidirectional": true,
"caseSensitive": false
}
]
}8.配置策略
编辑 config/policies.json 要设置权限规则，请执行以下操作：
{
"policies": {
"github/create_issue": "allow",
"github/create_pull_request": "require-approval",
"filesystem/write_file": "require-approval",
"filesystem/read_file": "allow",
"filesystem/delete_file": "deny",
"*": "allow"
},
"defaultPolicy": "allow"
}9.生成SSL证书（可选）
./scripts/generate-certs.sh或者跳过SSL进行本地测试（使用HTTP）。
10.启动网关
# Development mode (with hot reload)
npm run dev
# Production mode
npm run build
npm startDocker部署
# Build and start with docker-compose
docker-compose up -d
# View logs
docker-compose logs -f
# Stop
docker-compose down从克劳德代码连接
添加到您的Claude Code MCP配置中：
{
"mcpServers": {
"portero": {
"transport": "http",
"url": "https://your-server:8443/mcp/message",
"headers": {
"Authorization": "Bearer your-bearer-token-here"
}
}
}
}添加到Claude Code系统提示：
Your identity:
- Name: John Doe
- Email: john@example.com
Use these when asked for personal information.电报机器人命令
运行后，向您的机器人发送消息：
/status-显示已连接的MCP、活动授权、待批准- `/grant
-授予临时访问权限 - 示例： /grant github/* 30m, /grant * 1h`
/revoke-撤销所有有效拨款- `/allow
` -持续允许使用工具/模式（无需批准）
- `/deny
` -持续否认一种工具/模式
/rules-列出持久规则/unrule-删除持久规则/tasks-显示按状态分组的最近任务/pending-显示待处理的审批请求/logs-显示最近的审核日志/help-显示所有命令
异步审批的工作原理
Portero使用完全异步的审批流——HTTP请求在等待Telegram审批时永远不会被阻止。
- Claude Code调用一个工具（例如。，
github/create_pull_request) - 网关检查策略：需要批准
- Gateway创建 任务 （状态：
pending-approval)，发送带有批准/拒绝按钮的电报消息，以及 立即返回 带有任务ID - 克劳德代码接收
{ status: "pending-approval", taskId: "..." }并且可以继续工作 - 管理员通过Telegram按钮批准/拒绝
- 如果获得批准，Portero将在后台执行该工具并存储结果
- 克劳德代码调用
portero/check_task使用任务ID检索结果 - 如果还没有准备好，Claude Code可以调用
portero/check_task稍后再来
这意味着：
- 没有超时压力——批准可以随时进行
- Claude Code在等待时保持响应
- 多个审批可以同时进行
虚拟工具
Portero将这些虚拟工具与您的MCP工具一起注入：
| 工具 | 说明 |
|---|---|
portero/search_tools | 按关键字或类别搜索可用工具 |
portero/call | 按全名调用任何工具（适用于非固定工具） |
portero/check_task | 检查待处理或已完成异步任务的状态/结果 |
portero/list_tasks | 使用可选状态筛选器列出最近的任务 |
配置参考
数据匿名化
替换支持：
- 双向 --双向更换（假↔真实）
- 单向的 --仅替换假冒产品→真实，使用
responseReplacement获取回复 - 区分大小写 --设置
caseSensitive: false用于不区分大小写的匹配
权限策略
政策行动：
allow--未经批准允许deny--完全封锁require-approval--请求电报批准（异步）
模式支持通配符：
github/*--所有GitHub工具*/delete_*--所有删除操作*--所有工具
策略优先级（最高优先）：
- 持久规则（来自Telegram）
/allow,/deny命令） - 配置精确匹配（来自
config/policies.json) - 配置模式匹配（通配符）
- 默认策略
临时补助金
在有限的时间内跳过审批：
/grant github/* 30m # Grant GitHub access for 30 minutes
/grant * 1h # Grant all access for 1 hour
/revoke # Revoke all grants immediately安全注意事项
- 承载令牌 --生成强随机令牌：
openssl rand -hex 32- SSL/TLS --在生产环境中使用HTTPS（Let's Encrypt、自签名或反向代理）
- 电报 --只有您的管理员聊天ID可以控制机器人
- 防火墙 --将网关端口（8443）限制为授权的IP
- 环境变量 --永不承诺
.env转git
发展
项目结构
portero/
├── src/
│ ├── index.ts # Entry point
│ ├── config/ # Config loader & types
│ ├── gateway/ # HTTP server & MCP handler
│ ├── mcp/ # MCP client management
│ ├── middleware/ # Anonymizer, policy, approval
│ ├── telegram/ # Telegram bot & admin store
│ ├── db/ # File-backed JSON storage
│ ├── storage/ # Atomic file operations & paths
│ └── utils/ # Logger, crypto
├── config/ # JSON config files
├── data/ # Runtime data (auto-created)
└── scripts/ # Helper scripts构建命令
npm run dev # Development with hot reload
npm run build # Compile TypeScript
npm start # Start production build存储
文件支持的JSON存储 ./data/:
approvals.json--遗留审批（保留以保持向后兼容性）tasks.json--异步任务跟踪（待定→ 批准→ 执行→ 已完成）grants.json--临时访问许可rules.json--持久策略规则（来自/allow、/dense命令）audit.ndjson--仅附加审核日志（NDJSON格式）
故障排除
网关无法启动
- 检查Node.js版本：
node -v（应该是20+） - 验证
.env文件存在并且包含所有必需的变量 - 检查登录
./logs/combined.log
MCP连接失败
- 验证MCP命令是否正确
config/mcps.json - 检查MCP是否安装：
npx -y @modelcontextprotocol/server-github --version - 检查环境变量是否已设置（例如。，
GITHUB_TOKEN) - 自动跳过缺少env变量的MCP（非阻塞）
Telegram机器人没有响应
- 验证机器人令牌是否正确
- 检查管理员聊天ID是否与您的Telegram ID匹配
- 确保机器人已启动
/start
Claude Code无法连接
- 验证Claude Code配置中的承载令牌是否匹配
- 如果使用HTTPS，请检查SSL证书
- 测试用
curl:
curl -X POST https://localhost:8443/health贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 提交拉取请求
许可证
MIT许可证-请参阅 许可证 详细信息文件
支持
- GitHub问题：\[报告错误或请求功能\]
______________________________________________________________________
专为希望隐私、安全和控制其MCP连接的Claude Code用户而设计。