自然语言 PocketBase 服务

@mabeldata/pocketbase-mcp

0 Stars 28 次浏览 mabeldata 更新于 2026-08-23

允许与 PocketBase 数据库进行交互的 MCP 服务器，通过自然语言启用记录操作（获取、列出、创建、更新）、文件管理和模式迁移。

开发者工具

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

PocketBase MCP 服务器

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

安装

通过 Smithery 安装

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

npx -y @smithery/cli install @mabeldata/pocketbase-mcp --client claude

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

配置

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

POCKETBASE_API_URL: 您的 PocketBase 实例的 URL（例如，http://127.0.0.1:8090）。如果未设置，默认为 http://127.0.0.1:8090。
POCKETBASE_ADMIN_TOKEN: 您的 PocketBase 实例的管理员身份验证令牌。这是必需的。 您可以从 PocketBase 管理 UI 生成此令牌，参见 API 密钥。

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

可用工具

服务器提供以下按类别组织的工具：

记录管理

fetch_record: Fetch a single record from a PocketBase collection by ID.

Input Schema:

{
  "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: List records from a PocketBase collection. Supports pagination, filtering, sorting, and expanding relations.

Input Schema:

{
  "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: Create a new record in a PocketBase collection.

Input Schema:

{
  "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: Update an existing record in a PocketBase collection.

Input Schema:

{
  "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: Get the schema of a PocketBase collection.

Input Schema:

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "The name of the PocketBase collection."
    }
  },
  "required": [
    "collection"
  ]
}

upload_file: Upload a file to a specific field in a PocketBase collection record.

Input Schema:

{
  "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: List all collections in the PocketBase instance.
- Input Schema:
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

download_file: Get the download URL for a file stored in a PocketBase collection record.

Input Schema:

{
  "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"
  ]
}

Note: This tool returns the file URL. The actual download needs to be performed by the client using this URL.

集合管理

list_collections: 列出 PocketBase 实例中的所有集合。

输入模式:

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_collection_schema: 获取 PocketBase 集合的模式。

输入模式:

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    }
  },
  "required": [
    "collection"
  ]
}

日志管理

注意: Logs API 需要管理员身份验证，并且可能不是所有的 PocketBase 实例或配置都可用。这些工具与 PocketBase Logs API 交互，如 https://pocketbase.io/docs/api-logs/ 所述。

list_logs: 从 PocketBase 中列出带有过滤、排序和分页功能的 API 请求日志。

输入模式:

{
  "type": "object",
  "properties": {
    "page": {
      "type": "number",
      "description": "页码（默认为 1）。",
      "minimum": 1
    },
    "perPage": {
      "type": "number",
      "description": "每页项数（默认为 30，最大 500）。",
      "minimum": 1,
      "maximum": 500
    },
    "filter": {
      "type": "string",
      "description": "PocketBase 过滤字符串（例如，\"method='GET'\"）。"
    }
  },
  "required": []
}

get_log: 根据 ID 获取单个 API 请求日志。

输入模式:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "要获取的日志 ID。"
    }
  },
  "required": [
    "id"
  ]
}

get_logs_stats: 获取带有可选过滤条件的 API 请求日志统计信息。

输入模式:

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string",
      "description": "PocketBase 过滤字符串（例如，\"method='GET'\"）。"
    }
  },
  "required": []
}

定时任务管理

注意: Cron Jobs API 需要管理员身份验证，并且可能不是所有的 PocketBase 实例或配置都可用。这些工具与 PocketBase Cron Jobs API 交互。

list_cron_jobs: 返回所有已注册的应用级定时任务列表。

输入模式:

{
  "type": "object",
  "properties": {
    "fields": {
      "type": "string",
      "description": "要返回的字段的逗号分隔字符串（默认情况下返回所有字段）。例如：?fields=*,expand.relField.name"
    }
  }
}

run_cron_job: 通过ID触发单个定时任务。

输入模式:

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "要运行的定时任务的标识符。"
    }
  },
  "required": [
    "jobId"
  ]
}

迁移管理

set_migrations_directory: Set the directory where migration files will be created and read from.

Input Schema:

