pocketbase-mcp-server

MCP (Model Context Protocol) server for PocketBase — exposes the full PocketBase JS SDK as MCP tools for AI-powered database management.

Features

• 51 MCP tools covering the entire PocketBase JS SDK
• Admin operations: collection management, settings, logs, backups, crons, SQL
• Record CRUD: create, read, update, delete with filtering, sorting, and pagination
• Authentication: password auth, OAuth2, OTP, impersonation, token refresh, verification, email change flows
• Batch operations: transactional multi-record operations across collections
• MCP Resources: collection schemas, health, and settings exposed as ambient context
• Full TypeScript with strict type checking

Installation

npm install -g pocketbase-mcp-server

Configuration

Add to your MCP client configuration (e.g., mcp.json, Claude Desktop config, etc.):

{
  "mcpServers": {
    "pocketbase": {
      "command": "npx",
      "args": ["-y", "pocketbase-mcp-server"],
      "env": {
        "POCKETBASE_URL": "http://localhost:8090",
        "POCKETBASE_ADMIN_EMAIL": "[email protected]",
        "POCKETBASE_ADMIN_PASSWORD": "your-password"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | POCKETBASE_URL | Yes | Your PocketBase instance URL | | POCKETBASE_ADMIN_EMAIL | Yes | Superuser/admin email | | POCKETBASE_ADMIN_PASSWORD | Yes | Superuser/admin password |

Available Tools

Collections (Admin)

| Tool | Description | |------|-------------| | pb_collections_list | List collections with pagination and filtering | | pb_collections_get | Get a single collection by name or ID | | pb_collections_create | Create a new collection (base, auth, or view) | | pb_collections_update | Update an existing collection | | pb_collections_delete | Delete a collection | | pb_collections_import | Bulk import collection definitions | | pb_collections_truncate | Delete all records from a collection | | pb_collections_get_scaffolds | Get scaffold templates for collection types | | pb_collections_dry_run_view_query | Test a SQL query as a view collection | | pb_collections_oauth2_providers | List all configured OAuth2 providers |

Records (CRUD)

| Tool | Description | |------|-------------| | pb_records_get_list | List records with pagination, filtering, sorting | | pb_records_get_full_list | Fetch all records (auto-paginates) | | pb_records_get_first | Get first record matching a filter | | pb_records_get_one | Get a single record by ID | | pb_records_create | Create a new record | | pb_records_update | Update a record (partial) | | pb_records_delete | Delete a record | | pb_filter_build | Build a filter expression with parameter substitution |

Settings (Admin)

| Tool | Description | |------|-------------| | pb_settings_get_all | Get all application settings | | pb_settings_update | Update application settings | | pb_settings_test_s3 | Test S3 filesystem connection | | pb_settings_test_email | Send a test email |

Logs (Admin)

| Tool | Description | |------|-------------| | pb_logs_get_list | List application logs | | pb_logs_get_one | Get a single log entry | | pb_logs_get_stats | Get hourly log statistics |

Health

| Tool | Description | |------|-------------| | pb_health_check | Check server health status |

Authentication

| Tool | Description | |------|-------------| | pb_auth_with_password | Authenticate a user with password | | pb_auth_refresh | Refresh admin auth token | | pb_auth_list_methods | List available auth methods | | pb_auth_request_password_reset | Send password reset email | | pb_auth_confirm_password_reset | Confirm password reset | | pb_auth_request_verification | Send email verification | | pb_auth_confirm_verification | Confirm email verification | | pb_auth_request_email_change | Request email change | | pb_auth_confirm_email_change | Confirm email change | | pb_auth_with_oauth2_code | Authenticate with OAuth2 authorization code | | pb_auth_request_otp | Send a one-time password to a user's email | | pb_auth_with_otp | Authenticate with a one-time password | | pb_auth_impersonate | Impersonate a record (superuser only) |

Files

| Tool | Description | |------|-------------| | pb_files_get_url | Build file URL for a record's file field | | pb_files_get_token | Get private file access token |

Backups (Admin)

| Tool | Description | |------|-------------| | pb_backups_list | List all backup files | | pb_backups_create | Create a new backup | | pb_backups_delete | Delete a backup | | pb_backups_restore | Restore from a backup | | pb_backups_upload | Upload a backup file from a local path | | pb_backups_download_url | Generate a download URL for a backup |

Crons (Admin)

| Tool | Description | |------|-------------| | pb_crons_list | List registered cron jobs | | pb_crons_run | Manually trigger a cron job |

SQL (Admin)

| Tool | Description | |------|-------------| | pb_sql_run | Execute raw SQL (superuser only) |

Batch Operations

| Tool | Description | |------|-------------| | pb_batch_create | Execute multiple operations transactionally |

MCP Resources

The server exposes these resources for ambient context:

• pocketbase://collections — All collection schemas with fields and rules
• pocketbase://health — Current server health status
• pocketbase://settings — Current application settings

Development

# Clone and install
git clone <repo-url>
cd pocketbase-mcp
npm install

# Build
npm run build

# Type check
npm run typecheck

# Test
npm test

# Run locally
POCKETBASE_URL=http://localhost:8090 \
[email protected] \
POCKETBASE_ADMIN_PASSWORD=secret \
npm start

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Requirements

• Node.js >= 20
• PocketBase instance (v0.23.0+ recommended for superuser collection support)

License

MIT