PocketBase MCP Server
A comprehensive Model Context Protocol (MCP) server for PocketBase, providing both user and superuser functionality through a rich set of tools.
Features
🔐 User Authentication
- User login/logout with email and password
- User registration with validation
- Password reset workflows
- Token refresh functionality
- Current user information retrieval
👨💼 Administrative Functions
- Superuser authentication
- User management (create, read, update, delete)
- User impersonation for testing
- Application settings management
📊 Collection & Record Management
- Full CRUD operations for collections
- Collection schema management
- Record creation, reading, updating, and deletion
- Advanced filtering and pagination
- Bulk record operations
📁 File Management
- File upload to records
- File URL generation with thumbnail support
- File deletion and management
- Private file access tokens
🔧 System Operations
- Health checks
- System logs retrieval and analysis
- Backup creation and management
- Email testing functionality
- Server information retrieval
Installation
-
Clone and setup the project:
cd pb_mcp npm install -
Configure environment variables: The
.envfile should contain:POCKETBASE_URL=http://10.69.100.111:8090 SUPER_USER_LOGIN=your-admin@email.com SUPER_USER_PASSWORD=your-admin-password NODE_ENV=development LOG_LEVEL=info -
Build the project:
npm run build
Usage
Development Mode
npm run dev
Production Mode
npm run start
Running Tests
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
Code Quality
# Run linting
npm run lint
# Fix linting issues
npm run lint:fix
# Type checking
npm run typecheck
MCP Tools Overview
Authentication Tools
pb_auth_login
Authenticate a user with email and password.
Parameters:
email(string, required): User email addresspassword(string, required): User passwordoptions(object, optional): Additional auth options
Example:
{
"email": "user@example.com",
"password": "securepassword",
"options": {
"expand": "profile",
"fields": "id,email,username"
}
}
pb_auth_register
Register a new user account.
Parameters:
email(string, required): User email addresspassword(string, required): Password (minimum 8 characters)passwordConfirm(string, required): Password confirmationusername(string, optional): Usernamename(string, optional): Display name
pb_auth_refresh
Refresh the current authentication token.
pb_auth_logout
Logout the current user and clear authentication.
pb_auth_get_user
Get information about the currently authenticated user.
pb_auth_request_password_reset
Request a password reset email.
Parameters:
email(string, required): Email address for password reset
pb_auth_confirm_password_reset
Confirm password reset with token.
Parameters:
token(string, required): Reset token from emailpassword(string, required): New passwordpasswordConfirm(string, required): Password confirmation
Admin Tools
pb_admin_login
Authenticate as superuser/admin.
pb_admin_list_users
List all users (admin only).
Parameters:
page(number, optional): Page number (default: 1)perPage(number, optional): Items per page (default: 30)sort(string, optional): Sort criteriafilter(string, optional): Filter criteria
pb_admin_create_user
Create a new user (admin only).
pb_admin_update_user
Update an existing user (admin only).
pb_admin_delete_user
Delete a user (admin only).
pb_admin_impersonate_user
Impersonate a user for testing (admin only).
Parameters:
recordId(string, required): User ID to impersonateduration(number, optional): Token duration in seconds
pb_admin_get_settings
Get application settings (admin only).
pb_admin_update_settings
Update application settings (admin only).
Collection Tools
pb_collections_list
List all collections (admin only).
pb_collections_get
Get a specific collection by ID or name (admin only).
pb_collections_create
Create a new collection (admin only).
Parameters:
name(string, required): Collection nametype(string, required): Collection type ("base", "auth", "view")schema(array, optional): Field definitionslistRule(string, optional): List access rulecreateRule(string, optional): Create access rule- etc.
pb_collections_update
Update an existing collection (admin only).
pb_collections_delete
Delete a collection (admin only).
Record Tools
pb_records_list
List records from a collection with filtering and pagination.
Parameters:
collection(string, required): Collection name or IDpage(number, optional): Page numberperPage(number, optional): Items per pagesort(string, optional): Sort criteriafilter(string, optional): Filter criteriaexpand(string, optional): Relations to expandfields(string, optional): Fields to return
pb_records_get
Get a specific record by ID.
pb_records_create
Create a new record.
pb_records_update
Update an existing record.
pb_records_delete
Delete a record.
pb_records_bulk_create
Create multiple records at once.
File Tools
pb_files_get_url
Get the URL for a file attached to a record.
Parameters:
collection(string, required): Collection namerecordId(string, required): Record IDfilename(string, required): File namethumb(string, optional): Thumbnail size
pb_files_upload
Upload a file to a record field.
Parameters:
collection(string, required): Collection namerecordId(string, required): Record IDfieldName(string, required): Field namefileData(string, required): Base64 encoded file datafileName(string, required): Original file namemimeType(string, optional): File MIME type
pb_files_delete
Delete a file from a record field.
pb_files_get_token
Get a file access token for private files.
pb_files_list_record_files
List all files attached to a record.
System Tools
pb_health_check
Check the health status of the PocketBase server.
pb_server_info
Get PocketBase server information and configuration.
pb_logs_list
Get system logs (admin only).
pb_logs_stats
Get log statistics (admin only).
pb_backups_create
Create a new backup (admin only).
pb_backups_list
List all available backups (admin only).
pb_system_test_email
Send a test email (admin only).
Architecture
Project Structure
pb_mcp/
├── src/
│ ├── server.ts # Main MCP server
│ ├── pocketbase-service.ts # PocketBase client wrapper
│ ├── tools/ # Individual MCP tools
│ │ ├── auth.ts # User authentication tools
│ │ ├── admin.ts # Superuser/admin tools
│ │ ├── collections.ts # Collection management
│ │ ├── records.ts # Record CRUD operations
│ │ ├── files.ts # File management
│ │ └── system.ts # Health, logs, backups
│ ├── types/ # TypeScript definitions
│ │ ├── pocketbase.ts # PocketBase types
│ │ └── mcp.ts # MCP tool types
│ └── utils/ # Utility functions
│ ├── config.ts # Environment configuration
│ └── logger.ts # Logging utility
├── tests/ # Test files
├── package.json
├── tsconfig.json
├── .eslintrc.js
└── jest.config.js
Design Principles
- Type Safety: Full TypeScript implementation with strict type checking
- Error Handling: Comprehensive error handling with proper error types
- Authentication: Dual client support for user and admin operations
- Validation: Parameter validation using Zod schemas
- Logging: Structured logging for debugging and monitoring
- Testing: Comprehensive test coverage for all functionality
Development
Adding New Tools
- Define the tool schema in the appropriate file under
src/tools/ - Implement the handler function with proper error handling
- Add parameter validation using Zod schemas
- Export the tool and handler from the module
- Register the tool in
src/server.ts - Write tests for the new functionality
Configuration
The server uses environment variables for configuration:
POCKETBASE_URL: PocketBase server URLSUPER_USER_LOGIN: Superuser emailSUPER_USER_PASSWORD: Superuser passwordNODE_ENV: Environment (development/production/test)LOG_LEVEL: Logging level (debug/info/warn/error)
Error Handling
The server implements comprehensive error handling:
- PocketBaseError: Custom error class for PocketBase-specific errors
- Parameter validation: Zod schema validation with detailed error messages
- Graceful degradation: Proper error responses for all failure cases
- Logging: All errors are logged with context information
Testing
The project includes comprehensive test coverage:
- Unit tests: Individual component testing
- Integration tests: Full workflow testing
- Mock tests: External dependency mocking
- Coverage reports: Code coverage analysis
Run tests with:
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # With coverage
Security Considerations
- Environment variables: Sensitive credentials stored in environment variables
- Authentication tokens: Proper token management and refresh
- Parameter validation: All inputs validated before processing
- Error messages: No sensitive information leaked in error responses
- Admin operations: Proper authentication checks for admin-only functions
Troubleshooting
Common Issues
- Connection errors: Verify PocketBase URL and server availability
- Authentication failures: Check superuser credentials in
.env - Permission errors: Ensure proper collection access rules
- Type errors: Run
npm run typecheckto identify type issues
Debug Logging
Set LOG_LEVEL=debug in your .env file for detailed logging.
Health Check
Use the pb_health_check tool to verify server connectivity and status.
Contributing
- Fork the repository
- Create a feature branch
- Implement your changes with tests
- Run linting and type checking
- Submit a pull request
License
MIT License - see LICENSE file for details.
Support
For issues and questions:
- Check the troubleshooting section
- Review the test files for usage examples
- Create an issue in the repository