{
  "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: Create a new, empty PocketBase migration file with a timestamped name.

Input Schema:

{
  "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: Create a migration file specifically for creating a new PocketBase collection.

Input Schema:

{
  "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: Create a migration file for adding a field to an existing collection.

Input Schema:

{
  "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: List all migration files found in the PocketBase migrations directory.
- Input Schema:
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

apply_migration: Apply a specific migration file.

Input Schema:

{
  "type": "object",
  "properties": {
    "migrationFile": { 
      "type": "string", 
      "description": "Name of the migration file to apply." 
    }
  },
  "required": ["migrationFile"]
}

revert_migration: Revert a specific migration file.

Input Schema:

{
  "type": "object",
  "properties": {
    "migrationFile": { 
      "type": "string", 
      "description": "Name of the migration file to revert." 
    }
  },
  "required": ["migrationFile"]
}

apply_all_migrations: Apply all pending migrations.

Input Schema:

{
  "type": "object",
  "properties": {
    "appliedMigrations": { 
      "type": "array", 
      "items": { "type": "string" },
      "description": "Array of already applied migration filenames." 
    }
  }
}

revert_to_migration: Revert migrations up to a specific target.

Input Schema:

{
  "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 服务器包含一个全面的迁移系统，用于管理数据库模式变更。该系统允许您：

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

迁移文件格式

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

// 1744005374_update_transactions_add_debt_link.js
/// <reference path="../pb_data/types.d.ts" />
migrate((app) => {
  // Up migration code here
  return app.save();
}, (app) => {
  // Down migration code here
  return app.save();
});

每个迁移都有一个用于应用更改的 "up" 函数和一个用于回滚更改的 "down" 函数。

使用示例

设置自定义迁移目录：

await setMigrationsDirectory("./my_migrations");

创建基本迁移：

await createNewMigration("add_user_email_index");

创建集合迁移：

await createCollectionMigration({
  id: "users",
  name: "users",
  fields: [
    { name: "email", type: "email", required: true }
  ]
});

向集合中添加字段：

await createAddFieldMigration("users", {
  name: "address",
  type: "text"
});

应用迁移：

// Apply a specific migration
await applyMigration("1744005374_update_transactions_add_debt_link.js", pocketbaseInstance);

// Apply all pending migrations
await applyAllMigrations(pocketbaseInstance);

回滚迁移：

// Revert a specific migration
await revertMigration("1744005374_update_transactions_add_debt_link.js", pocketbaseInstance);

// Revert to a specific point (exclusive)
await revertToMigration("1743958155_update_transactions_add_relation_to_itself.js", pocketbaseInstance);

// Revert all migrations
await revertToMigration("", pocketbaseInstance);

Cline 安装

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

找到您的 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。

编辑文件并在 mcpServers 键下添加以下配置。 将 /path/to/pocketbase-mcp 替换为您系统上此项目目录的实际绝对路径。同时，将 <YOUR_POCKETBASE_API_URL> 和 <YOUR_POCKETBASE_ADMIN_TOKEN> 替换为您的实际 PocketBase URL 和管理员令牌。

{
  "mcpServers": {
    // ... 其他服务器可能在这里列出 ...

    "pocketbase-mcp": {
      "command": "node",
      "args": ["/path/to/pocketbase-mcp/build/index.js"],
      "env": {
        "POCKETBASE_API_URL": "<YOUR_POCKETBASE_API_URL>", // 例如, "http://127.0.0.1:8090"
        "POCKETBASE_ADMIN_TOKEN": "<YOUR_POCKETBASE_ADMIN_TOKEN>"
      },
      "disabled": false, // 确保其已启用
      "autoApprove": [
        "fetch_record",
        "list_collections",
        "get_collection_schema",
        "list_logs",
        "get_log",
        "get_logs_stats",
        "list_cron_jobs",
        "run_cron_job"
      ] // 建议的自动批准设置
    }

    // ... 其他服务器可能在这里列出 ...
  }
}

保存设置文件。 Cline 应该会自动检测更改并连接到服务器。然后您可以使用上述工具。

依赖项

@modelcontextprotocol/sdk
pocketbase
typescript
ts-node (开发依赖)
@types/node (开发依赖)

查看源码项目主页

服务介绍

PocketBase MCP 服务器

安装

通过 Smithery 安装

配置

可用工具

记录管理

集合管理

日志管理

定时任务管理

迁移管理

迁移系统

迁移文件格式

使用示例

Cline 安装

依赖项

相关 MCP 服务

开源版 与 企业版

企业版（含 FDE 交付）

技能定制开发服务

开源版与企业版