pocketbase-mcp

A Model Context Protocol (MCP) server for PocketBase — giving AI assistants like Claude full access to your PocketBase backend through a clean, Pythonic interface.

Overview

pocketbase-mcp bridges the gap between LLMs and your PocketBase instance. Once connected, AI assistants can list collections, perform CRUD operations on records, manage authentication, handle file uploads, and administer your database — all through natural language.

Built with FastMCP (the standard Python MCP framework) and httpx for async HTTP communication with the PocketBase REST API.

Features

• Records — list, get, create, update, delete, and batch-operate on records in any collection
• Collections — list, inspect, create, update, and delete collection schemas
• Authentication — authenticate as a superuser or regular user via email/password or API key
• Files — generate file tokens and retrieve file URLs with optional image transformations
• Settings — read and update application settings
• Filtering & Pagination — pass PocketBase filter expressions, sort, expand, and pagination params directly
• Realtime-aware — designed with SSE subscription patterns in mind for future extension

Requirements

• Python 3.11+
• A running PocketBase instance (local or remote)
• uv (recommended) or pip

Installation

Using pip

pip install pocketbase-mcp

Configuration

The server is configured via environment variables:

Set them in a .env file or export directly:

export POCKETBASE_URL=http://127.0.0.1:8090
export POCKETBASE_SUPERUSER_EMAIL=admin@example.com
export POCKETBASE_SUPERUSER_PASSWORD=your-password

Running the Server

stdio transport (default — for Claude Desktop, Claude Code, etc.)

pocketmcp

With MCP Inspector (for development and testing)

# Terminal 1
pocketmcp

# Terminal 2
npx @modelcontextprotocol/inspector
# Connect to: http://localhost:8000/mcp

Connecting to Claude

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "pocketbase": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/pocketbase-mcp/server.py"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_SUPERUSER_EMAIL": "admin@example.com",
        "POCKETBASE_SUPERUSER_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

Records

Collections

Authentication

Files

Settings

Project Structure

pocketbase-mcp/
├── server.py            # MCP server entry point (FastMCP)
├── tools/
│   ├── records.py       # Record CRUD tools
│   ├── collections.py   # Collection management tools
│   ├── auth.py          # Authentication tools
│   ├── files.py         # File tools
│   └── settings.py      # Settings tools
├── client.py            # Async PocketBase HTTP client (httpx)
├── config.py            # Environment variable loading
├── pyproject.toml
└── README.md

Example Usage

Once connected to Claude, you can interact with your PocketBase instance through natural language:

"List all records in the posts collection where status = 'published', sorted by created descending."

"Create a new record in users with name 'Alice' and role 'editor'."

"Show me the schema for the products collection."

"Delete the record with ID ae40239d2bc4477 from comments."

"Update the app name in PocketBase settings to 'My App'."

PocketBase Compatibility

This MCP server targets PocketBase v0.36.9+. The batch API requires it to be explicitly enabled in your PocketBase Dashboard under Settings → Application.

Security Notes

• Never commit credentials to version control. Use environment variables or a .env file (add .env to .gitignore).
• For production deployments, prefer API key authentication over email/password.
• Collection API rules in PocketBase govern what the authenticated user can actually access — pocketbase-mcp respects these rules.

Contributing

Contributions are welcome! Please open an issue before submitting a pull request for significant changes.

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes
4. Open a pull request

License

MIT License. See LICENSE for details.