brynnjocelyn/pocketbase_mcp_server
If you are the rightful owner of pocketbase_mcp_server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
PocketBase MCP Server is a comprehensive Model Context Protocol server that provides tools for managing PocketBase instances.
PocketBase MCP Server
A comprehensive Model Context Protocol (MCP) server that provides tools for managing PocketBase instances. This server enables LLMs to interact with PocketBase databases through a standardized protocol.
Overview
This MCP server exposes PocketBase functionality as tools that can be used by any MCP-compatible client (like Claude Desktop, Cursor, or other LLM applications). It provides comprehensive access to PocketBase features with 60+ tools covering all major operations.
Features
Collection Management
- List, get, create, update, and delete collections
- Import/export collections in bulk
- Full schema management support
Record Operations
- CRUD operations with filtering, sorting, and pagination
getFullList
for retrieving all records without paginationgetFirstListItem
for finding the first matching record- Advanced query support with field selection and relation expansion
- Batch operations for efficient bulk processing
Authentication & User Management
- Multiple auth methods: password, OAuth2, OTP
- Complete auth flow support: registration, login, password reset, email verification
- Email change functionality
- Auth token refresh
- List available auth methods for collections
File Management
- Generate file URLs with thumbnail support
- Private file token generation
- Download forcing support
System Operations
- Health monitoring
- Settings management
- Log viewing with statistics
- Cron job management and execution
Backup & Restore
- Create, list, download, and delete backups
- Full backup restoration support
Hook Management
- List, read, create, and delete JavaScript hooks
- Pre-built templates for common patterns
Installation
npm install
npm run build
Configuration
The server can be configured to connect to different PocketBase instances using (in order of precedence):
-
Local config file (
.pocketbase-mcp.json
in your project directory):{ "url": "http://localhost:8091" }
-
Environment variable:
POCKETBASE_URL
: URL of your PocketBase instance
-
Default:
http://127.0.0.1:8090
Multi-Project Setup
Option 1: Project-Specific Configuration (Recommended)
Each project can have its own MCP configuration:
# In project directory
claude mcp add-json pocketbase '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "http://localhost:8091"}}' --scope project
Option 2: Config File
Create a .pocketbase-mcp.json
in your project root:
{
"url": "https://api.myproject.com"
}
Option 3: Multiple Named Servers
Add different PocketBase instances globally:
claude mcp add-json pb-local '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "http://localhost:8090"}}'
claude mcp add-json pb-prod '{"command": "node", "args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"], "env": {"POCKETBASE_URL": "https://api.myapp.com"}}'
Usage with Claude Desktop
Add this configuration to your Claude Desktop MCP settings:
{
"mcpServers": {
"pocketbase": {
"command": "node",
"args": ["/path/to/pocketbase-mcp-server/dist/mcp-server.js"],
"env": {
"POCKETBASE_URL": "http://localhost:8090"
}
}
}
}
Available Tools
Collection Management Tools
list_collections
- List all collections with pagination and filteringget_collection
- Get a specific collection by ID or namecreate_collection
- Create a new collection with schemaupdate_collection
- Update collection settings and schemadelete_collection
- Delete a collectionimport_collections
- Import multiple collections at once
Record Management Tools
list_records
- List records with pagination, filtering, sorting, and field selectionget_full_list
- Get all records without pagination (batch processing)get_first_list_item
- Get the first record matching a filterget_record
- Get a specific record by IDcreate_record
- Create a new recordupdate_record
- Update an existing recorddelete_record
- Delete a record
Batch Operations
batch_create
- Create multiple records in a single transactionbatch_update
- Update multiple records in a single transactionbatch_delete
- Delete multiple records in a single transactionbatch_upsert
- Upsert multiple records in a single transaction
Authentication Tools
list_auth_methods
- Get available authentication methodsauth_with_password
- Authenticate with email/username and passwordauth_with_oauth2
- Get OAuth2 authentication URLauth_refresh
- Refresh authentication tokenrequest_otp
- Request OTP for email authenticationauth_with_otp
- Authenticate with OTPrequest_password_reset
- Send password reset emailconfirm_password_reset
- Confirm password reset with tokenrequest_verification
- Send verification emailconfirm_verification
- Confirm email verificationrequest_email_change
- Request email changeconfirm_email_change
- Confirm email change
File Management Tools
get_file_url
- Generate URL for accessing files with optionsget_file_token
- Get private file access token
Log Management Tools
list_logs
- List system logs with filteringget_log
- Get a specific log entryget_log_stats
- Get log statistics
Cron Job Tools
list_cron_jobs
- List all cron jobsrun_cron_job
- Manually run a cron job
System Tools
get_health
- Check PocketBase health statusget_settings
- Get PocketBase settings (requires admin auth)update_settings
- Update PocketBase settings (requires admin auth)
Backup Tools
create_backup
- Create a backuplist_backups
- List available backupsdownload_backup
- Get download URL for a backupdelete_backup
- Delete a backuprestore_backup
- Restore from a backup
Hook Management Tools
list_hooks
- List JavaScript hook files in the pb_hooks directoryread_hook
- Read the contents of a hook filecreate_hook
- Create or update a JavaScript hook filedelete_hook
- Delete a hook filecreate_hook_template
- Generate hook templates for common patterns:record-validation
: Field validation for recordsrecord-auth
: Custom authentication logiccustom-route
: API endpoint creationfile-upload
: File upload validationscheduled-task
: Cron job setup
Tool Examples
List Records with Filtering
{
"tool": "list_records",
"arguments": {
"collection": "posts",
"filter": "published = true && created >= '2024-01-01'",
"sort": "-created",
"expand": "author",
"fields": "id,title,content,author",
"skipTotal": true
}
}
Get All Records Without Pagination
{
"tool": "get_full_list",
"arguments": {
"collection": "categories",
"sort": "name",
"batch": 1000
}
}
Batch Create Records
{
"tool": "batch_create",
"arguments": {
"requests": [
{
"collection": "posts",
"data": {
"title": "First Post",
"content": "Content 1"
}
},
{
"collection": "posts",
"data": {
"title": "Second Post",
"content": "Content 2"
}
}
]
}
}
OAuth2 Authentication
{
"tool": "auth_with_oauth2",
"arguments": {
"collection": "users",
"provider": "google",
"redirectURL": "https://myapp.com/auth/callback"
}
}
OTP Authentication Flow
// Step 1: Request OTP
{
"tool": "request_otp",
"arguments": {
"collection": "users",
"email": "user@example.com"
}
}
// Step 2: Authenticate with OTP
{
"tool": "auth_with_otp",
"arguments": {
"collection": "users",
"otpId": "otp_id_from_step_1",
"password": "123456"
}
}
Get File URL with Thumbnail
{
"tool": "get_file_url",
"arguments": {
"collection": "products",
"recordId": "abc123",
"filename": "photo.jpg",
"thumb": "300x200"
}
}
Create a Hook Template
{
"tool": "create_hook_template",
"arguments": {
"type": "record-validation",
"collection": "posts"
}
}
Query Syntax
The MCP server supports PocketBase's full query syntax:
Filter Examples
title = "example"
- Exact matchcreated >= "2024-01-01"
- Date comparisontitle ~ "search"
- Contains texttags ?~ "important"
- Any array element containsuser.name = "John"
- Nested field access
Sort Examples
created
- Ascending by created-created
- Descending by createdname,-created
- Multiple sort fields
Expand Examples
author
- Expand single relationauthor,tags
- Expand multiple relationsauthor.profile
- Nested expansion
Field Selection
id,title,content
- Select specific fields*,expand.author.name
- Include expanded fields
Performance Optimization
- Use
skipTotal: true
when you don't need the total count - Use
fields
parameter to limit data transfer - Use
get_full_list
with appropriate batch sizes for large datasets - Use batch operations for bulk record modifications
Development
Running in Development Mode
npm run dev
Building
npm run build
Architecture
The MCP server follows the Model Context Protocol specification:
- MCP Server: Handles tool registration and execution
- PocketBase Client: Uses the official PocketBase JavaScript SDK
- Tool Handlers: Implement specific PocketBase operations with proper error handling
Error Handling
All tools include comprehensive error handling and return descriptive error messages. Common errors include:
- Invalid authentication
- Missing required fields
- Network connectivity issues
- Permission denied errors
Security Considerations
- Admin operations require appropriate authentication
- Use environment variables for sensitive configuration
- The server inherits PocketBase's security model and access rules
- OAuth2 state parameters are handled securely
Version Compatibility
- Requires PocketBase v0.20.0 or higher
- Uses PocketBase JavaScript SDK v0.21.0+
- Implements MCP protocol version 1.0
Contributing
Contributions are welcome! Please ensure that any new tools:
- Follow the existing naming patterns
- Include proper TypeScript types
- Have comprehensive error handling
- Are documented in this README
License
ISC