PocketBase MCP Server

Name: PocketBase MCP Server
Author: mabeldata

本地服务

loading.mabeldata.com数据库437 周前更新

代码仓库访问官网

关于 PocketBase MCP Server

PocketBase MCP Server 是一个连接 PocketBase 实例的 MCP 服务，可读取、列出、创建、更新和管理集合中的记录与文件。它面向需要通过 MCP 客户端操作 PocketBase 后端的开发者。README 说明了不同 PocketBase 版本的兼容性和部分功能的前提条件。

主要功能

01记录的查询、创建、更新与删除
02集合结构查看与集合列表
03文件上传与下载链接获取
04支持事务批处理，失败时整体回滚
05日志与定时任务管理
06可选的 run_sql 工具，默认关闭

适用场景

01通过 MCP 客户端查询和维护 PocketBase 集合数据
02上传文件到记录字段并获取下载地址
03批量导入或修改记录并保证一致性

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露约 30 个用于操作 PocketBase 的工具，例如 list_records、create_record 和 upload_file。

#backend #cline #pocketbase

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "pocketbase-mcp-mabeldata": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli"
      ]
    }
  }
}

启动命令npx -y @smithery/cli

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@smithery/clistdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

PocketBase MCP 服务

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

兼容性

组件	版本
PocketBase 服务端	需要 >= v0.23（`_superusers` 集合模型）；已针对 v0.40.3（发布时的最新稳定版）进行测试
`pocketbase` JS SDK	^0.28.1
`@modelcontextprotocol/sdk`	^1.30.0
Node.js	>= 18

较新 PocketBase 服务端的注意事项：

v0.27+：list_records / batch_records 完全支持 geoPoint 字段类型和 geoDistance() 过滤函数——参见 geoPoint 过滤示例。
v0.40.x：服务端可能会截断 Log.Data（约 16KB），并将其标记为 "__pb_truncated__": true；日志消息限制为 8KB。list_logs / get_log 的输出会原样传递此内容。
v0.38+：可在 PocketBase 设置中启用超级用户 IP 白名单。启用后，来自白名单以外 IP 的请求（包括此 MCP 的令牌）将被拒绝并返回 HTTP 403——参见故障排除。
v0.33+：集合 ID / 记录 ID 不能包含 . / \ | " ' ` < > : ? * % $，也不能使用 Windows 保留名称。迁移生成器会预先验证这些限制。
v0.28+：json 字段类型的默认最大大小为 1MB；较大的负载在 create_record / update_record 中会验证失败。

安装

通过 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，并使入口点可执行。

测试

测试套件（vitest，分为 3 层——完整指南见 tests/TESTS.md）：

npm test — 单元测试 + 契约测试（共 207 项：195 项通过 + 12 个已记录的已知错误标记；测试环境隔离：无需 PocketBase 实例或网络）。契约层通过快照锁定 tools/list MCP 契约（33 个工具：22 个原始工具 + 11 个新增的 PR-3 工具，各组分别创建快照），通过 InMemoryTransport 执行真实的客户端↔服务端握手，并对构建后的 build/index.js 进行 stdio 冒烟测试。
npm run test:integration — 使用真实 PocketBase 二进制文件进行集成测试（56 项）：自动下载并缓存二进制文件（使用 POCKETBASE_VERSION 固定版本，使用 POCKETBASE_BIN 指定本地二进制文件，使用 PB_BIN_DIR 指定备用缓存目录），在操作系统分配的端口上启动临时实例并使用唯一的超级用户身份，并使用官方 migrate up/down 运行器验证生成的迁移文件。PR-3 测试套件（pr3-tools.test.ts）会启动专用实例（管理范围的端点——SQL、批处理、备份、设置、清除日志——必须避免与共享服务器上的同级测试发生竞争；参见文件头部说明）。
npm run test:all — 完整测试套件（263 项）。
npm run typecheck — 对 src + tests 执行 tsc。
SKIP_KNOWN_BUG_TESTS=1 npm test — 绿色基线：跳过已知错误标记测试，不执行这些测试。

端到端冒烟脚本（通过 stdio 使用构建好的服务器连接真实 PocketBase 实例，执行 53 项检查）：

