gaspechak-pocketbase-mcp

Schema-aware, token-efficient MCP server for one PocketBase instance.

Each MCP process connects to a single PocketBase URL. For dev, homolog, and production, configure multiple MCP servers in your client, for example pocketbase-dev and pocketbase-prod, each with its own PB_URL.

Quick Start

npx gaspechak-pocketbase-mcp

With superuser auto-login:

PB_URL=http://127.0.0.1:8090 [email protected] PB_PASSWORD=yourpassword npx gaspechak-pocketbase-mcp

| Variable | Description | Default | | --- | --- | --- | | PB_URL | PocketBase instance URL | http://127.0.0.1:8090 | | PB_EMAIL | Superuser email for auto-login | unset | | PB_PASSWORD | Superuser password for auto-login | unset | | PB_TOKEN | Pre-existing auth token | unset | | PB_TIMEOUT_MS | HTTP timeout per request | 15000 | | PB_SCHEMA_CACHE_TTL_MS | In-memory schema cache TTL | 60000 | | PB_BULK_CONCURRENCY | Bulk mutation concurrency | 10 |

Multiple Instances

Runtime environment switching is intentionally not supported. Declare one MCP server per PocketBase instance in your client:

{
  "mcpServers": {
    "pocketbase-dev": {
      "command": "npx",
      "args": ["-y", "gaspechak-pocketbase-mcp"],
      "env": {
        "PB_URL": "http://127.0.0.1:8090",
        "PB_EMAIL": "[email protected]",
        "PB_PASSWORD": "dev-password"
      }
    },
    "pocketbase-prod": {
      "command": "npx",
      "args": ["-y", "gaspechak-pocketbase-mcp"],
      "env": {
        "PB_URL": "https://pb.example.com",
        "PB_TOKEN": "prod-token"
      }
    }
  }
}

Tools

The server exposes 16 compact tools:

| Tool | Purpose | | --- | --- | | pb_health | Check connectivity, version, auth status, and configured URL | | pb_auth_superuser | Authenticate this process as a superuser | | pb_auth_user | Authenticate an auth user and return a tokenRef | | pb_schema | Read compact schema summary or one collection | | pb_collection_create | Create base, auth, or view collections | | pb_collection_patch | Safely patch fields, rules, indexes, names, or view query | | pb_collection_delete | Delete a collection after explicit confirmation | | pb_record_list | List records with compact defaults and auto fields | | pb_record_get | Get one record with optional fields and expand | | pb_record_mutate | Create, update, delete, or bulk mutate records | | pb_rules_test | Test record API rules as public or user token | | pb_backup | Create, list, restore, or generate backup download URL | | pb_logs | Query request logs with redaction by default | | pb_file_url | Build file URLs and store protected tokens as refs | | pb_settings | Get or update settings with redaction by default | | pb_help | Return one short help topic |

Token-Efficient Defaults

• pb_schema returns a compact schema map first; request a collection or mode=raw only when needed.
• pb_record_list defaults to perPage=10, skipTotal=true, and schema-derived fields.
• Large text/editor fields are selected with :excerpt(200,true) when fields are inferred.
• Tool results include structuredContent; text content is compact JSON unless a tool intentionally returns help markdown.
• User, file, and backup tokens are stored in memory and returned as tokenRef by default.
• Settings and logs are redacted by default.

MCP Resources

Large guidance is exposed as resources instead of tool descriptions:

| Resource | Content | | --- | --- | | pocketbase://help/filters | Filter operators, macros, relations, and field selection | | pocketbase://help/fields | Field type reference and relation target resolution | | pocketbase://help/rules | API rule values and common patterns | | pocketbase://help/records | Record defaults and mutation notes | | pocketbase://schema/summary | Live compact schema summary | | pocketbase://schema/collections/{name} | Live compact schema for one collection |

Integration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pocketbase": {
      "command": "npx",
      "args": ["-y", "gaspechak-pocketbase-mcp"],
      "env": {
        "PB_URL": "http://127.0.0.1:8090",
        "PB_EMAIL": "[email protected]",
        "PB_PASSWORD": "yourpassword"
      }
    }
  }
}

VS Code / GitHub Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "pocketbase": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "gaspechak-pocketbase-mcp"],
      "env": {
        "PB_URL": "http://127.0.0.1:8090",
        "PB_EMAIL": "[email protected]",
        "PB_PASSWORD": "yourpassword"
      }
    }
  }
}

Development

git clone https://github.com/Gaspechak/pocketbase-mcp.git
cd pocketbase-mcp
npm install
npm test

Run locally:

PB_URL=http://127.0.0.1:8090 [email protected] PB_PASSWORD=secret node dist/index.js

Breaking Changes in 2.0.0

• Removed PB_ENV, PB_ENVIRONMENT, and all PB_<ENV>_* variables.
• Removed runtime environment switching tools.
• Replaced legacy tool names with the 16 pb_* tools listed above.
• Replaced pretty-printed JSON text responses with compact structured results.

License

MIT