PocketBase MCP Server

A Model Context Protocol (MCP) server for PocketBase, built with FastMCP. This server enables AI assistants like Claude to interact with PocketBase databases, manage collections, and perform CRUD operations on records.

Compatible with PocketBase API v0.30.4+

Features

Collection Management

• List all collections with pagination and filtering
• Get collection details
• Create new collections with custom schemas
• Update collection schemas and rules
• Delete collections
• NEW: Truncate collections (delete all records, keep schema)
• NEW: Get collection scaffolds (default field templates)
• NEW: Bulk import collections

Record Operations

• List records with pagination, filtering, and sorting
• NEW: Expand relations up to 6 levels deep
• NEW: Select specific fields for optimized responses
• NEW: Skip total count for faster queries
• Get individual records with expansion and field selection
• Create new records
• Update existing records
• Delete records

Advanced Features

• NEW: Batch operations (transactional create/update/delete)
• NEW: Health check endpoint
• Admin authentication support
• Collection-level API rules (list, view, create, update, delete)
• Filter records based on PocketBase query syntax

Installation

Option 1: Docker (Recommended)

The easiest way to get started with both PocketBase and the MCP server:

# Clone the repository
git clone <your-repo-url>
cd pb_mcp

# Create .env file with your credentials
echo "POCKETBASE_ADMIN_EMAIL=admin@example.com" > .env
echo "POCKETBASE_ADMIN_PASSWORD=your_secure_password" >> .env

# Start with Docker Compose
docker-compose up -d

See DOCKER.md for detailed Docker deployment instructions.

Option 2: Python Installation

1. Clone this repository:

git clone <your-repo-url>
cd pb_mcp

2. Install dependencies:

pip install -r requirements.txt

Or install in development mode:

pip install -e .

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env with your PocketBase configuration:

POCKETBASE_URL=http://127.0.0.1:8090
POCKETBASE_ADMIN_EMAIL=admin@example.com
POCKETBASE_ADMIN_PASSWORD=your_password_here

Important: The POCKETBASE_URL must include the protocol (http:// or https://).

• ✅ Correct: http://127.0.0.1:8090
• ✅ Correct: https://api.example.com
• ❌ Wrong: 127.0.0.1:8090 (missing protocol)
• ❌ Wrong: localhost:8090 (missing protocol)

Usage

Running the Server

STDIO Mode (Default)

For use with Claude Desktop and other STDIO-based MCP clients:

python -m pocketbase_mcp.server

Or if installed:

pocketbase-mcp

HTTP Mode

For web deployments and network access:

# Set environment variables
export MCP_TRANSPORT=http
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
export MCP_PATH=/mcp

# Run the server
python -m pocketbase_mcp.server

The server will be accessible at http://localhost:8000/mcp

Configuring with Claude Desktop

Python Installation

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pocketbase": {
      "command": "python",
      "args": ["-m", "pocketbase_mcp.server"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_ADMIN_EMAIL": "admin@example.com",
        "POCKETBASE_ADMIN_PASSWORD": "your_password_here"
      }
    }
  }
}

Docker Installation (STDIO Mode)

If using Docker Compose with STDIO:

{
  "mcpServers": {
    "pocketbase": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "pocketbase-mcp",
        "python",
        "-m",
        "pocketbase_mcp.server"
      ]
    }
  }
}

HTTP Mode Configuration

If running with HTTP transport, configure Claude Desktop to use the HTTP endpoint:

