Pocketbase

pocketbase-mcp

远程 MCP 服务，通过无状态 HTTP 将任意 MCP 客户端连接到 PocketBase 实例。

快速开始

使用托管实例 https://pocketbase.tokenscompany.co/mcp，或自行托管。

使用 AI Agent 安装

将此提示词复制并粘贴到 AI Agent（Claude Code、Cursor、Windsurf 等）中：

Install the PocketBase MCP server. The MCP endpoint is https://pocketbase.tokenscompany.co/mcp and the transport type is http (NOT sse). It requires X-PB-URL set to my PocketBase instance URL and either X-PB-Email + X-PB-Password (superuser credentials) or X-PB-Token (superuser auth token). Add it to my project MCP config with type "http". Then fetch https://raw.githubusercontent.com/tokenscompany/pocketbase-mcp/main/SKILL.md and save it to my project's agent instructions so you always know how to use the PocketBase tools.

claude mcp add --transport http pocketbase https://pocketbase.tokenscompany.co/mcp \
  --header "X-PB-URL: https://your-pocketbase.example.com" \
  --header "X-PB-Email: [email protected]" \
  --header "X-PB-Password: your-password"

{
  "mcpServers": {
    "pocketbase": {
      "type": "http",
      "url": "https://pocketbase.tokenscompany.co/mcp",
      "headers": {
        "X-PB-URL": "${PB_URL}",
        "X-PB-Email": "${PB_EMAIL}",
        "X-PB-Password": "${PB_PASSWORD}"
      }
    }
  }
}

{
  "mcpServers": {
    "pocketbase": {
      "url": "https://pocketbase.tokenscompany.co/mcp",
      "headers": {
        "X-PB-URL": "https://your-pocketbase.example.com",
        "X-PB-Email": "[email protected]",
        "X-PB-Password": "your-password"
      }
    }
  }
}

{
  "mcp": {
    "pocketbase": {
      "type": "remote",
      "url": "https://pocketbase.tokenscompany.co/mcp",
      "headers": {
        "X-PB-URL": "https://your-pocketbase.example.com",
        "X-PB-Email": "[email protected]",
        "X-PB-Password": "your-password"
      },
      "enabled": true
    }
  }
}

自行托管

Bun

bun install
bun run src/index.ts

服务会监听 PORT（默认值为 3000）。

Docker（GHCR）

docker pull ghcr.io/tokenscompany/pocketbase-mcp:latest
docker run -p 3000:3000 ghcr.io/tokenscompany/pocketbase-mcp:latest

或在本地构建：

docker build -t pocketbase-mcp .
docker run -p 3000:3000 pocketbase-mcp

验证镜像

每个发布到 GHCR 的镜像都包含 SLSA 来源证明。你可以验证镜像是否基于此仓库构建：

gh attestation verify oci://ghcr.io/tokenscompany/pocketbase-mcp:latest \
  --owner tokenscompany

身份验证

每个发往 POST /mcp 的请求都必须包含 X-PB-URL 和以下两种身份验证方式之一：

选项 1：电子邮件 + 密码（推荐）

服务会在每次请求时向 PocketBase 进行身份验证。无需手动管理令牌。

选项 2：令牌

手动获取令牌：

curl -X POST https://your-pb.example.com/api/admins/auth-with-password \
  -H 'Content-Type: application/json' \
  -d '{"identity":"[email protected]","password":"your-password"}'

响应中的 token 字段就是你的 X-PB-Token。如果同时提供令牌和电子邮件 + 密码，则优先使用令牌。

工具

资源

安全与隐私

此服务完全无状态——不会存储、记录或保留你的任何数据：

• 不使用数据库，不写入磁盘——每个请求都会在内存中创建一个全新的 MCP 服务和传输层，处理请求后丢弃所有内容。不会向磁盘写入任何内容。
• 不存储凭据——你的 X-PB-URL、X-PB-Token、X-PB-Email 和 X-PB-Password 标头仅在处理请求期间使用，不会持久化、缓存或记录。
• 无遥测或分析——服务不会收集任何使用数据，也不会联系任何第三方服务。
• 无会话——没有 Cookie、会话 ID，也不会在请求之间保留任何服务端状态。
• 开源——整个代码库均采用 MIT 许可证。每个 Docker 镜像都包含 SLSA 溯源证明，因此你可以验证它是直接从此代码库构建且未经修改的。
• 自行托管——如需最大程度的控制权，可运行自己的实例。该服务仅由一个容器构成，除你的 PocketBase 实例外没有任何外部依赖。

安全加固

托管公开实例时，服务还包含以下额外措施：

• SSRF 防护——会验证 X-PB-URL：仅允许 http/https 协议，并拒绝解析到私有／保留 IP 范围（127.0.0.0/8、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、169.254.0.0/16、::1、fc00::/7、fe80::/10）的主机名。

• 速率限制——按 IP 地址实施基于内存的令牌桶限流。可通过环境变量进行配置：

  变量	默认值	说明
  RATE_LIMIT_RPM	60	每个 IP 每分钟的请求数
  RATE_LIMIT_BURST	10	最大突发请求数

• CORS——Access-Control-Allow-Origin: *，并在 /mcp 上支持预检请求。

• 请求体大小限制——大于 1 MB 的请求将被拒绝，并返回 413。

端点

故障排除

“Failed to reconnect” 错误

你的 MCP 客户端配置可能使用了 "type": "sse"。此服务使用无状态的可流式 HTTP，而非服务器发送事件。请将传输类型改为 "http"：

{
  "mcpServers": {
    "pocketbase": {
      "type": "http",
      ...
    }
  }
}

对于 Claude Code CLI，添加时使用 --transport http：

claude mcp add --transport http pocketbase https://pocketbase.tokenscompany.co/mcp ...

许可证

MIT