PocketBase MCP Server

Instructions

Implementation Reference

• src/tools/handlers/record.ts:38-63 (handler)

  Implements the core logic for the list_records tool: constructs query options from args, calls PocketBase collection.getList(), and returns JSON response or handles errors.

  export function createListRecordsHandler(pb: PocketBase): ToolHandler {
    return async (args: ListRecordsArgs) => {
      try {
        const options: any = {};
        
        // Add optional parameters
        if (args.filter) options.filter = args.filter;
        if (args.sort) options.sort = args.sort;
        if (args.expand) options.expand = args.expand;
        if (args.fields) options.fields = args.fields;
        if (args.skipTotal !== undefined) options.skipTotal = args.skipTotal;
        
        // Set pagination
        const page = args.page || 1;
        const perPage = args.perPage || 50;
        
        const result = await pb
          .collection(args.collection)
          .getList(page, perPage, options);
        
        return createJsonResponse(result);
      } catch (error: unknown) {
        throw handlePocketBaseError("list records", error);
      }
    };
  }

• src/tools/schemas/record.ts:28-65 (schema)

  Input schema (JSON Schema) for validating arguments to the list_records tool, defining properties like collection, filter, sort, pagination, etc.

  export const listRecordsSchema = {
    type: "object",
    properties: {
      collection: {
        type: "string",
        description: "Collection name",
      },
      filter: {
        type: "string",
        description: "Filter query using PocketBase filter syntax (e.g. 'status = true && created > \"2022-08-01 10:00:00\"')",
      },
      sort: {
        type: "string",
        description: "Sort field and direction (e.g. '-created,title' for descending created date followed by ascending title)",
      },
      page: {
        type: "number",
        description: "Page number for pagination (default: 1)",
      },
      perPage: {
        type: "number",
        description: "Items per page (default: 50, max: 500)",
      },
      expand: {
        type: "string",
        description: "Comma-separated list of relation fields to expand (e.g. 'author,comments.user')",
      },
      fields: {
        type: "string",
        description: "Comma-separated fields to return in the response (e.g. 'id,title,author')",
      },
      skipTotal: {
        type: "boolean",
        description: "If set to true, the total count query will be skipped to improve performance",
      },
    },
    required: ["collection"],
  };

• src/server.ts:131-136 (registration)

  Registers the list_records tool in the MCP server array, linking the name, description, input schema, and instantiated handler.

  {
    name: "list_records",
    description: "List records from a collection with optional filters",
    inputSchema: listRecordsSchema,
    handler: createListRecordsHandler(pb),
  },

• src/types/index.ts:91-100 (schema)

  TypeScript interface defining the structure of input arguments for the list_records handler, used for type safety.

  export interface ListRecordsArgs {
    collection: string;
    filter?: string;
    sort?: string;
    page?: number;
    perPage?: number;
    expand?: string;
    fields?: string;
    skipTotal?: boolean;
  }