PocketBase MCP Server

Instructions

Implementation Reference

• src/tools/handlers/migration.ts:130-192 (handler)

  The main handler function createImportDataHandler that returns the async ToolHandler for executing the import_data tool logic. It handles create, update, upsert modes for importing data into a PocketBase collection.

  export function createImportDataHandler(pb: PocketBase): ToolHandler {
    return async (args: ImportDataArgs) => {
      try {
        const { collection, data, mode = "create" } = args;
        const results = {
          created: 0,
          updated: 0,
          errors: [] as string[],
        };
  
        for (const item of data) {
          try {
            switch (mode) {
              case "create":
                await pb.collection(collection).create(item);
                results.created++;
                break;
  
              case "update":
                if (!item.id) {
                  results.errors.push("Update mode requires 'id' field in each record");
                  continue;
                }
                await pb.collection(collection).update(item.id, item);
                results.updated++;
                break;
  
              case "upsert":
                if (item.id) {
                  try {
                    await pb.collection(collection).update(item.id, item);
                    results.updated++;
                  } catch {
                    await pb.collection(collection).create(item);
                    results.created++;
                  }
                } else {
                  await pb.collection(collection).create(item);
                  results.created++;
                }
                break;
  
              default:
                throw new McpError(
                  ErrorCode.InvalidParams,
                  `Unsupported import mode: ${mode}`
                );
            }
          } catch (error: any) {
            results.errors.push(`Failed to import record: ${error.message}`);
          }
        }
  
        return createJsonResponse({
          success: true,
          results,
          message: `Import completed: ${results.created} created, ${results.updated} updated, ${results.errors.length} errors`,
        });
      } catch (error: unknown) {
        throw handlePocketBaseError("import data", error);
      }
    };
  }

• src/tools/schemas/migration.ts:95-116 (schema)

  The input schema for the import_data tool, defining the expected parameters: collection name, data array, and optional mode.

  export const importDataSchema = {
    type: "object",
    properties: {
      collection: {
        type: "string",
        description: "Collection name",
      },
      data: {
        type: "array",
        description: "Array of records to import",
        items: {
          type: "object",
        },
      },
      mode: {
        type: "string",
        enum: ["create", "update", "upsert"],
        description: "Import mode (default: create)",
      },
    },
    required: ["collection", "data"],
  };

• src/server.ts:191-196 (registration)

  The registration of the import_data tool in the MCP server tools array, linking the name, description, schema, and handler.

  {
    name: "import_data",
    description: "Import data into a collection",
    inputSchema: importDataSchema,
    handler: createImportDataHandler(pb),
  },