Fully Capable Pocketbase Mcp Server

PocketBase MCP サーバー

PocketBase インスタンスを管理するためのツールを提供する、包括的な Model Context Protocol（MCP）サーバーです。このサーバーを使うと、LLM は標準化されたプロトコルを通じて PocketBase データベースとやり取りできます。

概要

この MCP サーバーは、PocketBase の機能を、MCP 対応のあらゆるクライアント（Claude Desktop、Cursor、その他の LLM アプリケーションなど）が利用できるツールとして公開します。主要な操作を網羅する 60 以上のツールを備え、PocketBase の機能に幅広くアクセスできます。

機能

コレクション管理

• コレクションの一覧表示、取得、作成、更新、削除
• コレクションの一括インポート／エクスポート
• スキーマ管理を全面的にサポート

レコード操作

• フィルタリング、並べ替え、ページネーションに対応した CRUD 操作
• ページネーションなしですべてのレコードを取得する getFullList
• 最初に一致するレコードを検索する getFirstListItem
• フィールド選択とリレーション展開に対応した高度なクエリ
• 効率的な一括処理のためのバッチ操作

認証とユーザー管理

• 複数の認証方法：パスワード、OAuth2、OTP
• 登録、ログイン、パスワードリセット、メール認証を含む認証フローを全面的にサポート
• メールアドレス変更機能
• 認証トークンの更新
• コレクションで利用可能な認証方法の一覧表示

ファイル管理

• サムネイルに対応したファイル URL の生成
• プライベートファイルトークンの生成
• ダウンロード強制に対応

システム操作

• ヘルスモニタリング
• 設定管理
• 統計情報付きのログ表示
• cron ジョブの管理と実行

バックアップと復元

• バックアップの作成、一覧表示、ダウンロード、削除
• バックアップ全体の復元に対応

フック管理

• JavaScript フックの一覧表示、読み取り、作成、削除
• よく使われるパターン向けの事前構築済みテンプレート

インストール

npm install
npm run build

設定

接続先の PocketBase インスタンスは、以下の順に優先される設定を使って指定できます。

1. ローカル設定ファイル（プロジェクトディレクトリ内の .pocketbase-mcp.json）：

   {
     "url": "http://localhost:8091"
   }
   

2. 環境変数：

   • POCKETBASE_URL：PocketBase インスタンスの URL

3. デフォルト：http://127.0.0.1:8090

複数プロジェクトの設定

オプション 1：プロジェクト固有の設定（推奨）

各プロジェクトに独自の MCP 設定を指定できます。

# In project directory
claude mcp add-json pocketbase '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "http://localhost:8091"}}' --scope project

オプション 2：設定ファイル

プロジェクトのルートに .pocketbase-mcp.json を作成します。

{
  "url": "https://api.myproject.com"
}

オプション 3：名前付きサーバーを複数設定

異なる PocketBase インスタンスをグローバル設定に追加します。

claude mcp add-json pb-local '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "http://localhost:8090"}}'
claude mcp add-json pb-prod '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "https://api.myapp.com"}}'

Claude Desktop での使用方法

この設定を Claude Desktop の MCP 設定に追加します。

{
  "mcpServers": {
    "pocketbase": {
      "command": "node",
      "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"],
      "env": {
        "POCKETBASE_URL": "http://localhost:8090"
      }
    }
  }
}

利用可能なツール

コレクション管理ツール

• list_collections - ページネーションとフィルタリングに対応した、すべてのコレクションの一覧表示
• get_collection - ID または名前で特定のコレクションを取得
• create_collection - スキーマを指定して新しいコレクションを作成
• update_collection - コレクションの設定とスキーマを更新
• delete_collection - コレクションを削除
• import_collections - 複数のコレクションを一括インポート

レコード管理ツール

• list_records - ページネーション、フィルタリング、並べ替え、フィールド選択に対応したレコードの一覧表示
• get_full_list - ページネーションなしですべてのレコードを取得（一括処理）
• get_first_list_item - フィルターに一致する最初のレコードを取得
• get_record - ID で特定のレコードを取得
• create_record - 新しいレコードを作成
• update_record - 既存のレコードを更新
• delete_record - レコードを削除

バッチ操作

• batch_create - 1 回のトランザクションで複数のレコードを作成
• batch_update - 1 回のトランザクションで複数のレコードを更新
• batch_delete - 1 回のトランザクションで複数のレコードを削除
• batch_upsert - 1 回のトランザクションで複数のレコードをアップサート

認証ツール

• list_auth_methods - 利用可能な認証方法を取得します
• auth_with_password - メールアドレス／ユーザー名とパスワードで認証します
• auth_with_oauth2 - OAuth2 認証 URL を取得します
• auth_refresh - 認証トークンを更新します
• request_otp - メール認証用の OTP をリクエストします
• auth_with_otp - OTP で認証します
• request_password_reset - パスワードリセット用のメールを送信します
• confirm_password_reset - トークンを使ってパスワードリセットを確定します
• request_verification - 確認用メールを送信します
• confirm_verification - メールアドレスの確認を完了します
• request_email_change - メールアドレスの変更をリクエストします
• confirm_email_change - メールアドレスの変更を確定します

ファイル管理ツール

• get_file_url - オプションを指定してファイルにアクセスする URL を生成します
• get_file_token - 非公開ファイルのアクセストークンを取得します

ログ管理ツール

• list_logs - フィルタリングしてシステムログを一覧表示します
• get_log - 特定のログエントリを取得します
• get_log_stats - ログの統計情報を取得します