npm run smoke:contract — 仅进行契约冒烟测试（通过 stdio 调用 tools/list，无需 PocketBase）。
npm run smoke — 完整冒烟测试：从 $POCKETBASE_BIN 中的二进制文件（默认为 /tmp/pb-bin/pocketbase）启动临时服务器，创建超级用户，然后通过 stdio JSON-RPC 通道测试每类工具（记录、集合、文件、日志、定时任务、迁移）。

CI（.github/workflows/ci.yml）会在 Node 18/20/22 × PocketBase v0.39.11/v0.40.3 的矩阵上运行构建、类型检查、隔离测试、集成测试和冒烟测试。

配置

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

POCKETBASE_API_URL：PocketBase 实例的 URL（例如 http://127.0.0.1:8090）。如果未设置，默认为 http://127.0.0.1:8090。
POCKETBASE_ADMIN_TOKEN：PocketBase 实例的管理认证令牌。**必填。**你可以在 PocketBase 管理界面生成该令牌，参见 API KEYS。
POCKETBASE_ENABLE_SQL：**可选，默认禁用。**用于控制是否启用 run_sql 工具（执行原始 SQL）。请参阅下文的 SQL Execution (run_sql)——只有在了解风险的情况下才将其设为 true。

将服务器添加到 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": "PocketBase 集合的名称。"
    },
    "page": {
      "type": "number",
      "description": "页码（默认为 1）。",
      "minimum": 1
    },
    "perPage": {
      "type": "number",
      "description": "每页项目数（默认为 30，最多 500）。",
      "minimum": 1,
      "maximum": 500
    },
    "filter": {
      "type": "string",
      "description": "PocketBase 查询的筛选字符串。"
    },
    "sort": {
      "type": "string",
      "description": "PocketBase 查询的排序字符串（例如，\\"fieldName,-otherFieldName\\"）。"
    },
    "expand": {
      "type": "string",
      "description": "PocketBase 查询的展开字符串（例如，\\"relation1,relation2.subRelation\\"）。"
    }
  },
  "required": [
    "collection"
  ]
}

create_record：在 PocketBase 集合中创建新记录。

输入架构：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    },
    "data": {
      "type": "object",
      "description": "新记录的数据。",
      "additionalProperties": true
    }
  },
  "required": [
    "collection",
    "data"
  ]
}

update_record：更新 PocketBase 集合中的现有记录。

输入架构：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    },
    "id": {
      "type": "string",
      "description": "要更新的记录的 ID。"
    },
    "data": {
      "type": "object",
      "description": "要更新的数据。",
      "additionalProperties": true
    }
  },
  "required": [
    "collection",
    "id",
    "data"
  ]
}

delete_record：按 ID 从 PocketBase 集合中删除记录（永久删除）。

输入架构：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称或 ID。"
    },
    "id": {
      "type": "string",
      "description": "要删除的记录的 ID。"
    }
  },
  "required": [
    "collection",
    "id"
  ]
}

batch_records：在一个事务性批次中执行多项记录操作（创建/更新/upsert/删除）——如果任一操作失败，整个批次都会回滚。需要启用服务端批处理：在 PocketBase >= v0.39 中，/api/batch 默认处于关闭状态；请通过 update_settings 设置 {"batch": {"enabled": true}}（或通过 Admin UI -> Settings）启用，否则调用会失败，并返回 HTTP 403 "Batch requests are not allowed"。

输入架构：

{
  "type": "object",
  "properties": {
    "requests": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "collection": { "type": "string" },
          "action": { "enum": ["create", "update", "upsert", "delete"] },
          "id": { "type": "string" },
          "data": { "type": "object", "additionalProperties": true }
        },
        "required": ["collection", "action"]
      }
    }
  },
  "required": ["requests"]
}

get_collection_schema：获取 PocketBase 集合的架构。

输入架构：

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

upload_file：将文件上传到 PocketBase 集合记录中的指定字段。

输入架构：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    },
    "recordId": {
      "type": "string",
      "description": "要上传文件到的记录 ID。"
    },
    "fileField": {
      "type": "string",
      "description": "PocketBase 集合中文件字段的名称。"
    },
    "fileContent": {
      "type": "string",
      "description": "要上传的文件内容。"
    },
    "fileName": {
      "type": "string",
      "description": "文件名称。"
    }
  },
  "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": "PocketBase 集合的名称。"
    },
    "recordId": {
      "type": "string",
      "description": "包含该文件的记录名称。"
    },
    "fileField": {
      "type": "string",
      "description": "PocketBase 集合中文件字段的名称。"
    }
  },
  "required": [
    "collection",
    "recordId",
    "fileField"
  ]
}

