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

Related MCP server: PocketBase MCP Server

Installation

1. Clone and setup the project:

   cd pb_mcp npm install

2. Configure environment variables: The .env file 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

3. Build the project:

   npm run build

Usage

Development Mode

Production Mode

Running Tests

Code Quality

MCP Tools Overview

Authentication Tools

pb_auth_login

Authenticate a user with email and password.

Parameters:

• email (string, required): User email address

• password (string, required): User password

• options (object, optional): Additional auth options

Example:

pb_auth_register

Register a new user account.

Parameters:

• email (string, required): User email address

• password (string, required): Password (minimum 8 characters)

• passwordConfirm (string, required): Password confirmation

• username (string, optional): Username

• name (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 email

• password (string, required): New password

• passwordConfirm (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 criteria

• filter (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 impersonate

• duration (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 name

• type (string, required): Collection type ("base", "auth", "view")

• schema (array, optional): Field definitions

• listRule (string, optional): List access rule

• createRule (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 ID

• page (number, optional): Page number

• perPage (number, optional): Items per page

• sort (string, optional): Sort criteria

• filter (string, optional): Filter criteria

• expand (string, optional): Relations to expand

• fields (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 name

• recordId (string, required): Record ID

• filename (string, required): File name

• thumb (string, optional): Thumbnail size

pb_files_upload

Upload a file to a record field.

Parameters:

• collection (string, required): Collection name

• recordId (string, required): Record ID

• fieldName (string, required): Field name

• fileData (string, required): Base64 encoded file data

• fileName (string, required): Original file name

• mimeType (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

Design Principles

1. Type Safety: Full TypeScript implementation with strict type checking

2. Error Handling: Comprehensive error handling with proper error types

3. Authentication: Dual client support for user and admin operations

4. Validation: Parameter validation using Zod schemas

5. Logging: Structured logging for debugging and monitoring

6. Testing: Comprehensive test coverage for all functionality

Development

Adding New Tools

1. Define the tool schema in the appropriate file under src/tools/

2. Implement the handler function with proper error handling

3. Add parameter validation using Zod schemas

4. Export the tool and handler from the module

5. Register the tool in src/server.ts

6. Write tests for the new functionality

Configuration

The server uses environment variables for configuration:

• POCKETBASE_URL: PocketBase server URL

• SUPER_USER_LOGIN: Superuser email

• SUPER_USER_PASSWORD: Superuser password

• NODE_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:

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

1. Connection errors: Verify PocketBase URL and server availability

2. Authentication failures: Check superuser credentials in .env

3. Permission errors: Ensure proper collection access rules

4. Type errors: Run npm run typecheck to 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

1. Fork the repository

2. Create a feature branch

3. Implement your changes with tests

4. Run linting and type checking

5. 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