PocketBase MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to PocketBase functionality. This server enables AI assistants and other MCP clients to interact with PocketBase databases for authentication, data management, and administrative operations.

Features

• Authentication: Admin and user authentication with session management
• Session Persistence: Save sessions across tool calls with saveSession parameter
• Auto-Authentication: Automatically authenticate at startup using environment variables
• Collection Management: Create, update, delete, and query collections (admin only)
• Record CRUD: Full create, read, update, delete operations on records
• User Management: Manage user accounts in auth collections
• Custom Headers: Send custom HTTP headers with any request
• Custom HTTP Requests: Send raw HTTP requests to any PocketBase API endpoint
• Query Support: Filtering, sorting, and pagination for records and users
• Error Handling: Consistent, informative error responses
• Multi-Instance: Support for connecting to multiple PocketBase instances
• TOON Output Format: Optional TOON format for 30-60% token reduction with LLMs

Installation

# Clone the repository
git clone https://github.com/ssakone/pocketbase-mcp-server.git
cd pocketbase-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Environment Variables

Create a .env file or set environment variables:

# PocketBase server URL (default: http://127.0.0.1:8090)
POCKETBASE_URL=http://127.0.0.1:8090

# Admin token for authenticated operations (optional - can be provided per-request)
POCKETBASE_ADMIN_TOKEN=your_admin_token_here

# Auto-authentication at startup (optional)
# If both are provided, the server will authenticate and obtain a token automatically
POCKETBASE_ADMIN_EMAIL=admin@example.com
POCKETBASE_ADMIN_PASSWORD=your_admin_password

# Output format: json (default) or toon
# TOON format reduces token usage by 30-60% when communicating with LLMs
MCP_OUTPUT_FORMAT=json

Configuration File

Alternatively, create a pocketbase.config.json:

{
  "pocketbaseUrl": "http://127.0.0.1:8090",
  "pocketbaseAdminToken": "your_admin_token_here"
}

Running the Server

stdio Mode (for MCP clients like Cursor, Kiro)

npm start

HTTP/SSE Mode (for web clients and remote access)

# Default port 3001
npm run start:http

# Custom port
PORT=8080 npm run start:http

The HTTP server exposes an SSE endpoint at http://localhost:3001/sse.

MCP Client Configuration

Cursor/Kiro Configuration

Add to your MCP configuration:

{
  "mcpServers": {
    "pocketbase": {
      "command": "npm",
      "args": ["start"],
      "cwd": "/path/to/pocketbase-mcp-server",
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_ADMIN_EMAIL": "admin@example.com",
        "POCKETBASE_ADMIN_PASSWORD": "your_password"
      }
    }
  }
}

Available Tools

Authentication Tools

authenticate_admin

Authenticate as a PocketBase admin with full access to all operations.

{
  "email": "admin@example.com",
  "password": "adminpassword",
  "baseUrl": "http://127.0.0.1:8090",
  "saveSession": true
}

| Parameter | Type | Description | |-----------|------|-------------| | email | string | Admin email address | | password | string | Admin password | | baseUrl | string | PocketBase URL (optional) | | saveSession | boolean | Save session for subsequent requests (default: true) |

authenticate_user

Authenticate as a regular user with permissions based on collection rules.

{
  "email": "user@example.com",
  "password": "userpassword",
  "collection": "users",
  "baseUrl": "h

... [View full README on GitHub](https://github.com/ssakone/pb_mcp_server#readme)