注意：此工具会返回文件 URL。客户端需要使用此 URL 实际下载文件。

geoPoint 筛选示例

PocketBase >= v0.27 支持 geoPoint 字段类型和 geoDistance() 筛选函数。它们都可以通过 list_records / create_record / update_record / batch_records 透明使用（筛选字符串会原样传递给服务端）：

// store a location: create_record data payload (location is a geoPoint field)
{ "title": "Office", "location": { "lat": -23.5505, "lon": -46.6333 } }

// geoDistance(lonA, latA, lonB, latB) returns KILOMETRES (verified on v0.40.3) —
// offices within 10 km of São Paulo center (list_records filter):
{ "collection": "places", "filter": "geoDistance(location.lon, location.lat, -46.6333, -23.5505) <= 10" }

// combine with other conditions:
{ "collection": "places", "filter": "active = true && geoDistance(location.lon, location.lat, -46.6333, -23.5505) < 5" }

参数必须是普通数字或数字字段标识符（对于 geoPoint 字段，使用 location.lon / location.lat）；几何字面量（如 {-23.55, -46.63}）无效，而且目前不支持在 sort 中使用 geoDistance()。官方文档：https://pocketbase.io/docs/api-rules-and-filters/（geoDistance 部分）。

集合管理

list_collections：列出 PocketBase 实例中的所有集合。
- 输入架构：
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

get_collection_schema：获取 PocketBase 集合的架构。

输入架构：

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

get_collection_scaffolds：获取集合架构示例载荷（服务端 >= v0.37）——一个以集合类型（base、auth、view）为键的对象，其中包含可直接编辑的模板，用于创建新集合。
- 输入架构：{ "type": "object", "properties": {}, "additionalProperties": false }
dry_run_view_query：验证 VIEW 集合的 SQL 查询，但不保存集合（服务端 >= v0.37）。返回生成的字段定义和部分示例行，或验证错误。
- 输入架构：
```
{
  "type": "object",
  "properties": {
    "query": { "type": "string", "description": "作为视图集合数据源的 SQL SELECT 语句。" }
  },
  "required": ["query"]
}
```

日志管理

注意： Logs API 需要管理员身份验证，且并非所有 PocketBase 实例或配置都支持该 API。这些工具会与 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'\"）。"
    },
    "sort": {
      "type": "string",
      "description": "PocketBase 排序字符串（例如：\"-created,url\"）。"
    }
  },
  "required": []
}

注意：在 PocketBase >= v0.40 中，服务可能会截断 Log.Data（约 16 KB，并标记为 "__pb_truncated__": true），并将日志消息限制为 8 KB。

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": []
}

truncate_logs：删除所有 API 请求日志（服务版本 >= v0.40）。此操作具有破坏性且不可逆——需要设置 confirm: true。

输入架构：

{
  "type": "object",
  "properties": {
    "confirm": { "type": "boolean", "description": "必须显式设为 true 才会删除所有日志。" }
  },
  "required": ["confirm"]
}

定时任务管理

注意： Cron Jobs API 需要管理员身份验证，且并非所有 PocketBase 实例或配置都支持该 API。这些工具会与 PocketBase Cron Jobs API 交互。

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

输入架构：

{
  "type": "object",
  "properties": {
    "fields": {
      "type": "string",
      "description": "以逗号分隔的字段字符串，用于指定 JSON 响应中要返回的字段（默认返回所有字段）。例如：?fields=*,expand.relField.name"
    }
  }
}

run_cron_job：按 ID 触发单个定时任务。

输入架构：

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

备份管理

注意： 备份 API 需要超级用户身份验证（服务器 >= v0.22）。文档：https://pocketbase.io/docs/api-backups/。

list_backups：列出实例上所有可用的备份文件（key、size、modified）。
- 输入架构：{ "type": "object", "properties": {}, "additionalProperties": false }
create_backup：将新的数据库和存储备份加入队列。可选的 name 必须以 .zip 结尾（仅限字母、数字、_、-）；省略时 → 服务器会生成 pb_backup_<timestamp>.zip。备份会异步处理——轮询 list_backups，直到出现新的键。
- 输入架构：
```
{
  "type": "object",
  "properties": {
    "name": { "type": "string", "description": "以 .zip 结尾的可选备份文件名。" }
  },
  "required": []
}
```

