Fully Capable Pocketbase Mcp Server

PocketBase MCP 服务

一个全面的模型上下文协议（MCP）服务，提供用于管理 PocketBase 实例的工具。此服务可让大模型通过标准化协议与 PocketBase 数据库交互。

概览

此 MCP 服务将 PocketBase 功能作为工具开放，供任何兼容 MCP 的客户端使用（例如 Claude Desktop、Cursor 或其他大模型应用）。它提供对 PocketBase 功能的全面访问，包含 60 多种工具，涵盖所有主要操作。

功能

集合管理

• 列出、获取、创建、更新和删除集合
• 批量导入／导出集合
• 全面支持架构管理

记录操作

• 支持筛选、排序和分页的 CRUD 操作
• 使用 getFullList 获取所有记录，无需分页
• 使用 getFirstListItem 查找第一个匹配的记录
• 支持字段选择和关联扩展的高级查询
• 支持批量操作，提升批量处理效率

身份验证与用户管理

• 多种身份验证方式：密码、OAuth2、OTP
• 完整支持身份验证流程：注册、登录、密码重置、电子邮件验证
• 电子邮件更改功能
• 身份验证令牌刷新
• 列出集合可用的身份验证方式

文件管理

• 生成支持缩略图的文件 URL
• 生成私有文件令牌
• 支持强制下载

系统操作

• 健康状态监控
• 设置管理
• 查看日志及统计信息
• Cron 作业管理与执行

备份与恢复

• 创建、列出、下载和删除备份
• 完整支持备份恢复

Hook 管理

• 列出、读取、创建和删除 JavaScript Hook
• 为常见模式提供预置模板

安装

npm install
npm run build

配置

可通过以下方式配置服务以连接到不同的 PocketBase 实例（按优先级排序）：

1. 本地配置文件（项目目录中的 .pocketbase-mcp.json）：

   {
     "url": "http://localhost:8091"
   }
   

2. 环境变量：

   • POCKETBASE_URL：PocketBase 实例的 URL

3. 默认值：http://127.0.0.1:8090

多项目设置

选项 1：项目专属配置（推荐）

每个项目都可以拥有自己的 MCP 配置：

# In project directory
claude mcp add-json pocketbase '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "http://localhost:8091"}}' --scope project

选项 2：配置文件

在项目根目录中创建 .pocketbase-mcp.json：

{
  "url": "https://api.myproject.com"
}

选项 3：多个命名服务

在全局配置中添加不同的 PocketBase 实例：

claude mcp add-json pb-local '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "http://localhost:8090"}}'
claude mcp add-json pb-prod '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "https://api.myapp.com"}}'

在 Claude Desktop 中使用

将此配置添加到 Claude Desktop MCP 设置中：

{
  "mcpServers": {
    "pocketbase": {
      "command": "node",
      "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"],
      "env": {
        "POCKETBASE_URL": "http://localhost:8090"
      }
    }
  }
}

可用工具

集合管理工具

• list_collections - 列出所有集合，支持分页和筛选
• get_collection - 按 ID 或名称获取指定集合
• create_collection - 使用架构创建新集合
• update_collection - 更新集合设置和架构
• delete_collection - 删除集合
• import_collections - 一次导入多个集合

记录管理工具

• list_records - 列出记录，支持分页、筛选、排序和字段选择
• get_full_list - 获取所有记录，无需分页（批量处理）
• get_first_list_item - 获取符合筛选条件的第一条记录
• get_record - 按 ID 获取指定记录
• create_record - 创建新记录
• update_record - 更新现有记录
• delete_record - 删除记录

批量操作

• batch_create - 在单个事务中创建多条记录
• batch_update - 在单个事务中更新多条记录
• batch_delete - 在单个事务中删除多条记录
• batch_upsert - 在单个事务中插入或更新多条记录

认证工具

• list_auth_methods - 获取可用的认证方式
• auth_with_password - 使用电子邮件/用户名和密码进行认证
• auth_with_oauth2 - 获取 OAuth2 认证 URL
• auth_refresh - 刷新认证令牌
• request_otp - 请求用于电子邮件认证的一次性密码（OTP）
• auth_with_otp - 使用 OTP 进行认证
• request_password_reset - 发送密码重置电子邮件
• confirm_password_reset - 使用令牌确认密码重置
• request_verification - 发送验证电子邮件
• confirm_verification - 确认电子邮件验证
• request_email_change - 请求更改电子邮件地址
• confirm_email_change - 确认更改电子邮件地址

文件管理工具

• get_file_url - 生成用于访问文件的 URL，并可设置选项
• get_file_token - 获取私有文件访问令牌

日志管理工具

• list_logs - 列出系统日志并支持筛选
• get_log - 获取特定日志条目
• get_log_stats - 获取日志统计信息

Cron 任务工具

