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
[email protected]
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": "[email protected]",
        "POCKETBASE_ADMIN_PASSWORD": "your_password"
      }
    }
  }
}

Available Tools

Authentication Tools

authenticate_admin

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

{
  "email": "[email protected]",
  "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": "[email protected]",
  "password": "userpassword",
  "collection": "users",
  "baseUrl": "http://127.0.0.1:8090",
  "saveSession": true
}

| Parameter | Type | Description | |-----------|------|-------------| | email | string | User email address | | password | string | User password | | collection | string | Auth collection name (default: "users") | | baseUrl | string | PocketBase URL (optional) | | saveSession | boolean | Save session for subsequent requests (default: true) |

logout

Clear the current authentication session.

check_auth_status

Check if there's an active authentication session.

Collection Management Tools (Admin Only)

list_collections

Get all collections with their metadata.

get_collection

Get detailed information about a specific collection.

create_collection

Create a new collection with schema definition.

{
  "name": "posts",
  "type": "base",
  "schema": [
    { "name": "title", "type": "text", "required": true },
    { "name": "content", "type": "editor", "required": false },
    { "name": "published", "type": "bool", "required": false }
  ],
  "listRule": "",
  "viewRule": "",
  "createRule": "@request.auth.id != ''",
  "updateRule": "@request.auth.id != ''",
  "deleteRule": "@request.auth.id != ''"
}

update_collection

Update an existing collection's schema or rules.

delete_collection

Delete a collection and all its records.

Record CRUD Tools

All record tools support custom headers via the headers parameter.

list_records

Query records with filtering, sorting, and pagination.

{
  "collection": "posts",
  "filter": "published = true && created > '2024-01-01'",
  "sort": "-created,title",
  "page": 1,
  "perPage": 20,
  "expand": "author",
  "headers": { "X-Custom-Header": "value" }
}

get_record

Get a single record by ID.

{
  "collection": "posts",
  "id": "record_id_here",
  "expand": "author,comments"
}

create_record

Create a new record in a collection.

{
  "collection": "posts",
  "data": {
    "title": "My First Post",
    "content": "Hello, world!",
    "published": true
  }
}

update_record

Update an existing record.

delete_record

Delete a record from a collection.

User Management Tools

User management tools respect PocketBase collection rules. Admin token is optional and only needed for privileged operations.

list_users

List users from an auth collection with filtering.

{
  "collection": "users",
  "filter": "verified = true",
  "sort": "-created",
  "page": 1,
  "perPage": 20,
  "headers": { "X-Custom-Header": "value" }
}

get_user

Get a single user by ID.

create_user

Create a new user account.

{
  "collection": "users",
  "email": "[email protected]",
  "password": "securepassword123",
  "passwordConfirm": "securepassword123",
  "emailVisibility": false,
  "verified": true,
  "name": "John Doe"
}

update_user

Update an existing user.

delete_user

Delete a user account.

Custom HTTP Requests Tool

send_custom_request

Send raw HTTP requests to any PocketBase API endpoint. Supports all authentication types (admin, user, or public) and maintains session state across requests.

{
  "method": "GET",
  "endpoint": "/api/collections/posts/records",
  "queryParams": {
    "filter": "status='published'",
    "sort": "-created",
    "perPage": "10"
  },
  "headers": {
    "X-Custom-Header": "value"
  }
}

| Parameter | Type | Description | |-----------|------|-------------| | method | string | HTTP method: GET, POST, PUT, PATCH, DELETE | | endpoint | string | API endpoint (e.g., '/api/collections/posts/records') | | body | object | Request body for POST/PUT/PATCH requests | | queryParams | object | URL query parameters | | headers | object | Custom HTTP headers | | baseUrl | string | PocketBase URL (optional) | | adminToken | string | Admin token for privileged endpoints (optional) |

Examples:

Get published posts with custom filtering:

{
  "method": "GET",
  "endpoint": "/api/collections/posts/records",
  "queryParams": {
    "filter": "status='published' && created > '2024-01-01'",
    "sort": "-created",
    "expand": "author,category",
    "perPage": "20"
  }
}

Create a new record with custom data:

{
  "method": "POST",
  "endpoint": "/api/collections/posts/records",
  "body": {
    "title": "My Custom Post",
    "content": "This was created via custom request",
    "status": "draft",
    "author": "user123"
  }
}

Admin-only settings request:

{
  "method": "GET",
  "endpoint": "/api/settings",
  "adminToken": "your_admin_token_here"
}

Custom file upload:

{
  "method": "POST",
  "endpoint": "/api/collections/users/records/user123",
  "headers": {
    "Content-Type": "multipart/form-data"
  },
  "body": {
    "avatar": "file_data_here"
  }
}

The send_custom_request tool supports multiple authentication methods:

• Current Session: Uses existing authentication (admin or user)
• Environment Token: Falls back to POCKETBASE_ADMIN_TOKEN if set
• Explicit Token: Provide adminToken parameter for admin operations
• No Auth: Public endpoints don't require authentication

Custom Request Examples

Advanced Filtering with Aggregation

{
  "method": "GET",
  "endpoint": "/api/collections/orders/records",
  "queryParams": {
    "filter": "status='completed' && total > 100",
    "sort": "-total",
    "fields": "id,user,total,status,created",
    "expand": "user",
    "perPage": "50"
  }
}

Batch Operations with Custom Logic

{
  "method": "POST",
  "endpoint": "/api/collections/posts/records",
  "body": {
    "title": "Batch Created Post",
    "content": "Created via custom request",
    "tags": ["automated", "custom"],
    "published": true,
    "author": "{{current_user_id}}"
  }
}

Custom Validation Endpoint

{
  "method": "POST",
  "endpoint": "/api/collections/users/records/validate",
  "body": {
    "email": "[email protected]",
    "password": "secure123"
  }
}

Health Check with Custom Headers

{
  "method": "GET",
  "endpoint": "/api/health",
  "headers": {
    "X-Client-Version": "1.0.0",
    "X-Request-ID": "custom-request-123"
  }
}

Common Parameters

Most tools accept these optional parameters:

| Parameter | Type | Description | |-----------|------|-------------| | baseUrl | string | PocketBase server URL | | adminToken | string | Admin token for privileged access | | headers | object | Custom HTTP headers to send with the request |

Error Handling

All tools return consistent error responses:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": { "field": "specific error details" },
  "suggestion": "How to fix the error"
}

Error Codes

| Code | Description | |------|-------------| | AUTH_INVALID | Invalid credentials | | AUTH_REQUIRED | Authentication required | | FORBIDDEN | Insufficient permissions | | NOT_FOUND | Resource not found | | VALIDATION_ERROR | Invalid input data | | NETWORK_ERROR | Connection issues | | UNKNOWN_ERROR | Unexpected error |

PocketBase Filter Syntax

The filter parameter uses PocketBase's filter syntax:

# Equality
status = 'active'

# Comparison
created > '2024-01-01'
price >= 100

# Logical operators
status = 'active' && published = true
category = 'tech' || category = 'science'

# Contains/Like
title ~ 'hello'      # contains
title !~ 'spam'      # not contains

# Null checks
avatar = null
avatar != null

# Relations
author.name = 'John'

Development

# Run in development mode with auto-reload
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build for production
npm run build

Author

Abdramane Sakone

License

MIT License - see LICENSE for details.