🚀 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

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"
      }
    }
  }
}

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

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

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
Enhanced pocketbase-execute-any-migration tool:
- Now correctly processes migration files containing relation fields
- Properly handles the execution of migrations with complex field relationships
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:

Bug in parseMigrationFields(): The function was not correctly handling the collectionId parameter for relation fields, causing migrations to fail when creating collections with relations.
Migration Execution: The pocketbase-execute-any-migration tool now properly detects and executes migrations containing relation fields without errors.
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:

roles collection: Stores role definitions (level 0-9, level 99 for super admin)
user_roles collection: Junction table linking users to roles with relation fields
Access rules: Configured with proper authentication rules
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

Add the definition in pocketbase-tools.ts
Implement the business logic
Test manually with MCP tools
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"
  }
}

🚀 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

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"
      }
    }
  }
}

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

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

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
Enhanced pocketbase-execute-any-migration tool:
- Now correctly processes migration files containing relation fields
- Properly handles the execution of migrations with complex field relationships
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:

Bug in parseMigrationFields(): The function was not correctly handling the collectionId parameter for relation fields, causing migrations to fail when creating collections with relations.
Migration Execution: The pocketbase-execute-any-migration tool now properly detects and executes migrations containing relation fields without errors.
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:

roles collection: Stores role definitions (level 0-9, level 99 for super admin)
user_roles collection: Junction table linking users to roles with relation fields
Access rules: Configured with proper authentication rules
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

Add the definition in pocketbase-tools.ts
Implement the business logic
Test manually with MCP tools
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"
  }
}

PocketBase MCP Server

🚀 PocketBase MCP Server

📥 Installation from GitHub

Clone and install

Quick setup

📦 Global installation (optional)

✨ Features

✅ Available Tools (20 complete tools)

🏗️ Migration Tools (13 tools)

📊 CRUD Tools (7 tools)

🚀 Installation (Alternative)

Prerequisites

Local installation

Configuration

📦 Project Structure

🛠️ Usage

Start the MCP Server

Cline Desktop Configuration

📝 Complete Examples

1. Create a Collection

2. Modify Collection Rules

3. Modify Collection Fields

4. Delete a Collection

5. Execute a Migration

6. Add a Field to a Collection

7. Remove a Field from a Collection

8. Revert a Migration

🔄 Complete Workflow

Step 1: Create a Migration

Step 2: Execute the Migration

Step 3: Verify

Step 4: Modify if necessary

🎯 Advanced Use Cases

Creation Migration with Authentication Rules

Authentication Collection Migration

⚙️ Technical Configuration

Environment Variables

NPM Scripts

🆕 New Features (January 2026)

✨ Addition of 3 New Tools

1. pocketbase-add-field-migration

2. pocketbase-remove-field-migration

3. pocketbase-revert-migration

🔧 Improvement of pocketbase-execute-any-migration

🔗 Relation Fields Support (January 2026)

✨ Enhanced Support for Relation Fields

Key Improvements

📋 Relation Field Examples

Creating a Collection with Relation Fields

Adding a Relation Field to an Existing Collection

🛠️ Technical Details

✅ Testing

🎯 Real-World Example: User Roles System

🧪 Testing

🔧 Development

Code Structure

Add a New Tool

📊 Project Statistics

🚀 Deployment on GitHub

Prepare the Project for GitHub

Files to Include in .gitignore

Package.json for Publication

🚀 PocketBase MCP Server

📥 Installation from GitHub

Clone and install

Quick setup

📦 Global installation (optional)

✨ Features

✅ Available Tools (20 complete tools)

🏗️ Migration Tools (13 tools)

📊 CRUD Tools (7 tools)

🚀 Installation (Alternative)

Prerequisites

Local installation

Configuration

📦 Project Structure

🛠️ Usage

Start the MCP Server

Cline Desktop Configuration

📝 Complete Examples

1. `pocketbase-add-field-migration`

2. `pocketbase-remove-field-migration`

3. `pocketbase-revert-migration`

🔧 Improvement of `pocketbase-execute-any-migration`

1. `pocketbase-add-field-migration`

2. `pocketbase-remove-field-migration`

3. `pocketbase-revert-migration`

🔧 Improvement of `pocketbase-execute-any-migration`