pocketbase-mcp

Pocketbase MCP Server

MCP (Model Context Protocol) server for Pocketbase - enables AI assistants to interact with Pocketbase backend through a clean, type-safe API.

Features

• 🔐 Silent Authentication - Automatic authentication with retry logic
• 📦 Full CRUD Operations - Complete record management
• 🔍 Advanced Querying - Filtering, sorting, pagination, field selection
• 📊 Collections Management - List and inspect collections
• 📝 Logs Access - Query system logs with filters
• 🛡️ Type Safety - Full TypeScript support with Zod validation
• 🏗️ Clean Architecture - Layered design for easy maintenance

Installation

# Install dependencies
pnpm install

# Build the project
pnpm build

Configuration

Environment Variables

Create a .env file in the project root:

POCKETBASE_URL=https://your-pocketbase-instance.com
POCKETBASE_IDENTITY=your-email@example.com
POCKETBASE_PASSWORD=your-password

MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop):

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pocketbase": {
      "command": "node",
      "args": ["path/to/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "https://your-pocketbase-instance.com",
        "POCKETBASE_IDENTITY": "your-email@example.com",
        "POCKETBASE_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

1. pocketbase_auth (Optional)

Authenticate with Pocketbase. Note: Authentication is handled automatically for other tools.

pocketbase_auth({
  pocketbaseUrl?: string,
  identity?: string,
  password?: string
})

2. pocketbase_list_collections

List all collections from Pocketbase.

pocketbase_list_collections({
  page?: number,        // default: 1
  perPage?: number,     // default: 500
  skipTotal?: number    // default: 1
})

3. pocketbase_list_records

List records from a collection with filtering and pagination.

pocketbase_list_records({
  collection: string,   // required
  page?: number,
  perPage?: number,     // default: 30, max: 500
  sort?: string,        // e.g., "-created,name"
  filter?: string,      // e.g., 'status="active"'
  expand?: string,      // e.g., "user,category"
  fields?: string,      // e.g., "id,name,email"
  skipTotal?: number
})

4. pocketbase_get_record

Get a single record by ID.

pocketbase_get_record({
  collection: string,   // required
  id: string,          // required
  expand?: string,
  fields?: string
})

5. pocketbase_create_record

Create a new record in a collection.

pocketbase_create_record({
  collection: string,   // required
  data: object,        // required - record data
  expand?: string,
  fields?: string
})

6. pocketbase_update_record

Update an existing record.

pocketbase_update_record({
  collection: string,   // required
  id: string,          // required
  data: object,        // required - fields to update
  expand?: string,
  fields?: string
})

7. pocketbase_delete_record

Delete a record from a collection.

pocketbase_delete_record({
  collection: string,   // required
  id: string           // required
})

8. pocketbase_list_logs

Query system logs with filtering and pagination.

pocketbase_list_logs({
  page?: number,
  perPage?: number,     // default: 50, max: 500
  sort?: string,
  filter?: string,      // e.g., '(message ~ "error")'
  skipTotal?: number    // default: 1
})

Architecture

The project follows a clean, layered architecture:

src/
├── index.ts              # MCP server entry point
├── config/               # Environment configuration
├── types/                # TypeScript type definitions
├── schemas/              # Zod validation schemas
├── utils/                # Error handling & response formatting
├── client/               # HTTP client & authentication manager
├── repositories/         # Data access layer
├── services/             # Business logic layer
├── handlers/             # MCP request handlers
└── tools/                # Tool definitions registry

Design Patterns

• Repository Pattern: Separates data access from business logic
• Service Pattern: Encapsulates business logic
• Singleton Pattern: For HTTP client and auth manager
• Template Method: Base classes for common functionality
• Dependency Injection: Services injected into handlers

Development

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start

License

ISC