restore_backup：使用现有备份键还原实例。破坏性操作：会替换所有当前数据。需要 confirm: true。

输入架构：

{
  "type": "object",
  "properties": {
    "key": { "type": "string", "description": "来自 list_backups 的备份文件键。" },
    "confirm": { "type": "boolean", "description": "必须明确设置为 true。" }
  },
  "required": ["key", "confirm"]
}

设置管理

注意： 设置 API 需要超级用户身份验证。服务器返回的机密信息（SMTP 密码、S3 密钥、OAuth2 客户端机密）会以 "******" 掩码显示；对于这些字段，update_settings 需要提供真实的新值（PATCH 语义——省略的字段会保留已存储的值）。

get_settings：获取所有应用设置（部分包括：meta、logs、smtp、batch、backups、s3、rateLimits 等）。
- 输入架构：{ "type": "object", "properties": {}, "additionalProperties": false }

update_settings：使用部分载荷批量更新设置。

输入架构：

{
  "type": "object",
  "properties": {
    "data": { "type": "object", "description": "部分设置载荷，例如：{ \"logs\": { \"maxDays\": 14 } }。", "additionalProperties": true }
  },
  "required": ["data"]
}

SQL 执行（run_sql — 安全门控）

run_sql 会以超级用户权限对 PocketBase 实例执行任意原始 SQL（服务器 >= v0.39，端点 POST /api/sql）。由于 MCP 服务通常由大模型驱动，而大模型可能会受到其读取数据中的提示词注入影响，因此此工具的影响范围远大于记录级工具，所以：

默认禁用。 此工具始终会列出（以保持契约稳定），但除非 MCP 进程启动时设置了 POCKETBASE_ENABLE_SQL=true，否则每次调用都会返回说明性错误。门控关闭时不会发出网络请求。
不设限制。 没有只读模式：修改或删除数据的 SQL 语句（UPDATE、DELETE、DROP、PRAGMA 等）与 SELECT 一样都可执行。仅在完全信任的实例上启用此门控，并尽可能使用数据副本（PocketBase 是单文件应用——请先使用 create_backup 备份）。
可审计。 SQL 调用会记录在 PocketBase 请求日志中（POST /api/sql），因此可以通过 list_logs 还原执行过的操作。

仅当你接受相关风险时，才明确启用：

POCKETBASE_ENABLE_SQL=true node build/index.js

启用后的典型（只读）用法：

{ "name": "run_sql", "arguments": { "query": "SELECT COUNT(*) AS n FROM posts" } }

迁移管理

set_migrations_directory：设置创建和读取迁移文件的目录。

输入架构：

{
  "type": "object",
  "properties": {
    "customPath": { 
      "type": "string", 
      "description": "迁移文件的自定义路径。如果未提供，默认为当前工作目录中的 'pb_migrations'。" 
    }
  }
}

create_migration：创建一个新的空 PocketBase 迁移文件，文件名包含时间戳。

输入架构：

{
  "type": "object",
  "properties": {
    "description": { 
      "type": "string", 
      "description": "迁移文件名的简短描述（例如，'add_user_email_index'）。" 
    }
  },
  "required": ["description"]
}

create_collection_migration：专门用于创建新 PocketBase 集合的迁移文件。

输入架构：

{
  "type": "object",
  "properties": {
    "description": { 
      "type": "string", 
      "description": "可选的文件名描述覆盖值。" 
    },
    "collectionDefinition": {
      "type": "object",
      "description": "新集合的完整架构定义（包括名称、ID、字段、规则等）。",
      "additionalProperties": true
    }
  },
  "required": ["collectionDefinition"]
}

add_field_migration：创建用于向现有集合添加字段的迁移文件。

输入架构：

{
  "type": "object",
  "properties": {
    "collectionNameOrId": { 
      "type": "string", 
      "description": "要更新的集合名称或 ID。" 
    },
    "fieldDefinition": {
      "type": "object",
      "description": "新字段的架构定义。",
      "additionalProperties": true
    },
    "description": { 
      "type": "string", 
      "description": "可选的文件名描述覆盖值。" 
    }
  },
  "required": ["collectionNameOrId", "fieldDefinition"]
}

list_migrations：列出 PocketBase 迁移目录中的所有迁移文件。
- 输入架构：
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

apply_migration：应用指定的迁移文件。

输入架构：

