高级 PocketBase MCP 服务器

一个全面的 MCP 服务器，提供用于与 PocketBase 数据库交互的复杂工具。该服务器通过模型上下文协议 (MCP) 实现高级数据库操作、模式管理和数据操作。

<a href="https://glama.ai/mcp/servers/z2xjuegxxh"><img width="380" height="200" src="https://glama.ai/mcp/servers/z2xjuegxxh/badge" alt="pocketbase-mcp-server MCP server" /></a>

更新日志

v2.0.0 (2025 年 4 月 2 日)

新增

• 增强了对使用环境变量进行管理员身份验证的支持
• 增加了通过 impersonate_user 工具模拟管理员的支持
• 改进了身份验证操作的错误处理
• 添加了全面的 TypeScript 类型定义，以获得更好的开发体验
• 增加了对 Cline 集成的支持

修复

• 修复了 PocketBase 客户端实现中的 TypeScript 错误
• 改进了模式字段处理，并带有正确的类型注释
• 修复了可选模式字段属性的问题

更改

• 更新了身份验证流程以支持多种身份验证方法
• 改进了文档，提供了更详细的示例
• 增强了环境变量配置选项

功能特性

集合管理

• 创建和管理具有自定义模式的集合
• 迁移集合模式并保留数据
• 高级索引管理（创建、删除、列表）
• 模式验证和类型安全
• 检索集合模式和元数据

记录操作

• 记录的 CRUD 操作
• 使用过滤、排序和聚合进行高级查询
• 批量导入/导出功能
• 关系扩展支持
• 分页和基于游标的导航

用户管理

• 用户身份验证和令牌管理
• 用户帐户创建和管理
• 密码管理
• 基于角色的访问控制
• 会话处理

数据库操作

• 数据库备份和恢复
• 多种导出格式 (JSON/CSV)
• 数据迁移工具
• 索引优化
• 批量操作

可用工具

集合管理

• create_collection: 创建具有自定义模式的新集合
• get_collection_schema: 获取集合的模式详细信息
• migrate_collection: 迁移集合模式并保留数据
• manage_indexes: 创建、删除或列出集合索引

记录操作

• create_record: 在集合中创建新记录
• list_records: 列出记录，带有可选的过滤器和分页
• update_record: 更新现有记录
• delete_record: 删除记录
• query_collection: 使用过滤、排序和聚合进行高级查询
• import_data: 将数据导入集合，具有创建/更新/插入模式

用户管理

• authenticate_user: 验证用户身份并获取身份验证令牌
• create_user: 创建新的用户帐户
• list_auth_methods: 列出所有可用的身份验证方法
• authenticate_with_oauth2: 使用 OAuth2 验证用户身份
• authenticate_with_otp: 使用一次性密码验证用户身份
• auth_refresh: 刷新身份验证令牌
• request_verification: 请求电子邮件验证
• confirm_verification: 使用令牌确认电子邮件验证
• request_password_reset: 请求密码重置
• confirm_password_reset: 使用令牌确认密码重置
• request_email_change: 请求电子邮件更改
• confirm_email_change: 使用令牌确认电子邮件更改
• impersonate_user: 模拟另一个用户（仅限管理员）

数据库操作

• backup_database: 创建 PocketBase 数据库的备份，带有格式选项
• import_data: 导入数据，具有各种模式（创建/更新/插入）

配置

服务器需要以下环境变量：

• POCKETBASE_URL: 您的 PocketBase 实例的 URL（例如，“http://127.0.0.1:8090”）

可选环境变量：

• POCKETBASE_ADMIN_EMAIL: 用于某些操作的管理员电子邮件
• POCKETBASE_ADMIN_PASSWORD: 管理员密码
• POCKETBASE_DATA_DIR: 自定义数据目录路径

使用示例

集合管理

