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.

Alternative: run from a local build (no npm install)

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

Alternative: run via Docker

{
  "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:
• REST 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