dynamic-pocketbase-mcp

Dynamic Model Context Protocol (MCP) server for PocketBase. Connect your AI client once, then manage collections and records in any PocketBase project using runtime tools.

Why this server is different

Many PocketBase MCP servers are static: they hardcode collection-specific behavior or require custom tool definitions per schema.

dynamic-pocketbase-mcp is dynamic:

• Uses collection-agnostic tools (list_collections, list_records, create_record, etc.)
• Works across existing and newly created collections without regenerating server code
• Exposes live PocketBase collections as MCP resources

Features

• 18 MCP tools for health, auth, collections, rules, and records
• Collection lifecycle operations (create, update, delete, inspect)
• Record CRUD with filters, sorting, pagination, and field selection
• Session-based auth via tools (auth_admin, auth_user, get_auth_status, logout)
• Built-in references for field schema and rules syntax

Installation

npm install dynamic-pocketbase-mcp
# or
bun install dynamic-pocketbase-mcp

Configure in an AI client

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "dynamic-pocketbase": {
      "command": "npx",
      "args": ["-y", "dynamic-pocketbase-mcp"]
    }
  }
}

If POCKETBASE_URL is not set, the server defaults to http://localhost:8090.

Direct usage

# Use default URL (http://localhost:8090)
npx -y dynamic-pocketbase-mcp

# Use custom PocketBase URL
POCKETBASE_URL=https://pb.example.com \
bunx dynamic-pocketbase-mcp

Simple tutorial: chat with AI using this MCP

After you configure your MCP client, open a chat and try prompts like this:

1. "Set PocketBase URL to https://pb.example.com."
2. "Check my PocketBase server health."
3. "List all PocketBase collections."
4. "Authenticate as admin with email <your-email> and password <your-password>."
5. "Create a collection named notes with a required title text field."
6. "Create a record in notes with title First note."
7. "Show all records in notes, newest first."
8. "Log out from PocketBase auth session."

If those steps succeed, your AI can now manage schema and data through this MCP server.

Authentication flow (via tools)

1. auth_admin or auth_user
2. get_auth_status
3. logout

Available tools

Health and references

• health - Check PocketBase server health status
• set_base_url - Update PocketBase URL for current MCP session and clear auth token
• get_field_schema_reference - Get field types documentation
• get_rules_reference - Get API rules syntax reference

Authentication

• auth_admin - Authenticate as admin/superuser
• auth_user - Authenticate as auth collection user (email/username)
• get_auth_status - Check current authentication status
• logout - Clear authentication session

Collections

• list_collections - List all collections
• view_collection - View collection by name or ID
• create_collection - Create new collection
• update_collection - Update collection schema/settings
• delete_collection - Delete collection
• update_collection_rules - Update access control rules

Records

• list_records - List/search records with filtering, sorting, pagination
• view_record - View single record by ID
• create_record - Create new record
• update_record - Update existing record
• delete_record - Delete record

Development

# Install dependencies
bun install

# Run in development mode
bun run dev

# Type check
bun run typecheck

# Run tests (builds dist first)
bun run test

# Run all checks (typecheck + tests)
bun run check

# Interactive release helper (bump, check, publish, push tag)
bun run release

# Build for production
bun run build

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | POCKETBASE_URL | No | PocketBase server URL (default: http://localhost:8090) |

License

MIT