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

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

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 address
• password (string, required): User password
• options (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 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

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

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:

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

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