PocketBase MCP Server

A comprehensive Model Context Protocol (MCP) server that provides tools for managing PocketBase instances. This server enables LLMs to interact with PocketBase databases through a standardized protocol.

Overview

This MCP server exposes PocketBase functionality as tools that can be used by any MCP-compatible client (like Claude Desktop, Cursor, or other LLM applications). It provides comprehensive access to PocketBase features with 60+ tools covering all major operations.

Features

Collection Management

• List, get, create, update, and delete collections
• Import/export collections in bulk
• Full schema management support

Record Operations

• CRUD operations with filtering, sorting, and pagination
• getFullList for retrieving all records without pagination
• getFirstListItem for finding the first matching record
• Advanced query support with field selection and relation expansion
• Batch operations for efficient bulk processing

Authentication & User Management

• Multiple auth methods: password, OAuth2, OTP
• Complete auth flow support: registration, login, password reset, email verification
• Email change functionality
• Auth token refresh
• List available auth methods for collections

File Management

• Generate file URLs with thumbnail support
• Private file token generation
• Download forcing support

System Operations

• Health monitoring
• Settings management
• Log viewing with statistics
• Cron job management and execution

Backup & Restore

• Create, list, download, and delete backups
• Full backup restoration support

Hook Management

• List, read, create, and delete JavaScript hooks
• Pre-built templates for common patterns

Installation

npm install
npm run build

Configuration

The server can be configured to connect to different PocketBase instances using (in order of precedence):

1. Local config file (.pocketbase-mcp.json in your project directory):

   {
     "url": "http://localhost:8091"
   }
   

2. Environment variable:

   • POCKETBASE_URL: URL of your PocketBase instance

3. Default: http://127.0.0.1:8090

Multi-Project Setup

Option 1: Project-Specific Configuration (Recommended)

Each project can have its own MCP configuration:

# In project directory
claude mcp add-json pocketbase '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "http://localhost:8091"}}' --scope project

Option 2: Config File

Create a .pocketbase-mcp.json in your project root:

{
  "url": "https://api.myproject.com"
}

Option 3: Multiple Named Servers

Add different PocketBase instances globally:

claude mcp add-json pb-local '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "http://localhost:8090"}}'
claude mcp add-json pb-prod '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "https://api.myapp.com"}}'

Usage with Claude Desktop

Add this configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "pocketbase": {
      "command": "node",
      "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"],
      "env": {
        "POCKETBASE_URL": "http://localhost:8090"
      }
    }
  }
}

Available Tools

Collection Management Tools

• list_collections - List all collections with pagination and filtering
• get_collection - Get a specific collection by ID or name
• create_collection - Create a new collection with schema
• update_collection - Update collection settings and schema
• delete_collection - Delete a collection
• import_collections - Import multiple collections at once

Record Management Tools

• list_records - List records with pagination, filtering, sorting, and field selection
• get_full_list - Get all records without pagination (batch processing)
• get_first_list_item - Get the first record matching a filter
• get_record - Get a specific record by ID
• create_record - Create a new record
• update_record - Update an existing record
• delete_record - Delete a record

Batch Operations

• batch_create - Create multiple records in a single transaction
• batch_update - Update multiple records in a single transaction
• batch_delete - Delete multiple records in a single transaction
• batch_upsert - Upsert multiple records in a single transaction

Authentication Tools

• list_auth_methods - Get available authentication methods
• auth_with_password - Authenticate with email/username and password
• auth_with_oauth2 - Get OAuth2 authentication URL
• auth_refresh - Refresh authentication token
• request_otp - Request OTP for email authentication
• auth_with_otp - Authenticate with OTP
• request_password_reset - Send password reset email
• confirm_password_reset - Confirm password reset with token
• request_verification - Send verification email
• confirm_verification - Confirm email verification
• request_email_change - Request email change
• confirm_email_change - Confirm email change

File Management Tools

• get_file_url - Generate URL for accessing files with options
• get_file_token - Get private file access token

Log Management Tools

• list_logs - List system logs with filtering
• get_log - Get a specific log entry
• get_log_stats - Get log statistics

Cron Job Tools

• list_cron_jobs - List all cron jobs
• run_cron_job - Manually run a cron job

System Tools

• get_health - Check PocketBase health status
• get_settings - Get PocketBase settings (requires admin auth)
• update_settings - Update PocketBase settings (requires admin auth)

