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": "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": "newuser@example.com",
  "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": "test@example.com",
    "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.