// 创建一个新集合
await mcp.use_tool("pocketbase", "create_collection", {
  name: "posts",
  schema: [
    {
      name: "title",
      type: "text",
      required: true
    },
    {
      name: "content",
      type: "text",
      required: true
    }
  ]
});

// 管理索引
await mcp.use_tool("pocketbase", "manage_indexes", {
  collection: "posts",
  action: "create",
  index: {
    name: "title_idx",
    fields: ["title"],
    unique: true
  }
});

高级查询

// 使用过滤、排序和聚合进行查询
await mcp.use_tool("pocketbase", "query_collection", {
  collection: "posts",
  filter: "created >= '2024-01-01'",
  sort: "-created",
  aggregate: {
    totalLikes: "sum(likes)",
    avgRating: "avg(rating)"
  },
  expand: "author,categories"
});

数据导入/导出

// 使用 upsert 模式导入数据
await mcp.use_tool("pocketbase", "import_data", {
  collection: "posts",
  data: [
    {
      title: "First Post",
      content: "Hello World"
    },
    {
      title: "Second Post",
      content: "More content"
    }
  ],
  mode: "upsert"
});

// 备份数据库
await mcp.use_tool("pocketbase", "backup_database", {
  format: "json" // or "csv"
});

模式迁移

// 迁移集合模式
await mcp.use_tool("pocketbase", "migrate_collection", {
  collection: "posts",
  newSchema: [
    {
      name: "title",
      type: "text",
      required: true
    },
    {
      name: "content",
      type: "text",
      required: true
    },
    {
      name: "tags",
      type: "json",
      required: false
    }
  ],
  dataTransforms: {
    // 迁移期间的可选字段转换
    tags: "JSON.parse(oldTags)"
  }
});

身份验证方法

// 列出可用的身份验证方法
await mcp.use_tool("pocketbase", "list_auth_methods", {
  collection: "users"
});

// 使用密码进行身份验证
await mcp.use_tool("pocketbase", "authenticate_user", {
  email: "user@example.com",
  password: "securepassword",
  collection: "users"
});

// 使用 OAuth2 进行身份验证
await mcp.use_tool("pocketbase", "authenticate_with_oauth2", {
  provider: "google",
  code: "auth_code_from_provider",
  codeVerifier: "code_verifier_from_pkce",
  redirectUrl: "https://your-app.com/auth/callback",
  collection: "users"
});

// 请求密码重置
await mcp.use_tool("pocketbase", "request_password_reset", {
  email: "user@example.com",
  collection: "users"
});

// 确认密码重置
await mcp.use_tool("pocketbase", "confirm_password_reset", {
  token: "verification_token",
  password: "new_password",
  passwordConfirm: "new_password",
  collection: "users"
});

// 刷新身份验证令牌
await mcp.use_tool("pocketbase", "auth_refresh", {
  collection: "users"
});

错误处理

所有工具都包含全面的错误处理，并提供详细的错误消息。错误已正确键入，包括：

• 无效的请求错误
• 身份验证错误
• 数据库操作错误
• 模式验证错误
• 网络错误

类型安全

服务器包含所有操作的 TypeScript 定义，确保在使用工具时的类型安全。每个工具的输入模式都经过严格的类型化和验证。

最佳实践

1. 始终使用 try/catch 块进行适当的错误处理
2. 在执行操作之前验证数据
3. 使用适当的索引以获得更好的查询性能
4. 定期备份数据库
5. 使用迁移进行模式更改
6. 遵循用户管理的安全最佳实践
7. 监控和优化数据库性能

开发

1. 克隆存储库
2. 安装依赖项：npm install
3. 将 .env.example 复制到 .env 并进行配置
4. 构建：npm run build
5. 启动您的 PocketBase 实例
6. MCP 服务器将自动连接到您的 PocketBase 实例

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 PocketBase Server：

npx -y @smithery/cli install pocketbase-server --client claude

贡献

1. Fork 存储库
2. 创建一个功能分支
3. 提交您的更改
4. 推送到分支
5. 创建一个 Pull Request