PocketBase MCP 服务器

这是一个与 PocketBase 实例交互的 MCP 服务器。它允许您获取、列出、创建、更新和管理 PocketBase 集合中的记录和文件。

安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 PocketBase MCP 服务器：

1. 克隆存储库（如果还没有）：
   git clone <repository_url> cd pocketbase-mcp
2. 安装依赖项：
   npm install
3. 构建服务器：
   npm run build
   这会将build/目录中的 TypeScript 代码编译为 JavaScript，并使入口点可执行。

配置

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

• POCKETBASE_API_URL ：你的 PocketBase 实例的 URL（例如http://127.0.0.1:8090 ）。如果未设置，则默认为http://127.0.0.1:8090 。
• POCKETBASE_ADMIN_TOKEN ：PocketBase 实例的管理员身份验证令牌。**此令牌为必需。**您可以从 PocketBase 管理界面生成此令牌，请参阅API 密钥。

将服务器添加到 Cline 时需要配置这些变量（参见 Cline 安装部分）。

可用工具

该服务器提供以下工具（按类别组织）：

记录管理

• fetch_record ：通过 ID 从 PocketBase 集合中获取单个记录。
  • 输入模式：
    { "type": "object", "properties": { "collection": { "type": "string", "description": "The name of the PocketBase collection." }, "id": { "type": "string", "description": "The ID of the record to fetch." } }, "required": [ "collection", "id" ] }
• list_records ：列出 PocketBase 集合中的记录。支持分页、过滤、排序和扩展关系。
  • 输入模式：
    { "type": "object", "properties": { "collection": { "type": "string", "description": "The name of the PocketBase collection." }, "page": { "type": "number", "description": "Page number (defaults to 1).", "minimum": 1 }, "perPage": { "type": "number", "description": "Items per page (defaults to 25).", "minimum": 1, "maximum": 100 }, "filter": { "type": "string", "description": "Filter string for the PocketBase query." }, "sort": { "type": "string", "description": "Sort string for the PocketBase query (e.g., \\"fieldName,-otherFieldName\\")." }, "expand": { "type": "string", "description": "Expand string for the PocketBase query (e.g., \\"relation1,relation2.subRelation\\")." } }, "required": [ "collection" ] }
• create_record ：在 PocketBase 集合中创建新记录。
  • 输入模式：
    { "type": "object", "properties": { "collection": { "type": "string", "description": "The name of the PocketBase collection." }, "data": { "type": "object", "description": "The data for the new record.", "additionalProperties": true } }, "required": [ "collection", "data" ] }
• update_record ：更新 PocketBase 集合中的现有记录。
  • 输入模式：
    { "type": "object", "properties": { "collection": { "type": "string", "description": "The name of the PocketBase collection." }, "id": { "type": "string", "description": "The ID of the record to update." }, "data": { "type": "object", "description": "The data to update.", "additionalProperties": true } }, "required": [ "collection", "id", "data" ] }
• get_collection_schema ：获取 PocketBase 集合的模式。
  • 输入模式：
    { "type": "object", "properties": { "collection": { "type": "string", "description": "The name of the PocketBase collection." } }, "required": [ "collection" ] }
• upload_file ：将文件上传到 PocketBase 集合记录中的特定字段。
  • 输入模式：
    { "type": "object", "properties": { "collection": { "type": "string", "description": "The name of the PocketBase collection." }, "recordId": { "type": "string", "description": "The ID of the record to upload the file to." }, "fileField": { "type": "string", "description": "The name of the file field in the PocketBase collection." }, "fileContent": { "type": "string", "description": "The content of the file to upload." }, "fileName": { "type": "string", "description": "The name of the file." } }, "required": [ "collection", "recordId", "fileField", "fileContent", "fileName" ] }
• list_collections ：列出 PocketBase 实例中的所有集合。
  • 输入模式：
    { "type": "object", "properties": {}, "additionalProperties": false }
• download_file ：获取存储在 PocketBase 集合记录中的文件的下载 URL。
  • 输入模式：
    { "type": "object", "properties": { "collection": { "type": "string", "description": "The name of the PocketBase collection." }, "recordId": { "type": "string", "description": "The ID of the record to download the file from." }, "fileField": { "type": "string", "description": "The name of the file field in the PocketBase collection." }, "downloadPath": { "type": "string", "description": "The path where the downloaded file should be saved (Note: This tool currently returns the URL, download must be handled separately)." } }, "required": [ "collection", "recordId", "fileField", "downloadPath" ] }
    注意：此工具返回文件 URL，实际下载需要客户端使用此 URL 进行。

收藏管理

• list_collections ：列出 PocketBase 实例中的所有集合。
  • 输入模式：
    { "type": "object", "properties": {}, "additionalProperties": false }
• get_collection_schema ：获取 PocketBase 集合的模式。
  • 输入模式：
    { "type": "object", "properties": { "collection": { "type": "string", "description": "The name of the PocketBase collection." } }, "required": [ "collection" ] }

日志管理

**注意：**日志 API 需要管理员身份验证，并且可能并非所有 PocketBase 实例或配置都可用。这些工具如何与 PocketBase 日志 API 交互，请参阅https://pocketbase.io/docs/api-logs/ 。

• list_logs ：列出来自 PocketBase 的 API 请求日志，包括过滤、排序和分页。
  • 输入模式：
    { "type": "object", "properties": { "page": { "type": "number", "description": "Page number (defaults to 1).", "minimum": 1 }, "perPage": { "type": "number", "description": "Items per page (defaults to 30, max 500).", "minimum": 1, "maximum": 500 }, "filter": { "type": "string", "description": "PocketBase filter string (e.g., \"method='GET'\")." } }, "required": [] }
