pocketbase-mcp

一个用于 PocketBase 的 模型上下文协议 (MCP) 服务器 —— 让 Claude 等 AI 助手能够通过简洁的 Python 接口全面访问您的 PocketBase 后端。

概述

pocketbase-mcp 弥合了 LLM 与您的 PocketBase 实例之间的鸿沟。连接后，AI 助手可以通过自然语言列出集合、执行记录的 CRUD 操作、管理身份验证、处理文件上传以及管理您的数据库。

基于 FastMCP（标准的 Python MCP 框架）构建，并使用 httpx 与 PocketBase REST API 进行异步 HTTP 通信。

Related MCP server: PocketBase MCP Server

功能

• 记录 — 在任何集合中列出、获取、创建、更新、删除记录以及进行批量操作

• 集合 — 列出、检查、创建、更新和删除集合架构

• 身份验证 — 通过电子邮件/密码或 API 密钥以超级用户或普通用户身份进行身份验证

• 文件 — 生成文件令牌并检索带有可选图像转换的文件 URL

• 设置 — 读取和更新应用程序设置

• 过滤与分页 — 直接传递 PocketBase 过滤表达式、排序、展开和分页参数

• 实时感知 — 考虑到 SSE 订阅模式，为未来扩展而设计

要求

• Python 3.11+

• 正在运行的 PocketBase 实例（本地或远程）

• uv（推荐）或 pip

安装

使用 pip

pip install pocketbase-mcp

配置

服务器通过环境变量进行配置：

在 .env 文件中设置它们或直接导出：

export POCKETBASE_URL=http://127.0.0.1:8090
export POCKETBASE_SUPERUSER_EMAIL=admin@example.com
export POCKETBASE_SUPERUSER_PASSWORD=your-password

运行服务器

stdio 传输（默认 — 适用于 Claude Desktop、Claude Code 等）

pocketmcp

使用 MCP Inspector（用于开发和测试）

# Terminal 1
pocketmcp

# Terminal 2
npx @modelcontextprotocol/inspector
# Connect to: http://localhost:8000/mcp

连接到 Claude

Claude Desktop

将以下内容添加到您的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "pocketbase": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/pocketbase-mcp/server.py"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_SUPERUSER_EMAIL": "admin@example.com",
        "POCKETBASE_SUPERUSER_PASSWORD": "your-password"
      }
    }
  }
}

可用工具

记录

集合

身份验证

文件

设置

项目结构

pocketbase-mcp/
├── server.py            # MCP server entry point (FastMCP)
├── tools/
│   ├── records.py       # Record CRUD tools
│   ├── collections.py   # Collection management tools
│   ├── auth.py          # Authentication tools
│   ├── files.py         # File tools
│   └── settings.py      # Settings tools
├── client.py            # Async PocketBase HTTP client (httpx)
├── config.py            # Environment variable loading
├── pyproject.toml
└── README.md

使用示例

连接到 Claude 后，您可以通过自然语言与 PocketBase 实例进行交互：

"列出 posts 集合中所有 status = 'published' 的记录，并按 created 降序排列。"

"在 users 中创建一个新记录，姓名为 'Alice'，角色为 'editor'。"

"向我展示 products 集合的架构。"

"从 comments 中删除 ID 为 ae40239d2bc4477 的记录。"

"将 PocketBase 设置中的应用名称更新为 'My App'。"

PocketBase 兼容性

此 MCP 服务器的目标版本为 PocketBase v0.36.9+。批量 API 要求在您的 PocketBase 控制面板的 设置 → 应用程序 中明确启用。

安全说明

• 切勿将凭据提交到版本控制系统。请使用环境变量或 .env 文件（将 .env 添加到 .gitignore）。

• 对于生产环境部署，优先使用 API 密钥身份验证，而不是电子邮件/密码。

• PocketBase 中的集合 API 规则决定了经过身份验证的用户实际可以访问的内容 — pocketbase-mcp 会遵守这些规则。

贡献

欢迎贡献！在提交重大更改的拉取请求之前，请先开启一个 issue。

1. Fork 本仓库

2. 创建功能分支 (git checkout -b feat/my-feature)

3. 提交您的更改

4. 开启拉取请求

许可证

MIT 许可证。详情请参阅 LICENSE。