{
  "type": "object",
  "properties": {
    "migrationFile": { 
      "type": "string", 
      "description": "要应用的迁移文件名。" 
    }
  },
  "required": ["migrationFile"]
}

revert_migration：回滚指定的迁移文件。

输入架构：

{
  "type": "object",
  "properties": {
    "migrationFile": { 
      "type": "string", 
      "description": "要回滚的迁移文件名。" 
    }
  },
  "required": ["migrationFile"]
}

apply_all_migrations：应用所有待处理的迁移。

输入架构：

{
  "type": "object",
  "properties": {
    "appliedMigrations": { 
      "type": "array", 
      "items": { "type": "string" },
      "description": "已应用迁移文件名的数组。" 
    }
  }
}

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 服务包含一个用于管理数据库架构变更的迁移系统。此系统支持：

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

apply/revert 的工作方式（及其限制）

此 MCP 生成的迁移文件（create_collection_migration、add_field_migration）包含机器可读的标记注释（// mcp-migration-meta: {...}），以纯数据形式描述其操作。apply_migration、revert_migration、apply_all_migrations 和 revert_to_migration 通过 PocketBase REST API（pb.collections.*）执行这些操作，这是 MCP 客户端唯一可用的通道。

不包含该标记的迁移文件（例如，使用 ./pocketbase migrate create 创建的手写服务端 JSVM 迁移）使用服务端 JSVM API（migrate()、new Collection()、app.save()），而 REST 客户端无法使用此 API。无法通过此 MCP 应用这些迁移；应用工具会返回说明性错误，并提示在 PocketBase 主机上运行 ./pocketbase migrate up。（早期版本曾尝试通过 new Function 在本地执行这些文件，但总是在运行时失败。）

已应用状态不会存储在服务端：apply_all_migrations / revert_to_migration 接受一个 appliedMigrations 数组参数（REST 客户端无法访问服务端的 _migrations 表）。请在自己的工具中维护该列表，或单独应用/回退文件。

生成的文件仍是有效的 JSVM 迁移，因此也可以在主机上使用 ./pocketbase migrate up 应用同一文件（此时 PocketBase 会在自己的 _migrations 表中跟踪状态——不要对同一文件混用这两种执行方式）。

迁移文件格式

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

// 1744005374_update_transactions_add_debt_link.js
/// <reference path="../pb_data/types.d.ts" />
// mcp-migration-meta: {"ops":{"up":[...],"down":[...]}}   <- only in MCP-generated files
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": {
    // ... 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",
        "list_cron_jobs",
        "run_cron_job"
      ] // Suggested auto-approve settings
    }

    // ... other servers might be listed here ...
  }
}

保存设置文件。 Cline 应会自动检测更改并连接到服务。之后即可使用上面列出的工具。

故障排除

每次请求都返回 HTTP 403：从 PocketBase v0.38 起，可以启用超级用户 IP 白名单（管理界面 -> 设置）。如果已启用，请添加运行此 MCP 服务的机器的 IP，或禁用白名单。
FATAL: POCKETBASE_ADMIN_TOKEN environment variable is required：未设置令牌环境变量；请在 PocketBase 管理界面（超级用户 -> API keys）中生成 API 密钥，并设置 POCKETBASE_ADMIN_TOKEN。
启动时 stderr 中出现健康检查警告：配置的 POCKETBASE_API_URL 无法访问（实例已停止或 URL 错误）。MCP 仍会启动，因此 tools/list 可以正常工作，但在实例可访问之前，工具调用会失败。
Cannot apply ...: This migration file does not contain MCP metadata：该文件是服务端 JSVM 迁移；请改为在 PocketBase 主机上运行 ./pocketbase migrate up（参见 Migration System）。

依赖项

@modelcontextprotocol/sdk (^1.30.0)
pocketbase (^0.28.1)
typescript（开发依赖）
@types/node（开发依赖）

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

PocketBase MCP Server

关于 PocketBase MCP Server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

PocketBase MCP 服务

兼容性

安装

通过 Smithery 安装

测试

配置

可用工具

记录管理

geoPoint 筛选示例

集合管理

日志管理

定时任务管理

备份管理

设置管理

SQL 执行（run_sql — 安全门控）

迁移管理

迁移系统

apply/revert 的工作方式（及其限制）

迁移文件格式

使用示例

Cline 安装

故障排除

依赖项

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？