• get_log ：通过ID获取单个API请求日志。
  • 输入模式：
    { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the log to fetch." } }, "required": [ "id" ] }
• get_logs_stats ：获取 API 请求日志统计信息，并可选择过滤。
  • 输入模式：
    { "type": "object", "properties": { "filter": { "type": "string", "description": "PocketBase filter string (e.g., \"method='GET'\")." } }, "required": [] }

迁移管理

• set_migrations_directory ：设置创建和读取迁移文件的目录。
  • 输入模式：
    { "type": "object", "properties": { "customPath": { "type": "string", "description": "Custom path for migrations. If not provided, defaults to 'pb_migrations' in the current working directory." } } }
• create_migration ：创建一个带有时间戳名称的新的、空的 PocketBase 迁移文件。
  • 输入模式：
    { "type": "object", "properties": { "description": { "type": "string", "description": "A brief description for the migration filename (e.g., 'add_user_email_index')." } }, "required": ["description"] }
• create_collection_migration ：创建一个专门用于创建新 PocketBase 集合的迁移文件。
  • 输入模式：
    { "type": "object", "properties": { "description": { "type": "string", "description": "Optional description override for the filename." }, "collectionDefinition": { "type": "object", "description": "The full schema definition for the new collection (including name, id, fields, rules, etc.).", "additionalProperties": true } }, "required": ["collectionDefinition"] }
• add_field_migration ：创建一个迁移文件，用于向现有集合添加字段。
  • 输入模式：
    { "type": "object", "properties": { "collectionNameOrId": { "type": "string", "description": "The name or ID of the collection to update." }, "fieldDefinition": { "type": "object", "description": "The schema definition for the new field.", "additionalProperties": true }, "description": { "type": "string", "description": "Optional description override for the filename." } }, "required": ["collectionNameOrId", "fieldDefinition"] }
• list_migrations ：列出在 PocketBase 迁移目录中找到的所有迁移文件。
  • 输入模式：
    { "type": "object", "properties": {}, "additionalProperties": false }
• apply_migration ：应用特定的迁移文件。
  • 输入模式：
    { "type": "object", "properties": { "migrationFile": { "type": "string", "description": "Name of the migration file to apply." } }, "required": ["migrationFile"] }
• revert_migration ：恢复特定的迁移文件。
  • 输入模式：
    { "type": "object", "properties": { "migrationFile": { "type": "string", "description": "Name of the migration file to revert." } }, "required": ["migrationFile"] }
• apply_all_migrations ：应用所有待处理的迁移。
  • 输入模式：
    { "type": "object", "properties": { "appliedMigrations": { "type": "array", "items": { "type": "string" }, "description": "Array of already applied migration filenames." } } }
• revert_to_migration ：将迁移恢复到特定目标。
  • 输入模式：
    { "type": "object", "properties": { "targetMigration": { "type": "string", "description": "Name of the migration to revert to (exclusive). Use empty string to revert all." }, "appliedMigrations": { "type": "array", "items": { "type": "string" }, "description": "Array of already applied migration filenames." } }, "required": ["targetMigration"] }

迁移系统

PocketBase MCP 服务器包含一个全面的迁移系统，用于管理数据库架构变更。该系统允许您：

1. 创建带有时间戳名称的迁移文件
2. 为常见操作（创建集合、添加字段）生成迁移
3. 单独或批量应用和恢复迁移
4. 跟踪已应用的迁移

迁移文件格式

迁移文件是带有时间戳前缀和描述性名称的 JavaScript 文件：

每次迁移都有一个用于应用更改的“向上”功能和一个用于恢复更改的“向下”功能。

使用示例

设置自定义迁移目录：

创建基本迁移：

创建集合迁移：

向集合添加字段：

应用迁移：

恢复迁移：

Cline 安装

要将此服务器与 Cline 一起使用，您需要将其添加到您的 MCP 设置文件 ( cline_mcp_settings.json ) 中。

1. 找到您的 Cline MCP 设置文件：
   • 通常在 Linux/macOS 上的~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json中找到。
   • 或者如果在 macOS 上使用 Claude 桌面应用程序~/Library/Application Support/Claude/claude_desktop_config.json 。
2. **编辑该文件，并在mcpServers键下添加以下配置。**将/path/to/pocketbase-mcp替换为你系统上该项目目录的实际绝对路径。同时，将<YOUR_POCKETBASE_API_URL>和<YOUR_POCKETBASE_ADMIN_TOKEN>替换为你的实际 PocketBase URL 和管理员令牌。
   { "mcpServers": { // ... other servers might be listed here ... "pocketbase-mcp": { "command": "node", "args": ["/path/to/pocketbase-mcp/build/index.js"], "env": { "POCKETBASE_API_URL": "<YOUR_POCKETBASE_API_URL>", // e.g., "http://127.0.0.1:8090" "POCKETBASE_ADMIN_TOKEN": "<YOUR_POCKETBASE_ADMIN_TOKEN>" }, "disabled": false, // Ensure it's enabled "autoApprove": [ "fetch_record", "list_collections", "get_collection_schema", "list_logs", "get_log", "get_logs_stats" ] // Suggested auto-approve settings } // ... other servers might be listed here ... } }
3. 保存设置文件。Cline应该会自动检测更改并连接到服务器。然后，您就可以使用上面列出的工具了。

依赖项

• @modelcontextprotocol/sdk
• pocketbase
• typescript
• ts-node （开发依赖项）
• @types/node （开发依赖项）