PocketBase Server

A complete MCP (Model Context Protocol) server for managing PocketBase migrations via REST API. Generates and executes migrations to create, modify, and delete PocketBase collections.

📥 Installation from GitHub

Clone and install

# Clone the repository
git clone https://github.com/Step-by-Step-technology/pocketbase-mcp.git
cd pocketbase-mcp

# Install dependencies
npm install

# Compile TypeScript
npm run build

Quick setup

1. Create an MCP configuration file (~/.cline_desktop_config.json or equivalent):

{
  "mcpServers": {
    "pocketbase-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_TOKEN": "your_pocketbase_admin_token",
        "POCKETBASE_MIGRATIONS_DIR": "/absolute/path/to/pb_migrations"
      }
    }
  }
}

1. Restart your MCP client (Cline Desktop, Cursor, etc.)

2. Test the installation:

   # Start the server in development mode
   npm run dev
   

📦 Global installation (optional)

# Install globally (if you want to use it as CLI)
npm install -g .

# Then run
pocketbase-mcp

GitHub Repository: https://github.com/Step-by-Step-technology/pocketbase-mcp

✨ Features

✅ Available Tools (20 complete tools)

🏗️ Migration Tools (13 tools)

Tool	Description	Status
pocketbase-create-collection-migration	Generates a migration to create a new collection (supports relation fields)	✅ Works perfectly
pocketbase-update-collection	Generates a migration to modify collection rules	✅ New
pocketbase-delete-collection	Generates a migration to delete a collection	✅ New
pocketbase-update-collection-fields	Generates a migration to modify collection fields (supports relation fields)	✅ New
pocketbase-add-field-migration	Generates a migration to add a single field to a collection (supports relation fields)	✅ NEW
pocketbase-remove-field-migration	Generates a migration to remove a single field from a collection	✅ NEW
pocketbase-revert-migration	Generates a migration to revert a previous migration	✅ NEW
pocketbase-execute-any-migration	Executes any type of migration (creation, modification, deletion) - now supports relation fields	✅ Improved
pocketbase-execute-migration	Executes a creation migration (original tool preserved)	✅ Works perfectly
pocketbase-list-migrations	Lists all available migrations	✅ Existing
pocketbase-view-migration	Displays the content of a migration	✅ Existing
pocketbase-list-collections	Lists all PocketBase collections	✅ Existing
pocketbase-view-collection	Displays collection details	✅ Existing

📊 CRUD Tools (7 tools)

Tool	Description	Status
pocketbase-fetch-record	Fetches a specific record from a PocketBase collection	✅ NEW
pocketbase-list-records	Lists all records from a collection with pagination	✅ NEW
pocketbase-create-record	Creates a new record in a PocketBase collection	✅ NEW
pocketbase-update-record	Updates an existing record in a PocketBase collection	✅ NEW
pocketbase-get-collection-schema	Gets the schema (fields and types) of a collection	✅ NEW
pocketbase-upload-file	Uploads a file to a PocketBase collection	✅ NEW
pocketbase-download-file	Downloads a file from a PocketBase collection	✅ NEW

Total: 20 complete MCP tools - Migration + CRUD + File management

🚀 Installation (Alternative)

If you have already cloned the project locally or are working on an existing version:

Prerequisites

• Node.js 18+
• PocketBase running
• PocketBase admin token

Local installation

# Move to the pocketbase-mcp folder
cd pocketbase-mcp

# Install dependencies
npm install

# Compile TypeScript
npm run build

Note: For a complete installation from GitHub, refer to the 📥 Installation from GitHub section above.

Configuration

Environment variables are configured in the MCP configuration file (cline_mcp_settings.json):

{
  "mcpServers": {
    "pocketbase-mcp": {
      "command": "node",
      "args": ["/absolute/path/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_TOKEN": "your_pocketbase_admin_token",
        "POCKETBASE_MIGRATIONS_DIR": "/absolute/path/pb_migrations"
      }
    }
  }
}

