What is Pocketbase Mcp Server

PocketBase MCP Server is a comprehensive Model Context Protocol (MCP) server designed to manage PocketBase instances. It allows LLMs to interact with PocketBase databases through a standardized protocol, providing tools for various database operations.

Use cases

Use cases include managing user data in applications, automating database operations, integrating with LLM applications for enhanced data processing, and providing a backend for web or mobile applications.

How to use

To use PocketBase MCP Server, install it via npm with ‘npm install’ and build it using ‘npm run build’. Configure the server to connect to different PocketBase instances using a local config file or environment variables.

Key features

Key features include collection management (CRUD operations, schema management), record operations (advanced querying, pagination), authentication and user management (multiple auth methods, complete auth flow), file management (URL generation, private token support), system operations (health monitoring, log viewing), backup and restore capabilities, and hook management.

Where to use

PocketBase MCP Server can be used in various fields such as application development, data management, and backend services where interaction with databases is required, especially in environments utilizing LLMs.

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

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