# pocketbase-mcp

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [PocketBase](https://pocketbase.io) — 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](https://github.com/jlowin/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`](https://github.com/astral-sh/uv) (recommended) or `pip`

---

## Installation

### Using pip

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

```bash
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.)

```bash
pocketmcp
```

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

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

---

## Connecting to Claude

### Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pocketbase": {
      "command": "pocketmcp",
      "args": ["server"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_SUPERUSER_EMAIL": "admin@admin.com",
        "POCKETBASE_SUPERUSER_PASSWORD": "adminadmin"
      }
    }
  }
}
```

---

## 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 |
| `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](LICENSE) for details.