Self-Hosted Supabase MCP Server

Instructions

Implementation Reference

• src/tools/list_storage_buckets.ts:36-82 (handler)

  The tool handler definition including the execute function that queries the storage.buckets table via direct PG connection and validates the output.

  export const listStorageBucketsTool = {
      name: 'list_storage_buckets',
      description: 'Lists all storage buckets in the project.',
      mcpInputSchema,
      inputSchema,
      outputSchema: ListStorageBucketsOutputSchema,
  
      execute: async (
          input: Input,
          context: ToolContext
      ): Promise<ListStorageBucketsOutput> => {
          const client = context.selfhostedClient;
          // Use console.error for operational logging
          console.error('Listing storage buckets...');
  
          // Check if direct DB connection is available, as it's likely needed for storage schema
          if (!client.isPgAvailable()) {
              // Log error for MCP client
              context.log('Direct database connection (DATABASE_URL) is required to list storage buckets.', 'error');
              throw new Error('Direct database connection (DATABASE_URL) is required to list storage buckets.');
          }
  
          const sql = `
              SELECT
                  id,
                  name,
                  owner,
                  public,
                  avif_autodetection,
                  file_size_limit,
                  allowed_mime_types,
                  created_at::text, -- Cast to text
                  updated_at::text  -- Cast to text
              FROM storage.buckets;
          `;
  
          console.error('Attempting to list storage buckets using direct DB connection...');
          const result = await client.executeSqlWithPg(sql);
  
          // Validate and return using handler
          const validatedBuckets = handleSqlResponse(result, ListStorageBucketsOutputSchema);
  
          console.error(`Found ${validatedBuckets.length} buckets.`);
          context.log(`Found ${validatedBuckets.length} buckets.`); // Also log for MCP
          return validatedBuckets;
      },
  };

• src/tools/list_storage_buckets.ts:8-22 (schema)

  Zod schemas for output validation: BucketSchema and ListStorageBucketsOutputSchema (array of buckets).

  const BucketSchema = z.object({
      id: z.string(),
      name: z.string(),
      owner: z.string().nullable(),
      public: z.boolean(),
      avif_autodetection: z.boolean(),
      file_size_limit: z.number().nullable(),
      allowed_mime_types: z.array(z.string()).nullable(),
      // Keep timestamps as strings as returned by DB/pg
      created_at: z.string().nullable(),
      updated_at: z.string().nullable(),
  });
  
  const ListStorageBucketsOutputSchema = z.array(BucketSchema);
  type ListStorageBucketsOutput = StorageBucket[];

• src/tools/list_storage_buckets.ts:25-32 (schema)

  Input schemas: empty object schema for no inputs (MCP static JSON and Zod).

  export const mcpInputSchema = {
      type: 'object',
      properties: {},
      required: [],
  };
  
  // Zod schema for runtime input validation
  const inputSchema = z.object({});

• src/index.ts:98-121 (registration)

  Registration of all tools including list_storage_buckets in the availableTools object used by the MCP server.

  const availableTools = {
      // Cast here assumes tools will implement AppTool structure
      [listTablesTool.name]: listTablesTool as AppTool,
      [listExtensionsTool.name]: listExtensionsTool as AppTool,
      [listMigrationsTool.name]: listMigrationsTool as AppTool,
      [applyMigrationTool.name]: applyMigrationTool as AppTool,
      [executeSqlTool.name]: executeSqlTool as AppTool,
      [getDatabaseConnectionsTool.name]: getDatabaseConnectionsTool as AppTool,
      [getDatabaseStatsTool.name]: getDatabaseStatsTool as AppTool,
      [getProjectUrlTool.name]: getProjectUrlTool as AppTool,
      [getAnonKeyTool.name]: getAnonKeyTool as AppTool,
      [getServiceKeyTool.name]: getServiceKeyTool as AppTool,
      [generateTypesTool.name]: generateTypesTool as AppTool,
      [rebuildHooksTool.name]: rebuildHooksTool as AppTool,
      [verifyJwtSecretTool.name]: verifyJwtSecretTool as AppTool,
      [listAuthUsersTool.name]: listAuthUsersTool as AppTool,
      [getAuthUserTool.name]: getAuthUserTool as AppTool,
      [deleteAuthUserTool.name]: deleteAuthUserTool as AppTool,
      [createAuthUserTool.name]: createAuthUserTool as AppTool,
      [updateAuthUserTool.name]: updateAuthUserTool as AppTool,
      [listStorageBucketsTool.name]: listStorageBucketsTool as AppTool,
      [listStorageObjectsTool.name]: listStorageObjectsTool as AppTool,
      [listRealtimePublicationsTool.name]: listRealtimePublicationsTool as AppTool,
  };

• src/index.ts:32-32 (registration)

  Import of the list_storage_buckets tool module.

  import listStorageBucketsTool from './tools/list_storage_buckets.js';