高级 PocketBase MCP 服务器
一个功能全面的 MCP 服务器，提供与 PocketBase 数据库交互的复杂工具。该服务器通过模型上下文协议 (MCP) 支持高级数据库操作、模式管理和数据操作。
变更日志
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_ADMIN_EMAIL ：用于某些操作的管理员电子邮件POCKETBASE_ADMIN_PASSWORD ：管理员密码POCKETBASE_DATA_DIR ：自定义数据目录路径
使用示例
收藏管理
// Create a new collection
await mcp.use_tool("pocketbase", "create_collection", {
name: "posts",
schema: [
{
name: "title",
type: "text",
required: true
},
{
name: "content",
type: "text",
required: true
}
]
});
// Manage indexes
await mcp.use_tool("pocketbase", "manage_indexes", {
collection: "posts",
action: "create",
index: {
name: "title_idx",
fields: ["title"],
unique: true
}
});
高级查询
// Query with filtering, sorting, and aggregation
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"
});
数据导入/导出
// Import data with upsert mode
await mcp.use_tool("pocketbase", "import_data", {
collection: "posts",
data: [
{
title: "First Post",
content: "Hello World"
},
{
title: "Second Post",
content: "More content"
}
],
mode: "upsert"
});
// Backup database
await mcp.use_tool("pocketbase", "backup_database", {
format: "json" // or "csv"
});
架构迁移
// Migrate collection schema
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: {
// Optional field transformations during migration
tags: "JSON.parse(oldTags)"
}
});
身份验证方法
// List available authentication methods
await mcp.use_tool("pocketbase", "list_auth_methods", {
collection: "users"
});
// Authenticate with password
await mcp.use_tool("pocketbase", "authenticate_user", {
email: "user@example.com",
password: "securepassword",
collection: "users"
});
// Authenticate with 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"
});
// Request password reset
await mcp.use_tool("pocketbase", "request_password_reset", {
email: "user@example.com",
collection: "users"
});
// Confirm password reset
await mcp.use_tool("pocketbase", "confirm_password_reset", {
token: "verification_token",
password: "new_password",
passwordConfirm: "new_password",
collection: "users"
});
// Refresh authentication token
await mcp.use_tool("pocketbase", "auth_refresh", {
collection: "users"
});
错误处理
所有工具均包含全面的错误处理功能，并配有详细的错误消息。错误信息均已正确输入，包括：
- 无效请求错误
- 身份验证错误
- 数据库操作错误
- 架构验证错误
- 网络错误
类型安全
该服务器包含所有操作的 TypeScript 定义，确保使用工具时的类型安全。每个工具的输入模式都经过严格的类型和验证。
最佳实践
- 始终使用 try/catch 块进行适当的错误处理
- 执行操作前验证数据
- 使用适当的索引以获得更好的查询性能
- 定期备份数据库
- 使用迁移进行架构更改
- 遵循用户管理的安全最佳实践
- 监控和优化数据库性能
发展
- 克隆存储库
- 安装依赖项：
npm install - 将
.env.example复制到.env并配置 - 构建：
npm run build - 启动您的 PocketBase 实例
- MCP 服务器将自动连接到您的 PocketBase 实例
通过 Smithery 安装
要通过Smithery自动为 Claude Desktop 安装 PocketBase Server：
npx -y @smithery/cli install pocketbase-server --client claude
贡献
- 分叉存储库
- 创建功能分支
- 提交你的更改
- 推送到分支
- 创建拉取请求