PocketBase Model Context Protocol Server

You can run the server as a containerized service.

1. Build the image: docker build -t pocketbase-mcp .

2. Run the container: Use docker run with environment variables. If your PocketBase instance is running on your host machine, use http://host.docker.internal:8090 as the POCKETBASE_URL to allow the container to reach the host.

3. Configure AI Assistant: Update your MCP settings to use docker run -i --rm as the command. The -i flag is required for stdio communication.

# Build the image
docker build -t pocketbase-mcp .

# Run the container
docker run -d \
  --name pocketbase-mcp \
  -e POCKETBASE_URL=http://host.docker.internal:8090 \
  -e POCKETBASE_ADMIN_EMAIL=your_admin@example.com \
  -e POCKETBASE_ADMIN_PASSWORD=your_admin_password \
  pocketbase-mcp

For easier management, you can use a docker-compose.yml file.

docker-compose.yml example:

version: "3.8"

services:
  pocketbase-mcp:
    build: .
    environment:
      - POCKETBASE_URL=http://host.docker.internal:8090
      - POCKETBASE_ADMIN_EMAIL=your_admin@example.com
      - POCKETBASE_ADMIN_PASSWORD=your_admin_password
    stdin_open: true
    tty: true

MCP Settings for Docker Compose: When using Compose, configure your MCP settings to use docker-compose as the command:

{
  "mcpServers": {
    "pocketbase-docker": {
      "command": "docker-compose",
      "args": ["run", "--rm", "pocketbase-mcp"],
      "disabled": false
    }
  }
}

The PocketBase MCP server requires specific environment variables to connect to your PocketBase instance and perform administrative tasks.

Required Variables:

• POCKETBASE_URL: The full URL of your PocketBase instance (e.g., https://your-instance.pockethost.io).

Administrative Variables (used for collection management and backups):

• POCKETBASE_ADMIN_EMAIL: The email address of the superuser/admin.
• POCKETBASE_ADMIN_PASSWORD: The password for the superuser/admin.

# Example environment setup
export POCKETBASE_URL="https://pb.example.com"
export POCKETBASE_ADMIN_EMAIL="admin@example.com"
export POCKETBASE_ADMIN_PASSWORD="secure_password"

Examples of how to call the MCP tools using a programmatic interface (e.g., via an MCP client implementation).

// Create a new collection
await mcp.use_tool("pocketbase", "create_collection", {
  name: "posts",
  schema: [
    {
      name: "title",
      type: "text",
      required: true,
    },
    {
      name: "content",
      type: "text",
      required: true,
    },
  ],
});

// Authenticate with password
await mcp.use_tool("pocketbase", "authenticate_user", {
  email: "user@example.com",
  password: "securepassword",
  collection: "users",
});

The server provides the following tools for interacting with PocketBase:

Collection Management

• create_collection: Create a new collection with a custom schema.
• get_collection: Retrieve schema details and metadata for a collection.

Record Operations

• create_record: Create a new record in a specific collection.
• list_records: List records with support for filters and pagination.
• update_record: Update an existing record.
• delete_record: Delete a record.

User Management

• authenticate_user: Authenticate a user and retrieve an auth token.
• create_user: Create a new user account.

Database Operations

• backup_database: Create a backup of the PocketBase database with specified format options.

The server uses the following environment variables for configuration:

Use these tools to perform CRUD operations on data within existing collections.

create_record

• Arguments:
  • collection (string, required): Collection name.
  • data (object, required): The record data.

list_records

• Arguments:
  • collection (string, required): Collection name.
  • filter (string): Filter query.
  • sort (string): Sort field and direction.
  • page (number): Page number.
  • perPage (number): Items per page.

update_record

• Arguments:
  • collection (string, required): Collection name.
  • id (string, required): Record ID.
  • data (object, required): Updated record data.

delete_record

• Arguments:
  • collection (string, required): Collection name.
  • id (string, required): Record ID.

The server exports utility functions to handle and flatten complex PocketBase error objects into human-readable strings.

• pocketbaseErrorMessage(errors: unknown): Returns a joined string of all error messages found in the error object. If no errors are found, returns "No errors found".
• flattenErrors(errors: unknown): Recursively traverses error objects (including nested data properties) to extract all error message strings into a flat array.

Tools for system-level operations.

backup_database

Creates a database backup.

• Arguments:
  • name (string): The name of the backup.

import_data

Imports an array of records into a collection.

• Arguments:
  • collection (string, required): Target collection.
  • data (array, required): Array of record objects.
  • mode (string): create, update, or upsert (default: create).

create_user

Creates a new user account.

• Arguments:
  • email (string, required): User email.
  • password (string, required): User password.
  • passwordConfirm (string, required): Confirmation.
  • name (string): User name.
  • collection (string): Collection name (default: users).