Backup Tools

• create_backup - Create a backup
• list_backups - List available backups
• download_backup - Get download URL for a backup
• delete_backup - Delete a backup
• restore_backup - Restore from a backup

Hook Management Tools

• list_hooks - List JavaScript hook files in the pb_hooks directory
• read_hook - Read the contents of a hook file
• create_hook - Create or update a JavaScript hook file
• delete_hook - Delete a hook file
• create_hook_template - Generate hook templates for common patterns:
  • record-validation: Field validation for records
  • record-auth: Custom authentication logic
  • custom-route: API endpoint creation
  • file-upload: File upload validation
  • scheduled-task: Cron job setup

Tool Examples

List Records with Filtering

{
  "tool": "list_records",
  "arguments": {
    "collection": "posts",
    "filter": "published = true && created >= '2024-01-01'",
    "sort": "-created",
    "expand": "author",
    "fields": "id,title,content,author",
    "skipTotal": true
  }
}

Get All Records Without Pagination

{
  "tool": "get_full_list",
  "arguments": {
    "collection": "categories",
    "sort": "name",
    "batch": 1000
  }
}

Batch Create Records

{
  "tool": "batch_create",
  "arguments": {
    "requests": [
      {
        "collection": "posts",
        "data": {
          "title": "First Post",
          "content": "Content 1"
        }
      },
      {
        "collection": "posts",
        "data": {
          "title": "Second Post",
          "content": "Content 2"
        }
      }
    ]
  }
}

OAuth2 Authentication

{
  "tool": "auth_with_oauth2",
  "arguments": {
    "collection": "users",
    "provider": "google",
    "redirectURL": "https://myapp.com/auth/callback"
  }
}

OTP Authentication Flow

// Step 1: Request OTP
{
  "tool": "request_otp",
  "arguments": {
    "collection": "users",
    "email": "user@example.com"
  }
}

// Step 2: Authenticate with OTP
{
  "tool": "auth_with_otp",
  "arguments": {
    "collection": "users",
    "otpId": "otp_id_from_step_1",
    "password": "123456"
  }
}

Get File URL with Thumbnail

{
  "tool": "get_file_url",
  "arguments": {
    "collection": "products",
    "recordId": "abc123",
    "filename": "photo.jpg",
    "thumb": "300x200"
  }
}

Create a Hook Template

{
  "tool": "create_hook_template",
  "arguments": {
    "type": "record-validation",
    "collection": "posts"
  }
}

Query Syntax

The MCP server supports PocketBase's full query syntax:

Filter Examples

• title = "example" - Exact match
• created >= "2024-01-01" - Date comparison
• title ~ "search" - Contains text
• tags ?~ "important" - Any array element contains
• user.name = "John" - Nested field access

Sort Examples

• created - Ascending by created
• -created - Descending by created
• name,-created - Multiple sort fields

Expand Examples

• author - Expand single relation
• author,tags - Expand multiple relations
• author.profile - Nested expansion

Field Selection

• id,title,content - Select specific fields
• *,expand.author.name - Include expanded fields

Performance Optimization

• Use skipTotal: true when you don't need the total count
• Use fields parameter to limit data transfer
• Use get_full_list with appropriate batch sizes for large datasets
• Use batch operations for bulk record modifications

Development

Running in Development Mode

npm run dev

Building

npm run build

Architecture

The MCP server follows the Model Context Protocol specification:

1. MCP Server: Handles tool registration and execution
2. PocketBase Client: Uses the official PocketBase JavaScript SDK
3. Tool Handlers: Implement specific PocketBase operations with proper error handling

Error Handling

All tools include comprehensive error handling and return descriptive error messages. Common errors include:

• Invalid authentication
• Missing required fields
• Network connectivity issues
• Permission denied errors

Security Considerations

• Admin operations require appropriate authentication
• Use environment variables for sensitive configuration
• The server inherits PocketBase's security model and access rules
• OAuth2 state parameters are handled securely

Version Compatibility

• Requires PocketBase v0.20.0 or higher
• Uses PocketBase JavaScript SDK v0.21.0+
• Implements MCP protocol version 1.0

Contributing

Contributions are welcome! Please ensure that any new tools:

• Follow the existing naming patterns
• Include proper TypeScript types
• Have comprehensive error handling
• Are documented in this README

License

ISC