Skip to content

ssakone/pb_mcp_server

BranchesTags

Repository files navigation

PocketBase MCP Server

License: MIT TypeScript

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.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

59 stars

Watchers

1 watching

Forks

3 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages