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:

Variable	Required	Default	Description
POCKETBASE_URL	Yes	—	Base URL of your PocketBase instance (e.g. http://127.0.0.1:8090)
POCKETBASE_SUPERUSER_EMAIL	No	—	Superuser email for admin operations
POCKETBASE_SUPERUSER_PASSWORD	No	—	Superuser password
POCKETBASE_API_KEY	No	—	Long-lived API key (alternative to email/password)

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

<!-- ### Streamable HTTP transport (for remote/multi-client setups)

uv run server.py --transport streamable-http --port 8000
``` -->

### With MCP Inspector (for development and testing)

```bash
# 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

Tool	Description
list_records	List records in a collection with filtering, sorting, and pagination
get_record	Get a single record by ID
create_record	Create a new record
update_record	Update an existing record
delete_record	Delete a record by ID
batch_records	Perform multiple create/update/upsert/delete operations in one request

Collections

Tool	Description
list_collections	List all collections
get_collection	Get a collection schema by name or ID
create_collection	Create a new collection with fields and API rules
update_collection	Update a collection's schema or rules
delete_collection	Delete a collection

Authentication

Tool	Description
auth_with_password	Authenticate a user or superuser with email and password
auth_with_api_key	Authenticate using a long-lived API key
get_auth_store	Return the current authentication state

Files

Tool	Description
get_file_url	Generate the URL for a file attached to a record
create_file_token	Create a short-lived token for accessing protected files

Settings

Tool	Description
get_settings	Retrieve all application settings
update_settings	Update application 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.