Provides a complete MCP server for PocketBase, offering 55 tools to manage collections, records, authentication, files, logs, settings, backups, and crons in a PocketBase instance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pocketbase-mcp show me the users collection schema"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
55 tools across every part of the PocketBase API:
Area | Tools |
Health & connection |
|
Collections (schema) |
|
Records (data) |
|
Authentication |
|
Superusers (admins) |
|
Files |
|
Logs |
|
Settings |
|
Backups |
|
Crons |
|
Escape hatch |
|
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.
Related MCP server: PocketBase MCP Server
The server reads its connection settings from environment variables:
Variable | Required | Description |
| ✅ | Base URL, e.g. |
| ✅* | Superuser email. |
| ✅* | Superuser password. |
| – | Auth collection to log in against (default |
| – | Use a pre-issued token instead of email/password. |
* Required unless POCKETBASE_TOKEN is provided.
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": ""
}
}
}
}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 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-bridgeThe image is a stdio server — run it with -i (interactive) so the MCP client can talk
to it over stdin/stdout.
docker-test/)A ready-to-run PocketBase is provided for development and validation:
docker compose -f docker-test/docker-compose.yml up -dDashboard: 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 dataSettings encryption is intentionally disabled in this local setup. For production, enable it with a 32-character key via
--encryptionEnv(see the comments indocker-test/docker-compose.yml).
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, backupsBoth spawn the compiled server over stdio and exercise the tools against the live instance.
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').
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.tsnpm run build # tsc -> dist/
npm run watch # tsc --watch
npm run dev # run from TS via tsx (no build step)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 workflowThe 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.ioBefore releasing, verify the tarball and package health:
npm publish --dry-run # inspect exactly what ships
npx publint # lint package.json/exports/bin for publish issuesMIT © Nicolas ESTEBE
Return information about the current MCP authentication: PocketBase URL, the auth collection used, whether the token is valid, and the identity (id/email) of the authenticated superuser or user. The raw token is never exposed.
Inputs: no named parameters.
Complete OTP authentication using the otpId (from request_otp) and the code the user received.
Inputs: code (required), otpId (required), collection.
Authenticate an end user against an auth collection with their identity (email/username) and password. Returns the auth token and the user record. Does not affect the MCP's own superuser session. Useful to obtain a token to act on behalf of a user or to verify credentials.
Inputs: identity (required), password (required), expand, collection.
Execute multiple record operations in a single transactional request. All operations succeed or all are rolled back. Each operation has an action ('create' | 'update' | 'delete' | 'upsert'), a target collection, and depending on the action a data object and/or record id. For 'upsert', include the record 'id' inside data (creates if missing, updates if present). Note: the Batch API must be enabled in PocketBase settings (Settings > Batch API).
Inputs: operations (required).
Confirm a user's email change using the token from the confirmation email and the user's password.
Inputs: token (required), password (required), collection.
Set a new password using the reset token from the password reset email.
Inputs: token (required), password (required), passwordConfirm (required), collection.
Confirm a user's email verification using the token from the verification email.
Inputs: token (required), collection.
Create a new backup (zip snapshot of the database and storage). If basename is omitted, PocketBase auto-generates a timestamped name. Returns the backup name. Superuser only.
Inputs: basename.
Create a new collection. Provide name and type ('base', 'auth' or 'view'). Use data for the rest of the collection payload: fields (array of field definitions), API rules (listRule, viewRule, createRule, updateRule, deleteRule — string or null), indexes (array of CREATE INDEX statements), viewQuery (for view collections), and auth options for auth collections. Tip: call get_collection_scaffolds first to see the expected shape. Example field: { "name": "title", "type": "text", "required": true }. IMPORTANT (PocketBase 0.23+): 'created'/'updated' timestamps are NOT added automatically — add them explicitly as autodate fields if you need them, e.g. { "name": "created", "type": "autodate", "onCreate": true } and { "name": "updated", "type": "autodate", "onCreate": true, "onUpdate": true }.
Inputs: name (required), data, type.
Create a new record in a collection. Pass field values in data. For auth collections, include 'password' and 'passwordConfirm' (and usually 'email'). To upload files, list them in files (each maps a field name to a local file path). Relation fields accept a record id or an array of ids.
Inputs: collection (required), data, files, expand, +1 more.
Create a new superuser (admin) account. Provide email and password. The new superuser has full administrative access to the instance.
Inputs: email (required), password (required), passwordConfirm.
Delete a single backup file by its key/name. Cannot be undone. Superuser only.
Inputs: key (required).
Permanently delete a collection and ALL of its records. This cannot be undone.
Inputs: idOrName (required).
Permanently delete a single record by id. Cannot be undone.
Inputs: id (required), collection (required).
Delete a superuser (admin) account by id. At least one superuser must always remain.
Inputs: id (required).
Download a backup file to a local path on the machine running this MCP server. Superuser only.
Inputs: key (required), destPath (required).
Download a record file to a local path on the machine running this MCP server. Handles protected files automatically by requesting an access token.
Inputs: destPath (required), filename (required), recordId (required), collection (required), +2 more.
Generate a new Apple OAuth2 client secret (JWT) from your Apple developer credentials. Superuser only.
Inputs: keyId (required), teamId (required), clientId (required), duration (required), +1 more.
Build a download URL for a backup file using a fresh superuser file token. Superuser only.
Inputs: key (required).
Fetch a single collection by its id or name, including its full field schema, rules and indexes.
Inputs: idOrName (required), fields.
Return default collection templates (scaffolds) for each collection type (base, auth, view). Useful as a starting point before calling create_collection — copy a scaffold, adjust the name and fields, then create it.
Inputs: no named parameters.
Generate a short-lived file access token used to access protected files by appending it as a ?token=... query parameter to a file URL.
Inputs: no named parameters.
Build the public URL for a file stored in a record's file field. For image files you may request a thumbnail via thumb (e.g. '100x100', '100x100t', '0x100'). For protected files (collection with a non-public file field), set protected to true to embed a short-lived access token.
Inputs: filename (required), recordId (required), collection (required), thumb, +2 more.
Return the first record matching a filter expression (throws if none found). Convenient for lookups like 'email = "a@b.com"'.
Inputs: filter (required), collection (required), expand, fields.
Fetch ALL records matching a filter, auto-paginating in batches. Use for exports or small/medium collections. Prefer list_records with pagination for large datasets to avoid huge responses.
Inputs: collection (required), sort, batch, expand, +2 more.
Fetch a single log entry by its id (superuser only).
Inputs: id (required).
Return hourly aggregated log statistics, optionally filtered. Useful to chart request volume or error rates. Filter example: 'level = 0'.
Inputs: filter.
Fetch a single record by id, optionally expanding relations and selecting specific fields.
Inputs: id (required), collection (required), expand, fields.
Fetch all instance settings (app name/url, SMTP, S3 storage, S3 backups, batch API, rate limits, trusted proxy, OAuth2 secrets are redacted). Superuser only.
Inputs: no named parameters.
Check the PocketBase API health status. Does not require authentication. Returns the server code, message and health data.
Inputs: no named parameters.
Generate an auth token for an existing user without their password (superuser only). Returns a non-refreshable token valid for the given duration, useful to make API calls on behalf of a user.
Inputs: recordId (required), duration, collection.
Bulk import collections from an array of collection definitions (as exported from the PocketBase admin UI). When deleteMissing is true, collections not present in the import list are deleted — use with caution. This is the recommended way to apply a full schema in one call.
Inputs: collections (required), deleteMissing.
List the available authentication methods for an auth collection: whether password/OTP auth is enabled and the configured OAuth2 providers (Google, GitHub, etc.).
Inputs: collection.
List all available backup files (key, size, modified date). Superuser only.
Inputs: no named parameters.
List collections (database tables / schemas) with pagination, filtering and sorting. Includes system collections such as _superusers, _authOrigins, etc. Filter example: 'type = "auth"'. Sort example: '-created'.
Inputs: page, sort, fields, filter, +1 more.
List all registered cron jobs with their id and cron expression (e.g. the automatic backups job, log/token cleanup, plus any custom jobs registered via hooks). Superuser only.
Inputs: no named parameters.
List the OAuth2 providers linked to a specific user record (superuser only).
Inputs: recordId (required), collection.
List application request/activity logs with pagination, filtering and sorting (superuser only). Filter example: 'level >= 4 && data.status >= 400'. Sort defaults to newest first.
Inputs: page, sort, filter, perPage.
List records of a collection with pagination, filtering, sorting and relation expansion. Filter supports operators like =, !=, >, <, ~ (contains), and functions. Example filter: 'status = "active" && created > "2024-01-01"'. Use expand to inline related records (e.g. 'author,comments_via_post'). Set skipTotal to true for faster queries when you don't need the total count.
Inputs: collection (required), page, sort, expand, +4 more.
List superuser (admin) accounts from the built-in _superusers collection.
Inputs: page, sort, filter, perPage.
Send a one-time password email to a user and return the otpId needed to complete auth_with_otp (requires SMTP and OTP auth enabled on the collection).
Inputs: email (required), collection.
Send a password reset email to a user (requires SMTP configured).
Inputs: email (required), collection.
Send a verification email to a user of an auth collection (requires SMTP configured).
Inputs: email (required), collection.
Restore the instance from an existing backup file. THIS OVERWRITES ALL CURRENT DATA and restarts the application. Use with extreme caution. Superuser only.
Inputs: key (required).
Manually trigger a registered cron job by its id (as returned by list_crons). Superuser only.
Inputs: jobId (required).
Escape hatch: send an arbitrary authenticated HTTP request to any PocketBase API endpoint. Use this for endpoints not covered by a dedicated tool, custom routes added via hooks, or new API features. The Authorization header (superuser token) is attached automatically. path is relative to the server root and must start with '/api/...' (e.g. '/api/collections'). Returns the parsed JSON response.
Inputs: path (required), body, query, method, +1 more.
Send a test email to verify SMTP configuration. Choose a template: 'verification', 'password-reset' or 'email-change'. Superuser only. Requires SMTP to be configured.
Inputs: toEmail (required), template, collection.
Perform an S3 filesystem connection test for either 'storage' or 'backups'. Superuser only.
Inputs: filesystem.
Delete ALL records of a collection while keeping the collection/schema itself. Cannot be undone.
Inputs: idOrName (required).
Remove a linked OAuth2 provider from a user record (superuser only).
Inputs: provider (required), recordId (required), collection.
Update an existing collection by id or name. Provide the fields to change in data. To modify the schema, pass the full fields array (existing field ids must be preserved to keep data). You can also update rules, indexes and options.
Inputs: data (required), idOrName (required).
Update an existing record by id. Only the fields present in data are changed. To append to a multi-relation/file/select field use the '+' modifier as a key (e.g. { "tags+": "id" }); to remove use 'field-'. Upload files via files.
Inputs: id (required), collection (required), data, files, +2 more.
Bulk update instance settings. Provide only the sections you want to change in data. Examples: { "meta": { "appName": "My App", "appURL": "https://example.com" } }, { "smtp": { "enabled": true, "host": "smtp.example.com", "port": 587, "username": "...", "password": "..." } }, { "batch": { "enabled": true, "maxRequests": 50 } }. Superuser only.
Inputs: data (required).
Update a superuser account (e.g. change email or reset the password). To change the password, include both 'password' and 'passwordConfirm' in data.
Inputs: id (required), data (required).
Upload an existing local backup zip file into the instance's backups. Superuser only.
Inputs: path (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 55 tools
Most tools pair a clear action with a distinct resource, and even similar prefixes like request_/confirm_ target clearly different auth workflows. The main ambiguity is between list_records, get_full_record_list, and get_first_record, which all retrieve records and differ only in pagination or convenience.
The API is overwhelmingly consistent verb_noun snake_case, following list_, get_, create_, update_, delete_, request_, and confirm_ patterns. A few outliers like health_check, batch, auth_info, and impersonate break the pattern, but they are minor deviations in an otherwise coherent naming scheme.
At 55 tools, this is an extremely large MCP surface for an agent to reason over, crossing the threshold where tool selection becomes a burden. Even though PocketBase is broad, this would be better split into focused servers for records, admin/settings, backups/logs, and auth.
The tool set covers collections, records, auth, superusers, settings, logs, backups, cron, and file handling with full CRUD and lifecycle coverage. The send_raw_request escape hatch also eliminates dead ends for any PocketBase endpoint not otherwise exposed.
MCP server for interacting with the Supabase platform
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Butterbase MCP server — manage your backend: schemas, auth, functions, storage, RAG, deploys.