• list_cron_jobs - 列出所有 Cron 任务
• run_cron_job - 手动运行 Cron 任务

系统工具

• get_health - 检查 PocketBase 健康状态
• get_settings - 获取 PocketBase 设置（需要管理员认证）
• update_settings - 更新 PocketBase 设置（需要管理员认证）

备份工具

• create_backup - 创建备份
• list_backups - 列出可用备份
• download_backup - 获取备份的下载 URL
• delete_backup - 删除备份
• restore_backup - 从备份恢复

Hook 管理工具

• list_hooks - 列出 pb_hooks 目录中的 JavaScript Hook 文件
• read_hook - 读取 Hook 文件的内容
• create_hook - 创建或更新 JavaScript Hook 文件
• delete_hook - 删除 Hook 文件
• create_hook_template - 为常见模式生成 Hook 模板：
  • record-validation：记录字段验证
  • record-auth：自定义认证逻辑
  • custom-route：创建 API 端点
  • file-upload：文件上传验证
  • scheduled-task：设置 Cron 任务

工具示例

筛选记录列表

{
  "tool": "list_records",
  "arguments": {
    "collection": "posts",
    "filter": "published = true && created >= '2024-01-01'",
    "sort": "-created",
    "expand": "author",
    "fields": "id,title,content,author",
    "skipTotal": true
  }
}

不分页获取所有记录

{
  "tool": "get_full_list",
  "arguments": {
    "collection": "categories",
    "sort": "name",
    "batch": 1000
  }
}

批量创建记录

{
  "tool": "batch_create",
  "arguments": {
    "requests": [
      {
        "collection": "posts",
        "data": {
          "title": "First Post",
          "content": "Content 1"
        }
      },
      {
        "collection": "posts",
        "data": {
          "title": "Second Post",
          "content": "Content 2"
        }
      }
    ]
  }
}

OAuth2 认证

{
  "tool": "auth_with_oauth2",
  "arguments": {
    "collection": "users",
    "provider": "google",
    "redirectURL": "https://myapp.com/auth/callback"
  }
}

OTP 认证流程

// Step 1: Request OTP
{
  "tool": "request_otp",
  "arguments": {
    "collection": "users",
    "email": "[email protected]"
  }
}

// Step 2: Authenticate with OTP
{
  "tool": "auth_with_otp",
  "arguments": {
    "collection": "users",
    "otpId": "otp_id_from_step_1",
    "password": "123456"
  }
}

获取带缩略图的文件 URL

{
  "tool": "get_file_url",
  "arguments": {
    "collection": "products",
    "recordId": "abc123",
    "filename": "photo.jpg",
    "thumb": "300x200"
  }
}

创建 Hook 模板

{
  "tool": "create_hook_template",
  "arguments": {
    "type": "record-validation",
    "collection": "posts"
  }
}

查询语法

MCP 服务支持 PocketBase 的完整查询语法：

筛选示例

• title = "example" - 精确匹配
• created >= "2024-01-01" - 日期比较
• title ~ "search" - 包含文本
• tags ?~ "important" - 任意数组元素包含该内容
• user.name = "John" - 访问嵌套字段

排序示例

• created - 按 created 升序
• -created - 按 created 降序
• name,-created - 按多个字段排序

展开示例

• author - 展开单个关联
• author,tags - 展开多个关联
• author.profile - 嵌套展开

字段选择

• id,title,content - 选择指定字段
• *,expand.author.name - 包含展开的字段

性能优化

• 不需要总数时，使用 skipTotal: true
• 使用 fields 参数限制数据传输量
• 对大型数据集使用 get_full_list，并设置合适的批次大小
• 批量修改记录时使用批量操作

开发

在开发模式下运行

npm run dev

构建

npm run build

架构

MCP 服务遵循 Model Context Protocol 规范：

1. MCP 服务：处理工具注册与执行
2. PocketBase 客户端：使用官方 PocketBase JavaScript SDK
3. 工具处理器：实现特定的 PocketBase 操作，并进行适当的错误处理

错误处理

所有工具都包含全面的错误处理，并会返回描述性错误消息。常见错误包括：

• 认证无效
• 缺少必填字段
• 网络连接问题
• 权限被拒绝

安全注意事项

• 管理操作需要适当的身份验证
• 使用环境变量配置敏感信息
• 此服务继承 PocketBase 的安全模型和访问规则
• 安全地处理 OAuth2 状态参数

版本兼容性

• 需要 PocketBase v0.20.0 或更高版本
• 使用 PocketBase JavaScript SDK v0.21.0+
• 实现 MCP 协议版本 1.0

贡献

欢迎贡献！请确保所有新工具：

• 遵循现有的命名模式
• 包含正确的 TypeScript 类型
• 具备全面的错误处理
• 在此 README 中编写文档

许可证

ISC