portero (Andycufari)

波特罗

位于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) │
   └─────────┘  └─────────┘  └─────────┘  └─────────┘

先决条件

• Node.js 20+ （推荐LTS）
• 电报机器人 （通过创建 @植物学家)
• 你的 Telegram聊天ID （从 @用户信息机器人)

快速开始

1.克隆和安装

git clone 
cd portero
npm install

2.配置环境

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:

1. 创建Google Cloud项目 在 console.cloud.google.com
2. 启用API：Gmail API、Google Calendar API、Google Drive API
3. 创建OAuth 2.0凭据：API和服务→ 凭证→ 创建凭据→ OAuth客户端ID→ 桌面应用程序
4. 设置环境变量 在 .env:

   GOOGLE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret

1. 首次运行：工作区mcp服务器将打开浏览器以获得OAuth同意。批准请求的范围。
2. 无头/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集成，请执行以下操作：

1. 创建Notion集成 在 notion.so/my集成
2. 复制内部集成密钥 （开始于 ntn_)
3. 共享页面/数据库 使用集成：打开一个页面→ ... → 连接→ 添加您的集成
4. 设置环境变量 在 .env:

   NOTION_API_TOKEN=ntn_your-token-here

如果 NOTION_API_TOKEN 如果未设置，Portero将跳过Notion MCP并在没有它的情况下启动。默认情况下允许读取操作（搜索、检索页面/块）；写入操作（创建/更新/删除）需要Telegram批准。

6.配置条纹（可选）

要添加Stripe集成以进行支付管理，请执行以下操作：

1. 获取Stripe API密钥 从 dashboard.stripe.com/apikeys
2. 设置环境变量 在 .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 start

Docker部署

# 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审批时永远不会被阻止。

1. Claude Code调用一个工具（例如。， github/create_pull_request)
2. 网关检查策略：需要批准
3. Gateway创建 任务 （状态： pending-approval)，发送带有批准/拒绝按钮的电报消息，以及 立即返回 带有任务ID
4. 克劳德代码接收 { status: "pending-approval", taskId: "..." } 并且可以继续工作
5. 管理员通过Telegram按钮批准/拒绝
6. 如果获得批准，Portero将在后台执行该工具并存储结果
7. 克劳德代码调用 portero/check_task 使用任务ID检索结果
8. 如果还没有准备好，Claude Code可以调用 portero/check_task 稍后再来

这意味着：

• 没有超时压力——批准可以随时进行
• Claude Code在等待时保持响应
• 多个审批可以同时进行

虚拟工具

Portero将这些虚拟工具与您的MCP工具一起注入：

配置参考

数据匿名化

替换支持：

• 双向 --双向更换（假↔真实）
• 单向的 --仅替换假冒产品→真实，使用 responseReplacement 获取回复
• 区分大小写 --设置 caseSensitive: false 用于不区分大小写的匹配

权限策略

政策行动：

• allow --未经批准允许
• deny --完全封锁
• require-approval --请求电报批准（异步）

模式支持通配符：

• github/* --所有GitHub工具
• */delete_* --所有删除操作
• * --所有工具

策略优先级（最高优先）：

1. 持久规则（来自Telegram） /allow, /deny 命令）
2. 配置精确匹配（来自 config/policies.json)
3. 配置模式匹配（通配符）
4. 默认策略

临时补助金

在有限的时间内跳过审批：

/grant github/* 30m      # Grant GitHub access for 30 minutes
/grant * 1h              # Grant all access for 1 hour
/revoke                   # Revoke all grants immediately

安全注意事项

1. 承载令牌 --生成强随机令牌：

   openssl rand -hex 32

1. SSL/TLS --在生产环境中使用HTTPS（Let's Encrypt、自签名或反向代理）

1. 电报 --只有您的管理员聊天ID可以控制机器人

1. 防火墙 --将网关端口（8443）限制为授权的IP

1. 环境变量 --永不承诺 .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

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 提交拉取请求

许可证

MIT许可证-请参阅 许可证 详细信息文件

支持

• GitHub问题：\[报告错误或请求功能\]

______________________________________________________________________

专为希望隐私、安全和控制其MCP连接的Claude Code用户而设计。