Cron ジョブツール

• list_cron_jobs - すべての Cron ジョブを一覧表示します
• run_cron_job - Cron ジョブを手動で実行します

システムツール

• get_health - PocketBase のヘルスステータスを確認します
• get_settings - PocketBase の設定を取得します（管理者認証が必要です）
• update_settings - PocketBase の設定を更新します（管理者認証が必要です）

バックアップツール

• create_backup - バックアップを作成します
• list_backups - 利用可能なバックアップを一覧表示します
• download_backup - バックアップのダウンロード URL を取得します
• delete_backup - バックアップを削除します
• restore_backup - バックアップから復元します

フック管理ツール

• list_hooks - pb_hooks ディレクトリ内の JavaScript フックファイルを一覧表示します
• read_hook - フックファイルの内容を読み取ります
• create_hook - JavaScript フックファイルを作成または更新します
• delete_hook - フックファイルを削除します
• create_hook_template - 一般的なパターン用のフックテンプレートを生成します：
  • record-validation：レコードのフィールド検証
  • record-auth：カスタム認証ロジック
  • custom-route：API エンドポイントの作成
  • file-upload：ファイルアップロードの検証
  • scheduled-task：Cron ジョブの設定

ツールの例

フィルタリングしてレコードを一覧表示

{
  "tool": "list_records",
  "arguments": {
    "collection": "posts",
    "filter": "published = true && created >= '2024-01-01'",
    "sort": "-created",
    "expand": "author",
    "fields": "id,title,content,author",
    "skipTotal": true
  }
}

ページネーションなしですべてのレコードを取得

{
  "tool": "get_full_list",
  "arguments": {
    "collection": "categories",
    "sort": "name",
    "batch": 1000
  }
}

レコードの一括作成

{
  "tool": "batch_create",
  "arguments": {
    "requests": [
      {
        "collection": "posts",
        "data": {
          "title": "First Post",
          "content": "Content 1"
        }
      },
      {
        "collection": "posts",
        "data": {
          "title": "Second Post",
          "content": "Content 2"
        }
      }
    ]
  }
}

OAuth2 認証

{
  "tool": "auth_with_oauth2",
  "arguments": {
    "collection": "users",
    "provider": "google",
    "redirectURL": "https://myapp.com/auth/callback"
  }
}

OTP 認証フロー

// Step 1: Request OTP
{
  "tool": "request_otp",
  "arguments": {
    "collection": "users",
    "email": "[email protected]"
  }
}

// Step 2: Authenticate with OTP
{
  "tool": "auth_with_otp",
  "arguments": {
    "collection": "users",
    "otpId": "otp_id_from_step_1",
    "password": "123456"
  }
}

サムネイル付きのファイル URL を取得

{
  "tool": "get_file_url",
  "arguments": {
    "collection": "products",
    "recordId": "abc123",
    "filename": "photo.jpg",
    "thumb": "300x200"
  }
}

フックテンプレートを作成

{
  "tool": "create_hook_template",
  "arguments": {
    "type": "record-validation",
    "collection": "posts"
  }
}

クエリ構文

MCP サーバーは PocketBase の完全なクエリ構文をサポートしています：

フィルターの例

• title = "example" - 完全一致
• created >= "2024-01-01" - 日付の比較
• title ~ "search" - テキストを含む
• tags ?~ "important" - 配列要素のいずれかが含む
• user.name = "John" - ネストされたフィールドへのアクセス

ソートの例

• created - 作成日時の昇順
• -created - 作成日時の降順
• name,-created - 複数のソートフィールド

展開の例

• author - 単一のリレーションを展開
• author,tags - 複数のリレーションを展開
• author.profile - ネストされた展開

フィールドの選択

• id,title,content - 特定のフィールドを選択
• *,expand.author.name - 展開されたフィールドを含める

パフォーマンスの最適化

• 合計件数が不要な場合は skipTotal: true を使用します
• データ転送量を制限するには fields パラメーターを使用します
• 大規模なデータセットには、適切なバッチサイズを指定して get_full_list を使用します
• レコードを一括変更するには、一括操作を使用します

開発

開発モードでの実行

npm run dev

ビルド

npm run build

アーキテクチャ

MCP サーバーは Model Context Protocol の仕様に準拠しています：

1. MCP Server：ツールの登録と実行を処理します
2. PocketBase Client：公式の PocketBase JavaScript SDK を使用します
3. Tool Handlers：適切なエラー処理を備えた、PocketBase の特定の操作を実装します

エラー処理

すべてのツールに包括的なエラー処理が含まれており、説明的なエラーメッセージを返します。一般的なエラーは次のとおりです：

• 認証が無効
• 必須フィールドが不足
• ネットワーク接続の問題
• 権限拒否エラー

セキュリティに関する考慮事項

• 管理者操作には適切な認証が必要です
• 機密性の高い設定には環境変数を使用してください
• サーバーはPocketBaseのセキュリティモデルとアクセスルールを継承します
• OAuth2のstateパラメーターは安全に処理されます

バージョン互換性

• PocketBase v0.20.0以上が必要です
• PocketBase JavaScript SDK v0.21.0+を使用します
• MCPプロトコルバージョン1.0を実装しています

コントリビューション

コントリビューションを歓迎します！新しいツールを追加する場合は、次の点を確認してください。

• 既存の命名パターンに従う
• 適切なTypeScript型を含める
• 包括的なエラーハンドリングを行う
• このREADMEにドキュメントを記載する

ライセンス

ISC