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:

"Set PocketBase URL to https://pb.example.com."
"Check my PocketBase server health."
"List all PocketBase collections."
"Authenticate as admin with email <your-email> and password <your-password>."
"Create a collection named notes with a required title text field."
"Create a record in notes with title First note."
"Show all records in notes, newest first."
"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)

auth_admin or auth_user
get_auth_status
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

dynamic-pocketbase-mcp