🚀 PocketBase MCP 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)

📊 CRUD Tools (7 tools)

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

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

🧪 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",
    "types