AI导哈

PocketBase模型上下文协议服务器

一个全面的模型上下文协议（MCP）服务器，提供管理PocketBase实例的工具，使LLM能够通过标准化协议与PocketBase数据库交互。

  • by brynnjocelyn
  • JavaScript
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 brynnjocelyn/pocketbase_mcp_server

使用说明

PocketBase MCP服务器

一个全面的模型上下文协议（MCP）服务器，提供管理PocketBase实例的工具。此服务器使LLM能够通过标准化协议与PocketBase数据库进行交互。

概述

此MCP服务器将PocketBase功能作为工具公开，可供任何MCP兼容客户端（如Claude Desktop、Cursor或其他LLM应用程序）使用。它提供了对PocketBase功能的全面访问，包括60多种涵盖所有主要操作的工具。

特性

收集管理

  • 列出、获取、创建、更新和删除集合
  • 大宗进出口托收
  • 全面的架构管理支持

记录操作

  • 带过滤、排序和分页的CRUD操作
  • getFullList 用于在不分页的情况下检索所有记录
  • getFirstListItem 用于查找第一条匹配记录
  • 高级查询支持，包括字段选择和关系扩展
  • 批量操作，实现高效批量处理

身份验证和用户管理

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

文件管理

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

系统操作

  • 健康监测
  • 设置管理
  • 使用统计信息查看日志
  • Cron作业管理和执行

备份和恢复

  • 创建、列出、下载和删除备份
  • 完全备份还原支持

钩子管理

  • 列出、读取、创建和删除JavaScript钩子
  • 常见模式的预构建模板

安装

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 -从备份还原

钩子管理工具

  • list_hooks -列出pb_hooks目录中的JavaScript挂钩文件
  • read_hook -读取挂钩文件的内容
  • create_hook -创建或更新JavaScript挂钩文件
  • delete_hook -删除挂钩文件
  • create_hook_template -为常见模式生成钩子模板：
    • 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": "user@example.com"
  }
}

// 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"
  }
}

创建挂钩模板

{
  "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 -按创建顺序降序
  • 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服务器遵循模型上下文协议规范：

  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中

许可证

国际协调委员会

相关 MCP