pb_mcp_server by ssakone - MCP Server

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 for details.