# 🚀 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
```bash
# 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):
```json
{
"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**:
```bash
# Start the server in development mode
npm run dev
```
### 📦 Global installation (optional)
```bash
# 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
```bash
# 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](#-installation-from-github) section above.
### Configuration
Environment variables are configured in the MCP configuration file (`cline_mcp_settings.json`):
```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
```bash
# Development
npm run dev
# Production
npm run build
node dist/index.js
```
### Cline Desktop Configuration
Add to `~/.cline_desktop_config.json`:
```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
```json
{
"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
```json
{
"collectionName": "products",
"listRule": "@request.auth.id != ''",
"createRule": "@request.auth.id != ''",
"updateRule": "@request.auth.id != ''",
"deleteRule": "@request.auth.id != ''"
}
```
### 3. Modify Collection Fields
```json
{
"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
```json
{
"collectionName": "old_collection"
}
```
### 5. Execute a Migration
```json
{
"migrationFile": "1768985344_update_products.js"
}
```
### 6. Add a Field to a Collection
```json
{
"collectionName": "products",
"field": {
"name": "stock",
"type": "number",
"required": false,
"min": 0
}
}
```
### 7. Remove a Field from a Collection
```json
{
"collectionName": "products",
"fieldName": "stock"
}
```
### 8. Revert a Migration
```json
{
"migrationFile": "1768987877_add_field_stock_to_products.js"
}
```
## 🔄 Complete Workflow
### Step 1: Create a Migration
```bash
# Use the pocketbase-create-collection-migration tool
# → Generates a file in pb_migrations/
```
### Step 2: Execute the Migration
```bash
# Use the pocketbase-execute-any-migration tool
# → Executes the migration via REST API
```
### Step 3: Verify
```bash
# Use pocketbase-list-collections
# → Verifies that the collection was created
```
### Step 4: Modify if necessary
```bash
# Use pocketbase-update-collection
# → Generates a modification migration
# → Execute with pocketbase-execute-any-migration
```
## 🎯 Advanced Use Cases
### Creation Migration with Authentication Rules
```json
{
"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
```json
{
"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
```json
{
"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**:
```json
{
"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**:
```json
{
"collectionName": "products",
"fieldName": "stock"
}
```
#### 3. **`pocketbase-revert-migration`**
- **Purpose**: Revert a previous migration
- **Advantage**: Safety - ability to undo changes
- **Usage example**:
```json
{
"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
```json
{
"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
```json
{
"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:
```bash
# 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
```bash
# 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
```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:
```json
{
"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"
}
}
