pocketbase-mcp-bridge

PocketBase MCP Server

A complete Model Context Protocol server for PocketBase. It exposes the full PocketBase management surface — collections, records, authentication, files, logs, settings, backups and crons — as MCP tools that an AI assistant (Claude Desktop, Claude Code, Cursor, etc.) can call directly.

Built and validated against PocketBase v0.39.6 using the official pocketbase JS SDK.

Features

55 tools across every part of the PocketBase API:

Highlights:

• Auto-authentication as a superuser from environment variables, with transparent re-auth when the token expires.
• File uploads/downloads to/from the local filesystem (multipart handled for you).
• Transactional batch operations (create/update/delete/upsert) in one request.
• Non-destructive user auth — authenticating as an end user never clobbers the MCP's own superuser session.
• send_raw_request guarantees completeness: anything the dedicated tools don't cover (custom routes, new API features) is still reachable.

Configuration

The server reads its connection settings from environment variables:

* Required unless POCKETBASE_TOKEN is provided.

MCP client config

Add the server to your MCP client (Claude Desktop claude_desktop_config.json, Claude Code, Cursor, …). The recommended, zero-install form uses npx:

{
  "mcpServers": {
    "pocketbase": {
      "command": "npx",
      "args": ["-y", "pocketbase-mcp-bridge"],
      "env": {
        "POCKETBASE_URL": "",
        "POCKETBASE_ADMIN_EMAIL": "",
        "POCKETBASE_ADMIN_PASSWORD": ""
      }
    }
  }
}

Fill the three env values with your instance URL and superuser credentials (keep secrets in env, never in args). The -y flag lets clients launch the server non-interactively.

{
  "mcpServers": {
    "pocketbase": {
      "command": "node",
      "args": ["/absolute/path/to/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "",
        "POCKETBASE_ADMIN_EMAIL": "",
        "POCKETBASE_ADMIN_PASSWORD": ""
      }
    }
  }
}

{
  "mcpServers": {
    "pocketbase": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "POCKETBASE_URL",
        "-e", "POCKETBASE_ADMIN_EMAIL",
        "-e", "POCKETBASE_ADMIN_PASSWORD",
        "pocketbase-mcp-bridge"
      ],
      "env": {
        "POCKETBASE_URL": "http://host.docker.internal:8090",
        "POCKETBASE_ADMIN_EMAIL": "",
        "POCKETBASE_ADMIN_PASSWORD": ""
      }
    }
  }
}

Installation

The published package works out of the box with npx -y pocketbase-mcp-bridge (see above) — no manual install needed once it is on npm.

To build from source:

git clone https://github.com/nestebe/pocketbase-mcp.git
cd pocketbase-mcp
npm install
npm run build      # compiles TypeScript to dist/

The entry point is dist/index.js (a stdio MCP server with a #!/usr/bin/env node shebang, also exposed as the pocketbase-mcp-bridge bin).

Docker image

docker build -t pocketbase-mcp-bridge .
docker run -i --rm \
  -e POCKETBASE_URL=http://host.docker.internal:8090 \
  -e POCKETBASE_ADMIN_EMAIL=admin@example.com \
  -e POCKETBASE_ADMIN_PASSWORD=secret \
  pocketbase-mcp-bridge

The image is a stdio server — run it with -i (interactive) so the MCP client can talk to it over stdin/stdout.

Local test instance (docker-test/)

A ready-to-run PocketBase is provided for development and validation:

docker compose -f docker-test/docker-compose.yml up -d

• Dashboard: http://localhost:8090/_/
• REST API: http://localhost:8090/api/
• Superuser (auto-created on first boot):
  • email: admin@yourdomain.com
  • password: your-secure-password-here

Stop / reset:

docker compose -f docker-test/docker-compose.yml down          # stop
docker compose -f docker-test/docker-compose.yml down -v       # stop + wipe data

Settings encryption is intentionally disabled in this local setup. For production, enable it with a 32-character key via --encryptionEnv (see the comments in docker-test/docker-compose.yml).

Run the smoke tests

With the container running:

node scripts/smoke-test.mjs             # collections, records, batch, settings, logs, crons...
node scripts/smoke-test-files-auth.mjs  # users auth, file upload/download, impersonation, backups

Both spawn the compiled server over stdio and exercise the tools against the live instance.

Usage notes & gotchas

• PocketBase 0.23+ removed implicit created/updated fields. New base collections have no timestamp columns unless you add them. To sort by creation date, add autodate fields when creating the collection:

  { "name": "created", "type": "autodate", "onCreate": true },
  { "name": "updated", "type": "autodate", "onCreate": true, "onUpdate": true }
  

  Tip: call get_collection_scaffolds to get a template that already includes them.
• Batch API is disabled by default. The batch tool returns "Batch requests are not allowed" until you enable it: update_settings { "data": { "batch": { "enabled": true } } }.
• Admins are now "superusers" — a special _superusers auth collection. The *_superuser tools are convenience wrappers over record operations on it.
• Email-dependent flows (verification, password reset, OTP, test email) require SMTP to be configured in settings.
• Filtering & sorting use PocketBase's expression syntax, e.g. filter: 'status = "active" && created > "2024-01-01"', sort: '-created,title'. Use expand to inline relations (e.g. expand: 'author,comments_via_post').

Development

src/
  index.ts          # stdio entry point + eager auth
  server.ts         # builds the McpServer and registers every tool group
  config.ts         # env parsing
  pocketbase.ts     # SDK client singleton, auth, withAuth() retry helper
  util.ts           # tool result / error helpers
  formdata.ts       # multipart body builder for file uploads
  tools/
    health.ts collections.ts records.ts auth.ts superusers.ts
    files.ts logs.ts settings.ts backups.ts crons.ts raw.ts

npm run build     # tsc -> dist/
npm run watch     # tsc --watch
npm run dev       # run from TS via tsx (no build step)

Publishing (maintainers)

The package is distributed on npm and listed in the official MCP Registry. Both are automated by .github/workflows/release.yml, triggered when you publish a GitHub Release.

One-time setup

• Create an npm Automation (or granular, read+write) access token and add it as the repository secret NPM_TOKEN. (Later you can migrate to tokenless Trusted Publishing / OIDC and drop the secret.)
• The MCP Registry step uses GitHub OIDC (id-token: write) — no secret needed. It publishes under the io.github.nestebe/* namespace, verified by the mcpName field in package.json matching the name in server.json.

Cut a release

npm version patch          # or minor / major — bumps package.json + creates a git tag
# keep server.json "version" in sync with package.json, then commit it
git push --follow-tags
gh release create v1.0.0 --generate-notes   # publishing the release fires the workflow

The workflow then: builds → npm publish --provenance --access public → publishes the server.json metadata to the registry.

Manual publish (without CI)

npm publish --access public            # npm (must include the mcpName field)
# then, from the repo root:
mcp-publisher login github             # interactive GitHub OAuth (owner of "nestebe")
mcp-publisher publish                  # pushes server.json to registry.modelcontextprotocol.io

Before releasing, verify the tarball and package health:

npm publish --dry-run     # inspect exactly what ships
npx publint               # lint package.json/exports/bin for publish issues

License

MIT © Nicolas ESTEBE