PocketBase MCP Server

A Model Context Protocol (MCP) server for managing a PocketBase instance from chat. Works with Claude Desktop, Cursor, OpenCode, and any MCP-compatible client.

Features

• Auto-login: Authenticates as superuser on startup and refreshes tokens automatically

• 30+ tools covering the full PocketBase admin API:

  • Collections: list, get, create, update, delete, truncate, import, scaffolds

  • Records: list, get, create, update, delete, batch operations

  • Auth: password auth, impersonation, verification, password reset, email change

  • Files: file token generation, URL building

  • Logs: list, get, stats, truncate

  • Settings: get/update settings, test email, test S3

  • Backups: list, create, delete, restore, download, upload

  • Crons: list, run

  • System: health check

  • Raw request: escape hatch for any PocketBase API endpoint

• Token refresh: Automatically re-authenticates on 401/403 errors

• Local test setup: Docker-based PocketBase instance with e2e tests

Related MCP server: PocketBase MCP Server

Quick Start

1. Install dependencies

npm install

2. Build the server

npm run build

3. Configure your MCP client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pocketbase": {
      "command": "node",
      "args": ["/absolute/path/to/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_SUPERUSER_EMAIL": "admin@example.com",
        "POCKETBASE_SUPERUSER_PASSWORD": "your-password"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "pocketbase": {
      "command": "node",
      "args": ["/absolute/path/to/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_SUPERUSER_EMAIL": "admin@example.com",
        "POCKETBASE_SUPERUSER_PASSWORD": "your-password"
      }
    }
  }
}

OpenCode

Add to opencode.json in your project or ~/.config/opencode/config.json globally:

{
  "mcp": {
    "pocketbase": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_SUPERUSER_EMAIL": "admin@example.com",
        "POCKETBASE_SUPERUSER_PASSWORD": "your-password"
      }
    }
  }
}

VS Code

Create .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "pocketbase-email",
      "description": "PocketBase superuser email",
      "password": false
    },
    {
      "type": "promptString",
      "id": "pocketbase-password",
      "description": "PocketBase superuser password",
      "password": true
    }
  ],
  "servers": {
    "pocketbase": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_SUPERUSER_EMAIL": "${input:pocketbase-email}",
        "POCKETBASE_SUPERUSER_PASSWORD": "${input:pocketbase-password}"
      }
    }
  }
}

Environment Variables

Available Tools

Collections

• list_collections — List all collections (paginated)

• get_collection — Get a single collection by name or ID

• create_collection — Create a new collection (base, auth, or view)

• update_collection — Update an existing collection

• delete_collection — Delete a collection and all its records

• truncate_collection — Delete all records (keeps schema)

• import_collections — Bulk import collections

• list_collection_scaffolds — Get default collection templates

Records

• list_records — List records with filtering, sorting, pagination

• get_record — Get a single record by ID

• create_record — Create a new record

• update_record — Update an existing record

• delete_record — Delete a record

• batch_records — Batch create/update/upsert/delete in one transaction

Authentication

• list_auth_methods — List allowed auth methods for a collection

• auth_with_password — Authenticate a user with email/username + password

• impersonate_user — Impersonate an auth record (superuser only)

• request_verification — Send email verification request

• confirm_verification — Confirm email verification

• request_password_reset — Send password reset email

• confirm_password_reset — Confirm password reset

• request_email_change — Request email change

• confirm_email_change — Confirm email change

Files

• get_file_token — Generate a short-lived file access token

• build_file_url — Build a public file URL for a record's file field

Logs

• list_logs — List request logs (paginated)

• get_log — Get a single log entry

• log_stats — Get hourly aggregated log statistics

• truncate_logs — Delete all logs

Settings

• get_settings — Get all application settings (secrets redacted)

• update_settings — Update application settings

• test_email — Send a test email

• test_s3 — Test S3 storage connection

Backups

• list_backups — List all backup files

• create_backup — Create a new backup

• delete_backup — Delete a backup

• restore_backup — Restore a backup (restarts PocketBase)

• get_backup_download_url — Generate a download URL

• upload_backup — Upload a backup file

Crons

• list_crons — List all registered cron jobs

• run_cron — Manually trigger a cron job

System

• health_check — Check PocketBase API health

Raw

• raw_request — Send a raw HTTP request to any PocketBase API endpoint

Local Development

Run with MCP Inspector

npm run inspect

Then open http://localhost:5173 in your browser to interactively test tools.

Run the server directly

POCKETBASE_URL=http://127.0.0.1:8090 \
POCKETBASE_SUPERUSER_EMAIL=admin@test.local \
POCKETBASE_SUPERUSER_PASSWORD=password123 \
npm run dev

Local Test Setup

The test/local/ directory contains a Docker-based PocketBase instance for testing:

cd test/local
docker compose up -d
./setup.sh

This starts PocketBase on http://127.0.0.1:8090 with:

• Email: admin@test.local

• Password: SuperSecret123!

Run the e2e test suite:

cd ../..
npm run test:e2e

See test/local/README.md for details.

Docker

Build and run with Docker:

docker build -t pocketbase-mcp .

docker run -i --rm \
  -e POCKETBASE_URL=http://host.docker.internal:8090 \
  -e POCKETBASE_SUPERUSER_EMAIL=admin@example.com \
  -e POCKETBASE_SUPERUSER_PASSWORD=your-password \
  pocketbase-mcp

Use host.docker.internal to access PocketBase running on your host machine.

Architecture

• TypeScript + Node 22 — modern, type-safe

• @modelcontextprotocol/server v2 — latest MCP SDK with registerTool() API

• Native fetch — no PocketBase SDK dependency, explicit token management

• Auto-login + refresh — authenticates on startup, re-auths on 401/403

• stdio transport — works with all MCP clients (Claude Desktop, Cursor, OpenCode, etc.)

License

MIT