MCP 服务器

PocketBase MCP Server

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

README

PocketBase MCP 服务器

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

安装

克隆存储库（如果尚未克隆）：

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 KEYS。

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

可用工具

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

记录管理

fetch_record: 从 PocketBase 集合中按 ID 获取单个记录。

输入模式:

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    },
    "id": {
      "type": "string",
      "description": "要获取的记录的 ID。"
    }
  },
  "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": "每页的项目数（默认为 25）。",
      "minimum": 1,
      "maximum": 100
    },
    "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"
  ]
}

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": "要从中下载文件的记录的 ID。"
    },
    "fileField": {
      "type": "string",
      "description": "PocketBase 集合中文件字段的名称。"
    },
    "downloadPath": {
      "type": "string",
      "description": "应保存下载文件的路径（注意：此工具当前返回 URL，必须单独处理下载）。"
    }
  },
  "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": "PocketBase 集合的名称。"
    }
  },
  "required": [
    "collection"
  ]
}

迁移管理

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": "要还原到的迁移的名称（不包括）。 使用空字符串还原所有迁移。" 
    },
    "appliedMigrations": { 
      "type": "array", 
      "items": { "type": "string" },
      "description": "已应用的迁移文件名的数组。" 
    }
  },
  "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"
});

应用迁移：

// 应用特定的迁移
await applyMigration("1744005374_update_transactions_add_debt_link.js", pocketbaseInstance);

// 应用所有待处理的迁移
await applyAllMigrations(pocketbaseInstance);

还原迁移：

// 还原特定的迁移
await revertMigration("1744005374_update_transactions_add_debt_link.js", pocketbaseInstance);

// 还原到特定点（不包括）
await revertToMigration("1743958155_update_transactions_add_relation_to_itself.js", pocketbaseInstance);

// 还原所有迁移
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": [] // 默认自动批准设置
    }

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

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

依赖项

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

PocketBase MCP Server

README

PocketBase MCP 服务器

安装

配置

可用工具

记录管理

集合管理

迁移管理

迁移系统

迁移文件格式

使用示例

Cline 安装

依赖项

推荐服务器