Required variables:

• POCKETBASE_URL: URL of your PocketBase instance (e.g., http://127.0.0.1:8090)
• POCKETBASE_TOKEN: PocketBase admin token (obtained via admin interface)
• POCKETBASE_MIGRATIONS_DIR: Absolute path to the migrations directory

📦 Project Structure

pocketbase-mcp/
├── src/
│   ├── index.ts                    # MCP entry point
│   ├── pocketbase-migration.ts     # Migration generator
│   └── pocketbase-tools.ts         # All MCP tools
├── dist/                           # Compiled files
├── pb_migrations/                  # Generated migrations
├── package.json
├── tsconfig.json
├── README.md
└── GUIDE_COMPLET.md

🛠️ Usage

Start the MCP Server

# Development
npm run dev

# Production
npm run build
node dist/index.js

Cline Desktop Configuration

Add to ~/.cline_desktop_config.json:

{
  "mcpServers": {
    "pocketbase-mcp": {
      "command": "node",
      "args": ["/absolute/path/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_TOKEN": "your_token",
        "POCKETBASE_MIGRATIONS_DIR": "/absolute/path/pb_migrations"
      }
    }
  }
}

📝 Complete Examples

1. Create a Collection

{
  "collectionName": "products",
  "fields": [
    {
      "name": "title",
      "type": "text",
      "required": true,
      "max": 200
    },
    {
      "name": "price",
      "type": "number",
      "required": true,
      "min": 0
    },
    {
      "name": "category",
      "type": "select",
      "required": true,
      "values": ["electronics", "clothing", "books", "food", "home"]
    }
  ],
  "type": "base"
}

2. Modify Collection Rules

{
  "collectionName": "products",
  "listRule": "@request.auth.id != ''",
  "createRule": "@request.auth.id != ''",
  "updateRule": "@request.auth.id != ''",
  "deleteRule": "@request.auth.id != ''"
}

3. Modify Collection Fields

{
  "collectionName": "products",
  "fields": [
    {
      "name": "title",
      "type": "text",
      "required": true,
      "max": 200
    },
    {
      "name": "description",
      "type": "text",
      "required": false,
      "max": 1000
    },
    {
      "name": "price",
      "type": "number",
      "required": true,
      "min": 0
    },
    {
      "name": "stock",
      "type": "number",
      "required": false,
      "min": 0
    }
  ]
}

4. Delete a Collection

{
  "collectionName": "old_collection"
}

5. Execute a Migration

{
  "migrationFile": "1768985344_update_products.js"
}

6. Add a Field to a Collection

{
  "collectionName": "products",
  "field": {
    "name": "stock",
    "type": "number",
    "required": false,
    "min": 0
  }
}

7. Remove a Field from a Collection

{
  "collectionName": "products",
  "fieldName": "stock"
}

8. Revert a Migration

{
  "migrationFile": "1768987877_add_field_stock_to_products.js"
}

🔄 Complete Workflow

Step 1: Create a Migration

# Use the pocketbase-create-collection-migration tool
# → Generates a file in pb_migrations/

Step 2: Execute the Migration

# Use the pocketbase-execute-any-migration tool
# → Executes the migration via REST API

Step 3: Verify

# Use pocketbase-list-collections
# → Verifies that the collection was created

Step 4: Modify if necessary

# Use pocketbase-update-collection
# → Generates a modification migration
# → Execute with pocketbase-execute-any-migration

🎯 Advanced Use Cases

Creation Migration with Authentication Rules

{
  "collectionName": "user_posts",
  "fields": [
    {
      "name": "title",
      "type": "text",
      "required": true,
      "max": 200
    },
    {
      "name": "content",
      "type": "text",
      "required": false,
      "max": 5000
    }
  ],
  "listRule": "@request.auth.id != ''",
  "createRule": "@request.auth.id != ''",
  "updateRule": "@request.auth.id = author",
  "deleteRule": "@request.auth.id = author"
}

Authentication Collection Migration

{
  "collectionName": "users",
  "type": "auth",
  "fields": [
    {
      "name": "username",
      "type": "text",
      "required": true,
      "max": 100
    },
    {
      "name": "avatar",
      "type": "file",
      "required": false,
      "maxSelect": 1
    }
  ]
}

⚙️ Technical Configuration

Environment Variables

Variable	Description	Default Value
POCKETBASE_URL	URL of the PocketBase instance	http://127.0.0.1:8090
POCKETBASE_TOKEN	PocketBase admin token	(required)
POCKETBASE_ADMIN_TOKEN	Alternative to token	(optional)
POCKETBASE_MIGRATIONS_DIR	Migrations directory	./pb_migrations

NPM Scripts

{
  "scripts": {
    "build": "tsc",
    "dev": "tsx watch src/index.ts",
    "start": "node dist/index.js"
  }
}

🆕 New Features (January 2026)

✨ Addition of 3 New Tools

1. pocketbase-add-field-migration

• Purpose: Add a single field to an existing collection

• Advantage: Fine granularity - no need to rewrite all fields

• Usage example:

  {
    "collectionName": "products",
    "field": {
      "name": "stock",
      "type": "number",
      "required": false,
      "min": 0
    }
  }
  

2. pocketbase-remove-field-migration

• Purpose: Remove a single field from an existing collection

• Advantage: Targeted removal without affecting other fields

• Usage example:

  {
    "collectionName": "products",
    "fieldName": "stock"
  }
  

3. pocketbase-revert-migration

• Purpose: Revert a previous migration

• Advantage: Safety - ability to undo changes

• Usage example:

  {
    "migrationFile": "1768987877_add_field_stock_to_products.js"
  }
  

🔧 Improvement of pocketbase-execute-any-migration

• New detection: Now recognizes 6 types of migrations:

  1. create - Collection creation
  2. update - Rule modification
  3. update_fields - Modification of all fields
  4. add_field - Addition of a single field
  5. remove_field - Removal of a single field
  6. delete - Collection deletion

• Compatibility: Doesn't break existing functionality - the original pocketbase-execute-migration tool is preserved

🔗 Relation Fields Support (January 2026)

✨ Enhanced Support for Relation Fields

The MCP server now fully supports relation fields in PocketBase collections. This includes creating, updating, and managing collections with foreign key relationships between collections.

Key Improvements

1. Fixed parseMigrationFields() function in src/pocketbase-migration.ts:

   • Correctly handles collectionId parameter for relation fields
   • Properly serializes relation field configurations
   • Supports maxSelect and cascadeDelete options

2. Enhanced pocketbase-execute-any-migration tool:

   • Now correctly processes migration files containing relation fields
   • Properly handles the execution of migrations with complex field relationships

3. Updated pocketbase-update-collection-fields tool:

   • Supports adding/modifying relation fields in existing collections
   • Maintains backward compatibility with existing collections

📋 Relation Field Examples

Creating a Collection with Relation Fields

{
  "collectionName": "user_roles",
  "fields": [
    {
      "name": "user_ref",
      "type": "relation",
      "required": true,
      "collectionId": "users",
      "maxSelect": 1,
      "cascadeDelete": false
    },
    {
      "name": "role_ref",
      "type": "relation",
      "required": true,
      "collectionId": "roles",
      "maxSelect": 1,
      "cascadeDelete": false
    },
    {
      "name": "assigned_at",
      "type": "date",
      "required": true
    },
    {
      "name": "assigned_by",
      "type": "relation",
      "required": true,
      "collectionId": "users",
      "maxSelect": 1,
      "cascadeDelete": false
    }
  ],
  "type": "base"
}

Adding a Relation Field to an Existing Collection

{
  "collectionName": "posts",
  "field": {
    "name": "author",
    "type": "relation",
    "required": true,
    "collectionId": "users",
    "maxSelect": 1,
    "cascadeDelete": true
  }
}

🛠️ Technical Details

The fixes address the following issues:

1. Bug in parseMigrationFields(): The function was not correctly handling the collectionId parameter for relation fields, causing migrations to fail when creating collections with relations.

2. Migration Execution: The pocketbase-execute-any-migration tool now properly detects and executes migrations containing relation fields without errors.

3. Field Configuration: Relation fields now support all PocketBase options:

   • collectionId: The ID of the related collection (required)
   • maxSelect: Maximum number of related records (default: 1)
   • cascadeDelete: Whether to delete related records when the parent is deleted (default: false)

✅ Testing

The relation field support has been thoroughly tested with:

• ✅ Creating collections with relation fields: Works perfectly
• ✅ Adding relation fields to existing collections: Works perfectly
• ✅ Executing migrations with relation fields: Works perfectly
• ✅ Real-world use case: User roles system with users ↔ roles relationships

🎯 Real-World Example: User Roles System

A complete user roles system was implemented using the enhanced relation field support:

1. roles collection: Stores role definitions (level 0-9, level 99 for super admin)
2. user_roles collection: Junction table linking users to roles with relation fields
3. Access rules: Configured with proper authentication rules
4. Default role assignment: All new users automatically get level 1 (basic user)

This demonstrates the practical application of the relation field support in building complex database schemas with PocketBase.

🧪 Testing

The project has been successfully tested with:

• ✅ Manual tests of all features
• ✅ Real migrations executed on PocketBase
• ✅ Complete validation of the 13 MCP tools
• ✅ Tests of new features:
  • Field addition: ✅ Works
  • Field removal: ✅ Works
  • Migration revert: ✅ Works

To test the MCP server:

# Start the server in development mode
npm run dev

# Then use the tools via Cline Desktop or other MCP client

🔧 Development

Code Structure

• src/pocketbase-migration.ts: Migration generation logic

  • createMigrationFile(): Collection creation
  • createUpdateMigrationFile(): Collection modification
  • createDeleteMigrationFile(): Collection deletion
  • createUpdateFieldsMigrationFile(): Field modification
  • parseMigrationFields(): Parsing fields from migrations

• src/pocketbase-tools.ts: MCP tool definitions

  • 10 complete tools with Zod validation
  • Robust error handling
  • REST API to PocketBase

• src/index.ts: Main MCP server

  • Server configuration
  • Connection management
  • Logging and monitoring

Add a New Tool

1. Add the definition in pocketbase-tools.ts
2. Implement the business logic
3. Test manually with MCP tools
4. Document in the README

📊 Project Statistics

• 10 complete MCP tools
• 4 types of migrations supported (creation, modification, deletion, field modification)
• 100% TypeScript with Zod validation
• Complete REST API to PocketBase
• Robust error handling
• Complete documentation

🚀 Deployment on GitHub

Prepare the Project for GitHub

# Initialize git
git init

# Add files
git add .

# Initial commit
git commit -m "Initial commit: Complete PocketBase MCP Server"

# Create a repo on GitHub
# Link the remote repo
git remote add origin https://github.com/your-username/pocketbase-mcp.git

# Push the code
git push -u origin main

Files to Include in .gitignore

# Dependencies
node_modules/

# Build outputs
dist/

# Environment variables
.env
.env.local

# PocketBase migrations (optional)
pb_migrations/

# IDE
.vscode/
.idea/

# OS
.DS_Store

Package.json for Publication

Make sure your package.json contains:

{
  "name": "pocketbase-mcp",
  "version": "1.0.0",
  "description": "MCP Server for PocketBase migrations",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "dev": "tsx watch src/index.ts",
    "start": "node dist/index.js"
  },
  "keywords": ["mcp", "pocketbase", "migrations", "database"],
  "author": "Step by Step",
  "license": "MIT",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.22.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.0.0",
    "tsx": "^4.0.0"
  }
}