@aliyun-rds/supabase-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,203 @@
+# Self-Hosted Supabase MCP Server
+
+MCP (Model Context Protocol) server for self-hosted Supabase instances. Allows AI assistants like Claude to interact with your self-hosted Supabase database.
+
+Originally developed by [HenkDz](https://github.com/HenkDz), now maintained by lemontreen.
+
+## Features
+
+This server exposes a rich set of tools for interacting with your self-hosted Supabase instance:
+
+*   **Database Schema**
+    *   `list_tables`: Lists all tables in the `public` schema.
+    *   `list_extensions`: Lists installed PostgreSQL extensions.
+    *   `get_database_connections`: Retrieves current database connection information.
+    *   `get_database_stats`: Gets database statistics (e.g., table sizes).
+*   **Migrations & SQL**
+    *   `list_migrations`: Lists applied migrations from the `supabase_migrations` schema.
+    *   `apply_migration`: Applies a new SQL migration (Requires direct DB access).
+    *   `execute_sql`: Executes arbitrary SQL (Requires helper function in DB or direct DB access).
+    *   `generate_typescript_types`: Generates TypeScript types from the database schema.
+*   **Project Configuration**
+    *   `get_project_url`: Returns the configured Supabase project URL.
+    *   `get_anon_key`: Returns the configured Supabase Anon Key.
+    *   `get_service_key`: Returns the configured Supabase Service Role Key (if provided).
+    *   `verify_jwt_secret`: Verifies the provided JWT secret against the database (Requires direct DB access).
+*   **Infrastructure**
+    *   `rebuild_hooks`: Attempts to restart the `pg_net` worker (if used).
+*   **Auth User Management**
+    *   `list_auth_users`: Lists users from `auth.users`.
+    *   `get_auth_user`: Retrieves details for a specific user.
+    *   `create_auth_user`: Creates a new user (Requires direct DB access, insecure password handling).
+    *   `delete_auth_user`: Deletes a user (Requires direct DB access).
+    *   `update_auth_user`: Updates user details (Requires direct DB access, insecure password handling).
+*   **Storage Insights**
+    *   `list_storage_buckets`: Lists all storage buckets.
+    *   `list_storage_objects`: Lists objects within a specific bucket.
+*   **Realtime Inspection**
+    *   `list_realtime_publications`: Lists PostgreSQL publications (often `supabase_realtime`).
+
+*(Note: `get_logs` was initially planned but skipped due to implementation complexities in a self-hosted environment).*
+
+## How It Works
+
+This MCP server works with AI assistant tools like Claude Desktop, Cursor, and other MCP-compatible applications. Once configured, these AI assistants can automatically use the tools provided by this server to interact with your self-hosted Supabase instance.
+
+For example, when you ask an AI assistant "List all tables in my database", it will:
+1. Recognize it needs to use a database tool
+2. Call the `list_tables` tool from this server
+3. Execute the tool against your Supabase instance
+4. Present the results in a human-readable format
+
+## Setup and Installation
+
+### Method 1: Using npx (Recommended)
+
+The easiest way to use this server is via npx, which requires no installation:
+
+```bash
+npx @lemontreen/rds-supabase-mcp-server --url http://localhost:8000 --anon-key YOUR_ANON_KEY
+```
+
+### Method 2: Installing via Smithery
+
+To install Self-Hosted Supabase MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@HenkDz/selfhosted-supabase-mcp):
+
+```bash
+npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude
+```
+
+### Method 3: Global Installation
+
+Install the package globally:
+
+```bash
+npm install -g @lemontreen/rds-supabase-mcp-server
+supabase-mcp --url http://localhost:8000 --anon-key YOUR_ANON_KEY
+```
+
+### Method 4: Local Installation and Build
+
+If you want to build from source:
+
+#### Prerequisites
+
+*   Node.js (Version 18.x or later recommended)
+*   npm (usually included with Node.js)
+*   Access to your self-hosted Supabase instance (URL, keys, potentially direct DB connection string).
+
+#### Steps
+
+1.  **Clone the repository:**
+    ```bash
+    git clone <repository-url>
+    cd selfhosted-supabase-mcp
+    ```
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+3.  **Build the project:**
+    ```bash
+    npm run build
+    ```
+    This compiles the TypeScript code to JavaScript in the `dist` directory.
+
+## Configuration
+
+The server requires configuration details for your Supabase instance. These can be provided via command-line arguments or environment variables. CLI arguments take precedence.
+
+**Required:**
+
+*   `--url <url>` or `SUPABASE_URL=<url>`: The main HTTP URL of your Supabase project (e.g., `http://localhost:8000`).
+*   `--anon-key <key>` or `SUPABASE_ANON_KEY=<key>`: Your Supabase project's anonymous key.
+
+**Optional (but Recommended/Required for certain tools):**
+
+*   `--service-key <key>` or `SUPABASE_SERVICE_ROLE_KEY=<key>`: Your Supabase project's service role key. Needed for operations requiring elevated privileges, like attempting to automatically create the `execute_sql` helper function if it doesn't exist.
+*   `--db-url <url>` or `DATABASE_URL=<url>`: The direct PostgreSQL connection string for your Supabase database (e.g., `postgresql://postgres:password@localhost:5432/postgres`). Required for tools needing direct database access or transactions (`apply_migration`, Auth tools, Storage tools, querying `pg_catalog`, etc.).
+*   `--jwt-secret <secret>` or `SUPABASE_AUTH_JWT_SECRET=<secret>`: Your Supabase project's JWT secret. Needed for tools like `verify_jwt_secret`.
+*   `--tools-config <path>`: Path to a JSON file specifying which tools to enable (whitelist). If omitted, all tools defined in the server are enabled. The file should have the format `{"enabledTools": ["tool_name_1", "tool_name_2"]}`.
+
+### Important Notes:
+
+*   **`execute_sql` Helper Function:** Many tools rely on a `public.execute_sql` function within your Supabase database for secure and efficient SQL execution via RPC. The server attempts to check for this function on startup. If it's missing *and* a `service-key` (or `SUPABASE_SERVICE_ROLE_KEY`) *and* `db-url` (or `DATABASE_URL`) are provided, it will attempt to create the function and grant necessary permissions. If creation fails or keys aren't provided, tools relying solely on RPC may fail.
+*   **Direct Database Access:** Tools interacting directly with privileged schemas (`auth`, `storage`) or system catalogs (`pg_catalog`) generally require the `DATABASE_URL` to be configured for a direct `pg` connection.
+
+## Using with AI Assistant Tools
+
+### Cursor
+
+1.  Create or open the file `.cursor/mcp.json` in your project root.
+2.  Add the following configuration:
+
+    ```json
+    {
+      "mcpServers": {
+        "selfhosted-supabase": { 
+          "command": "npx",
+          "args": [
+            "@lemontreen/rds-supabase-mcp-server",
+            "--url",
+            "<your-supabase-url>", // e.g., "http://localhost:8000"
+            "--anon-key",
+            "<your-anon-key>",
+            // Optional - Add these if needed by the tools you use
+            "--service-key",
+            "<your-service-key>",
+            "--db-url",
+            "<your-db-url>", // e.g., "postgresql://postgres:password@host:port/postgres"
+            "--jwt-secret",
+            "<your-jwt-secret>",
+            // Optional - Whitelist specific tools
+            "--tools-config",
+            "<path-to-tools-config.json>"
+          ]
+        }
+      }
+    }
+    ```
+
+### Claude for Desktop
+
+For Claude Desktop, you can add the following to your configuration:
+
+1.  Open Claude Desktop Settings
+2.  Go to "Developer" and enable "Custom MCP Servers"
+3.  Add a new server with the following configuration:
+
+    ```json
+    {
+      "name": "Self-Hosted Supabase",
+      "command": "npx",
+      "args": [
+        "@lemontreen/rds-supabase-mcp-server",
+        "--url",
+        "http://localhost:8000",
+        "--anon-key",
+        "YOUR_ANON_KEY_HERE"
+      ]
+    }
+    ```
+
+### Other MCP-Compatible Tools
+
+Most MCP-compatible tools follow similar configuration patterns. The general format is:
+- Command: `npx`
+- Arguments: `[@lemontreen/rds-supabase-mcp-server, --url, YOUR_URL, --anon-key, YOUR_ANON_KEY, ...]`
+
+## Development
+
+To develop and contribute to this project:
+
+1. Clone the repository
+2. Run `npm install`
+3. Make your changes
+4. Run `npm run build` to compile
+5. Test with `node dist/index.js` or directly with an MCP client
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+Originally developed by [HenkDz](https://github.com/HenkDz), now maintained by lemontreen.