PocketBase MCP 서버
PocketBase 인스턴스와 상호 작용하는 MCP 서버입니다. PocketBase 컬렉션의 레코드와 파일을 가져오고, 나열하고, 생성하고, 업데이트하고, 관리할 수 있습니다.
설치
Smithery를 통해 설치
Smithery를 통해 Claude Desktop에 PocketBase MCP Server를 자동으로 설치하려면:
지엑스피1
- 저장소를 복제합니다(아직 복제하지 않았다면):
git clone <repository_url>
cd pocketbase-mcp
- 종속성 설치:
- 서버를 빌드하세요:이렇게 하면 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 : 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"
]
}
컬렉션 관리
- 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 인스턴스 또는 구성에서는 사용할 수 없습니다. 이러한 도구는 https://pocketbase.io/docs/api-logs/ 에 설명된 대로 PocketBase 로그 API와 상호 작용합니다.
- 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 서버에는 데이터베이스 스키마 변경 관리를 위한 포괄적인 마이그레이션 시스템이 포함되어 있습니다. 이 시스템을 통해 다음을 수행할 수 있습니다.
- 타임스탬프 이름으로 마이그레이션 파일 만들기
- 일반적인 작업(컬렉션 생성, 필드 추가)에 대한 마이그레이션 생성
- 개별적으로 또는 일괄적으로 마이그레이션을 적용하고 되돌립니다.
- 어떤 마이그레이션이 적용되었는지 추적합니다.
마이그레이션 파일 형식
마이그레이션 파일은 타임스탬프 접두사와 설명적 이름을 가진 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();
});
각 마이그레이션에는 변경 사항을 적용하는 "위로" 기능과 변경 사항을 되돌리는 "아래로" 기능이 있습니다.
사용 예
사용자 정의 마이그레이션 디렉토리 설정:
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과 함께 사용하려면 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"
] // Suggested auto-approve settings
}
// ... other servers might be listed here ...
}
}
- 설정 파일을 저장하세요. Cline이 자동으로 변경 사항을 감지하고 서버에 연결할 것입니다. 그러면 위에 나열된 도구를 사용할 수 있습니다.
종속성
@modelcontextprotocol/sdkpocketbasetypescriptts-node (개발 종속성)@types/node (개발 종속성)