AI导哈

PocketBase MCP服务器

一个MCP（模型上下文协议）服务器，使AI代理能够与PocketBase实例进行数据查询和管理。

  • by feirelles
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 feirelles/pocketbase-mcp

使用说明

PocketBase MCP服务器

MCP（模型上下文协议）服务器，使AI代理能够与 PocketBase 用于数据查询和管理的实例。

特性

  • 通过过滤、排序、分页和关系扩展查询记录
  • 记录和集合的完整CRUD操作
  • 管理员和用户身份验证
  • 集合架构管理
  • 紧凑的TOML输出格式（比JSON小25%，可配置）
  • 带Zod验证的类型安全TypeScript实现
  • 支持所有PocketBase字段类型：文本、数字、bool、电子邮件、url、日期、自动日期、选择、json、文件、关系、编辑器、geoPoint

安装

npm install @feirelles/pocketbase-mcp

或者克隆并在本地构建：

git clone https://github.com/feirelles/pocketbase-mcp.git
cd pocketbase-mcp
npm install
npm run build

配置

将PocketBase URL设置为环境变量：

export POCKETBASE_URL="http://localhost:8090"

MCP客户端配置

克劳德桌面版

增添 ~/.config/claude/claude_desktop_config.json:

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

VS代码（副本）

增添 .vscode/mcp.json:

{
  "servers": {
    "pocketbase": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "http://localhost:8090"
      }
    }
  }
}

可用工具

认证

工具 说明
pocketbase_auth_admin 以管理员/超级用户身份进行身份验证
pocketbase_auth_user 作为普通用户进行身份验证（支持电子邮件/用户名）
pocketbase_get_auth_status 检查当前身份验证状态
pocketbase_logout 清除身份验证会话

记录

工具 说明
pocketbase_list_records 列出具有过滤、排序、分页和skipTotal功能的记录
pocketbase_get_record 按ID获取单个记录
pocketbase_create_record 创建新记录（支持扩展/字段响应）
pocketbase_update_record 更新现有记录（支持扩展/字段响应）
pocketbase_delete_record 删除记录

收藏（仅限管理员）

工具 说明
pocketbase_list_collections 列出所有收藏
pocketbase_get_collection 获取集合架构详细信息
pocketbase_create_collection 创建新收藏
pocketbase_update_collection 更新集合架构
pocketbase_delete_collection 删除收藏

管理（仅限管理员）

工具 说明
pocketbase_health_check 检查服务器运行状况（无需身份验证）
pocketbase_list_logs 列出服务器日志并进行筛选
pocketbase_get_log 按ID获取单个日志条目
pocketbase_log_stats 获取每小时日志统计信息
pocketbase_list_backups 列出所有可用的备份文件
pocketbase_create_backup 创建新的数据库备份
pocketbase_restore_backup 从备份文件还原
pocketbase_delete_backup 删除备份文件

文件

工具 说明
pocketbase_get_file_url 生成URL以访问带有可选缩略图的文件

用法

MCP服务器使AI代理能够通过自然语言与PocketBase实例进行交互。代理人可以：

  • 跨集合查询和管理记录
  • 以管理员或普通用户身份进行身份验证
  • 创建和修改集合架构
  • 使用完整的CRUD功能管理数据

只需让AI代理对PocketBase数据执行操作，它就会自动使用适当的工具。

输出格式

默认情况下，所有工具都返回TOML格式以提高令牌效率：

page = 1
perPage = 50
totalItems = 42
hasMore = false

[[items]]
id = "abc123def456"
title = "My Post"
status = "published"
created = "2026-01-15T10:30:00.000Z"

要获取JSON，请添加 format: "json" 任何工具调用。

错误处理

错误以结构化格式返回：

[error]
code = "NOT_FOUND"
message = "Collection 'posts' not found"
suggestion = "Use pocketbase_list_collections to see available collections"

错误代码：

  • CONNECTION_ERROR -无法连接到PocketBase
  • AUTH_REQUIRED -需要身份验证
  • AUTH_FAILED -凭据无效
  • NOT_FOUND -未找到资源
  • VALIDATION_ERROR -输入数据无效
  • PERMISSION_DENIED -权限不足

现场类型和特殊处理

关系字段

当使用创建或更新集合时 relation 类型字段，您可以使用以下任一字段：

  • 收集 名字 （例如。， "users")-自动解析为ID
  • 收集 ID （例如。， "pbc_2478858439")-直接使用

为了方便起见，MCP服务器会自动将集合名称解析为其ID。

例子：

{
  "name": "author",
  "type": "relation",
  "required": true,
  "options": {
    "collectionId": "users",
    "cascadeDelete": false,
    "maxSelect": 1,
    "displayFields": ["email", "name"]
  }
}

看 examples/create-collectionwith-relations.json 举一个完整的例子。

选择字段

对于 select 字段，提供 values 和 maxSelect 在选项中：

{
  "name": "status",
  "type": "select",
  "required": true,
  "options": {
    "values": ["draft", "published", "archived"],
    "maxSelect": 1
  }
}

自动日期字段

对于 autodate 字段，指定更新时间：

{
  "name": "created",
  "type": "autodate",
  "options": {
    "onCreate": true,
    "onUpdate": false
  }
}

文件字段和URL

使用 pocketbase_get_file_url 为存储在PocketBase中的文件生成URL。支持生成图像缩略图（JPG、PNG、GIF、WebP）。

缩略图格式：

  • WxH -裁剪到宽x高视框（从中心）
  • WxHt -从顶部裁剪
  • WxHb -从底部收割
  • WxHf -内部宽x高（无裁剪）
  • 0xH -调整高度，保持纵横比
  • Wx0 -调整宽度，保持纵横比

例子：

pocketbase_get_file_url(
  collection="posts",
  recordId="abc123",
  filename="photo.jpg",
  thumb="200x200"
)

故障排除

连接问题

如果你得到 CONNECTION_ERROR:

  1. 验证PocketBase是否正在运行： curl http://localhost:8090/api/health
  2. 检查 POCKETBASE_URL 设置正确
  3. 确保没有防火墙阻塞端口

身份验证问题

  • 管理员身份验证失败：验证电子邮件/密码 _superusers 收集
  • 用户身份验证失败：使用 identity 参数（可以是电子邮件或用户名）
  • 权限不足：检查PocketBase管理中的集合API规则

常见错误

  1. 使用 email 而不是 identity 用于用户身份验证

    • 对的： identity="user@example.com" 或 identity="johndoe"
    • 错误： email="user@example.com" （仅用于管理员身份验证）

  2. 在管理员操作之前忘记进行身份验证

    • 使用 pocketbase_auth_admin 第一
    • 与核对 pocketbase_get_auth_status

  3. 创建没有名称的备份

    • name 可选-如果省略，则自动生成

发展

# Install dependencies
npm install

# Build
npm run build

# Development mode (watch)
npm run dev

# Lint
npm run lint

# Test
npm test

MCP检验员测试

npx @modelcontextprotocol/inspector node dist/index.js

许可证

麻省理工学院

相关 MCP