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 .env file should contain:

POCKETBASE_URL=http://10.69.100.111:8090
[email protected]
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 address
password (string, required): User password
options (object, optional): Additional auth options

Example:

{
  "email": "[email protected]",
  "password": "securepassword",
  "options": {
    "expand": "profile",
    "fields": "id,email,username"
  }
}

`pb_auth_register`

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

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

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

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