{
  "mcpServers": {
    "pocketbase": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Note: HTTP transport is recommended for web deployments and when you need network access to the MCP server.

Available Tools

Collection Management

list_collections()

List all collections in PocketBase.

get_collection(collection_id: str)

Get details of a specific collection including its schema and rules.

create_collection(name, collection_type, schema, list_rule, view_rule, create_rule, update_rule, delete_rule)

Create a new collection with custom schema and access rules.

Example schema for a blog posts collection:

{
    "name": "posts",
    "collection_type": "base",
    "schema": [
        {
            "name": "title",
            "type": "text",
            "required": True,
            "options": {"min": 1, "max": 200}
        },
        {
            "name": "content",
            "type": "editor",
            "required": True
        },
        {
            "name": "published",
            "type": "bool",
            "required": False
        }
    ],
    "list_rule": "",  # Public access
    "create_rule": "@request.auth.id != ''",  # Authenticated users only
    "update_rule": "@request.auth.id = author.id"  # Only author can update
}

update_collection(collection_id, name, schema, ...rules)

Update an existing collection's schema or rules.

delete_collection(collection_id: str)

Delete a collection and all its records.

truncate_collection(collection_id: str) NEW

Delete all records from a collection while preserving the schema. Useful for clearing test data or resetting a collection.

get_collection_scaffolds() NEW

Get default field templates for base, auth, and view collection types. Helpful for understanding available fields when creating collections.

Record Operations

list_records(collection, page, per_page, filter_query, sort, expand, fields, skip_total)

List records from a collection with pagination, filtering, and advanced options.

Parameters:

• expand - Expand related records up to 6 levels deep (e.g., "author,comments.user")
• fields - Select specific fields for optimized responses (e.g., "id,title,author.name")
• skip_total - Skip total count calculation for faster queries

Example filters:

• "status='active'" - Filter by field value
• "created >= '2024-01-01'" - Date comparison
• "title ~ 'blog'" - Text search (contains)
• "views > 100 && published = true" - Multiple conditions

Relation Expansion Example:

# Get posts with expanded author and comment user data
list_records(
    collection="posts",
    expand="author,comments.user",
    fields="id,title,author.name,comments.content"
)

get_record(collection, record_id, expand, fields)

Get a specific record by ID with optional relation expansion and field selection.

Parameters:

• expand - Comma-separated relations to expand
• fields - Comma-separated fields to return

create_record(collection: str, data: dict)

Create a new record in a collection.

Example:

{
    "collection": "posts",
    "data": {
        "title": "My First Post",
        "content": "<p>Hello World!</p>",
        "published": True
    }
}

update_record(collection: str, record_id: str, data: dict)

Update an existing record.

delete_record(collection: str, record_id: str)

Delete a record from a collection.

health_check() NEW

Check PocketBase server health and connectivity. Useful for monitoring and debugging.

Advanced Features (v0.30.4+)

Relation Expansion

PocketBase supports expanding related records up to 6 levels deep:

# Single level expansion
list_records(collection="posts", expand="author")

# Multi-level expansion
list_records(collection="posts", expand="author,comments.user")

# Deep nesting (up to 6 levels)
list_records(collection="posts", expand="author.team.organization")

Expanded data is returned in an expand property on each record.

Field Selection

Optimize responses by selecting only needed fields:

# Select specific fields
list_records(collection="posts", fields="id,title,created")

# Include fields from expanded relations
list_records(
    collection="posts",
    expand="author",
    fields="id,title,author.name,author.email"
)

Performance Optimization

For large datasets, skip total count calculation:

# Skip total for faster queries
list_records(collection="posts", skip_total=True)

This can drastically speed up queries when pagination info isn't needed.

Batch Operations

Execute multiple operations in a single transaction (requires dashboard configuration):

# Note: Use the client directly for batch operations
batch_request([
    {
        "method": "POST",
        "url": "/api/collections/posts/records",
        "body": {"title": "Post 1"}
    },
    {
        "method": "PATCH",
        "url": "/api/collections/posts/records/RECORD_ID",
        "body": {"published": true}
    }
])

Field Types

PocketBase supports various field types for collection schemas:

• text - Short text field
• editor - Rich text/HTML editor
• number - Numeric values
• bool - Boolean (true/false)
• email - Email address with validation
• url - URL with validation
• date - Date field
• select - Single or multiple select from predefined options
• relation - Relation to another collection
• file - File upload (single or multiple)
• json - JSON data

Access Rules

PocketBase uses a flexible rule system for access control. Rules are JavaScript-like expressions:

• null - No access (default for create/update/delete)
• "" (empty string) - Public access
• "@request.auth.id != ''" - Authenticated users only
• "@request.auth.id = author.id" - Only record owner
• "@request.auth.role = 'admin'" - Admin users only
• Complex expressions with &&, ||, and ()

Resources

The server exposes the following MCP resource:

• pocketbase://server/info - Server connection information

Prompts

• collection_schema_example - Example of creating a collection with schema

Development

Project Structure

pb_mcp/
├── pocketbase_mcp/
│   ├── __init__.py
│   ├── client.py      # PocketBase HTTP client
│   └── server.py      # FastMCP server with tools
├── .env.example
├── .gitignore
├── pyproject.toml
├── requirements.txt
└── README.md

Running Tests

# TODO: Add tests
pytest

Requirements

• Python 3.10+
• PocketBase server (0.20.0+)
• FastMCP
• httpx
• python-dotenv

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Troubleshooting

"UnsupportedProtocol: Request URL is missing an 'http://' or 'https://' protocol"

This error means the POCKETBASE_URL environment variable is missing the protocol.

Solution:

# ❌ Wrong
POCKETBASE_URL=127.0.0.1:8090
POCKETBASE_URL=localhost:8090
POCKETBASE_URL=pocketbase:8090

# ✅ Correct
POCKETBASE_URL=http://127.0.0.1:8090
POCKETBASE_URL=http://localhost:8090
POCKETBASE_URL=http://pocketbase:8090

For Docker deployments, check your .env file or docker-compose environment variables.

Authentication Errors

If you get authentication errors, verify:

1. PocketBase server is running at the configured URL
2. Admin email and password are correct
3. Admin account exists in PocketBase

Connection Issues

• Ensure PocketBase server is accessible at the configured URL
• Check firewall settings if running on different machines
• Verify the URL includes the correct protocol (http/https)
• Test with curl $POCKETBASE_URL/api/health

Collection Not Found

• Verify the collection name/ID is correct
• Check if you have admin authentication configured
• Some operations require admin access

"POCKETBASE_URL environment variable is not set"

Make sure you have either:

1. Created a .env file with POCKETBASE_URL=http://...
2. Set the environment variable: export POCKETBASE_URL=http://...
3. Configured it in docker-compose.yml

Resources

• PocketBase Documentation
• FastMCP Documentation
• Model Context Protocol

Example Usage with Claude

Once configured, you can ask Claude to:

• "List all collections in my PocketBase"
• "Create a new collection called 'tasks' with title and completed fields"
• "Show me all records from the posts collection"
• "Create a new post with title 'Hello World'"
• "Update the post with ID xyz123 to set published to true"
• "Delete all completed tasks"
• "Get the schema for the users collection"

The MCP server will handle all the API interactions with your PocketBase instance.