mcp-supabase-selfhosted 1.0.0

package/.env.example

@@ -0,0 +1,9 @@
+# URL de tu instancia Self-Hosted de Supabase (ej. http://localhost:8000 o https://api.midominio.com)
+SUPABASE_URL="http://localhost:8000"
+
+# Service Role Key para hacer bypass de RLS (necesario para gestionar usuarios/buckets)
+SUPABASE_SERVICE_ROLE_KEY="tu_service_role_key_aqui"
+
+# URL de conexión directa a PostgreSQL (para queries directas y gestión de tablas)
+# Generalmente: postgresql://postgres:postgres@localhost:5432/postgres
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"

package/.gemini/skills/supabase-selfhosted/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: supabase-selfhosted
+description: Use when you need to interact with a self-hosted Supabase instance to configure Auth, Storage, manage the database schema, apply RLS policies, or debug performance.
+---
+
+# Skill: Supabase Self-Hosted MCP
+
+This skill guides the agent on how to correctly and safely utilize the `supabase-selfhosted` MCP server tools to interact with a self-hosted Supabase environment.
+
+## 1. When to Use
+Activate this skill whenever the user asks to:
+- "Configurar un usuario de prueba en auth."
+- "Crear un bucket para mis imágenes."
+- "Revisar las políticas de seguridad RLS."
+- "Corregir problemas de rendimiento de la base de datos."
+- "Ver qué columnas tiene una tabla en mi Supabase."
+
+## 2. Security and RLS (Row Level Security) Mandates
+**Critical:** Because this MCP uses the `SUPABASE_SERVICE_ROLE_KEY` and direct PostgreSQL connections, **it bypasses Row Level Security (RLS) entirely.**
+- When you create tables or schemas using `execute_sql`, you MUST strongly recommend or automatically apply RLS policies unless explicitly told otherwise.
+- Use `list_rls_policies` to audit existing security rules.
+- If the `get_advisors` tool flags tables without RLS, you should proactively offer to write the SQL to secure them.
+
+## 3. Recommended Workflows
+
+### A. Exploring the Database
+1. Run `list_tables` to see what exists.
+2. Run `get_schema({ table_name: "X" })` to understand the columns before writing any SQL.
+3. Run `get_advisors()` to check if there are missing indexes or security gaps.
+
+### B. Configuring Auth
+1. Use `list_users` to see who is registered.
+2. Use `create_user({ email, password, email_confirm: true })` to bootstrap administrative or test accounts without needing an email SMTP server configured locally.
+3. If asked to clean up, use `delete_user({ user_id })`.
+
+### C. Configuring Storage (Buckets)
+1. Use `list_buckets()` to check existing buckets.
+2. Use `create_bucket({ bucket: "name", public: true/false })` to make a new one. Remember: making a bucket public allows read access without auth, but RLS policies are still recommended via `storage.objects` table.
+3. Use `list_files({ bucket: "name" })` to verify uploads.
+
+### D. Debugging and Infrastructure
+- If the user complains about "Too many connections" or database hanging, immediately run `get_active_connections()` to identify locked processes or long-running queries.
+- Run `get_advisors()` and report the `cache_health` and `unused_indexes` so the user can optimize their self-hosted VPS resources.
+
+## 4. Examples
+
+**Creating a Secure Table with RLS:**
+If asked to create a `posts` table, execute:
+```sql
+CREATE TABLE posts (
+  id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
+  title text,
+  user_id uuid REFERENCES auth.users(id)
+);
+ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+CREATE POLICY "Users can read own posts" ON posts FOR SELECT USING (auth.uid() = user_id);
+```
+*(Always use `execute_sql` with robust SQL strings).*

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,36 @@
+name: Bug report
+description: Create a report to help us improve
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Also tell us what you expected to happen
+      placeholder: Tell us what you see!
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction-steps
+    attributes:
+      label: Steps to reproduce
+      description: How can we reproduce this?
+      placeholder: |
+        1. Setup MCP with ...
+        2. Run tool ...
+        3. See error ...
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Operating System, Node version, Docker version, etc.
+      placeholder: |
+        - OS: Linux/macOS/Windows
+        - Node: v20.x
+        - MCP Client: Cursor/Claude Desktop

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Suggest an idea for this project
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Is your feature request related to a problem?
+      description: A concise description of what the problem is. Ex. I'm always frustrated when [...]
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Describe the solution you'd like
+      description: A concise description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add any other context or screenshots about the feature request here.

package/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run lint
+    - run: npm run build
+    - run: npm test

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2
+}

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-06-01
+
+### Added
+- Initial release of the Supabase Self-Hosted MCP server.
+- Database tools: `list_tables`, `get_schema`, `execute_sql`.
+- Infrastructure tools: `get_advisors`, `get_active_connections`, `list_rls_policies`.
+- Auth tools: `list_users`, `create_user`, `delete_user`.
+- Storage tools: `list_buckets`, `create_bucket`, `delete_bucket`, `list_files`.
+- Docker support with Multi-stage builds.
+- One-command execution support via `npx`.
+- Initial test suite and linting configuration.
+- MIT License and community health files.

package/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to Supabase Self-Hosted MCP
+
+First off, thank you for considering contributing to this project! It's people like you that make the open-source community such a great place to learn, inspire, and create.
+
+## Code of Conduct
+
+By participating in this project, you are expected to uphold our Code of Conduct.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+- Use the [GitHub Bug Report template](.github/ISSUE_TEMPLATE/bug_report.md).
+- Provide a clear and descriptive title.
+- Describe the exact steps which reproduce the problem.
+
+### Suggesting Enhancements
+- Use the [GitHub Feature Request template](.github/ISSUE_TEMPLATE/feature_request.md).
+- Explain why this enhancement would be useful to most users.
+
+### Pull Requests
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. Ensure the test suite passes (`npm test`).
+4. Make sure your code lints (`npm run lint`).
+5. Issue that pull request!
+
+## Styleguide
+
+- Use TypeScript for all logic.
+- Follow the existing Prettier and ESLint configurations.
+- Document new tools in the `README.md` and provide examples in the `SKILL.md` if applicable.
+
+## License
+By contributing, you agree that your contributions will be licensed under its MIT License.

package/Dockerfile

@@ -0,0 +1,36 @@
+# Construcción
+FROM node:20-slim AS builder
+
+WORKDIR /app
+
+# Copiar configuración
+COPY package*.json ./
+COPY tsconfig.json ./
+
+# Instalar dependencias
+RUN npm ci
+
+# Copiar código fuente
+COPY src/ ./src/
+
+# Compilar TypeScript
+RUN npm run build
+
+# Producción
+FROM node:20-slim AS runner
+
+WORKDIR /app
+
+# Copiar archivos compilados y dependencias de producción
+COPY package*.json ./
+RUN npm ci --omit=dev
+
+COPY --from=builder /app/dist ./dist
+
+# Variables de entorno por defecto
+ENV SUPABASE_URL=""
+ENV SUPABASE_SERVICE_ROLE_KEY=""
+ENV DATABASE_URL=""
+
+# Ejecutar usando stdio (por eso no exponemos puertos HTTP)
+ENTRYPOINT ["node", "dist/index.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open Source Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do action so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# Supabase Self-Hosted MCP Server
+
+Un servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) diseñado específicamente para instancias **Self-Hosted de Supabase**. 
+
+A diferencia del servidor MCP oficial que depende en gran medida de las APIs de la nube de Supabase y del `project-ref`, esta versión se conecta directamente a tu base de datos PostgreSQL local y a las APIs locales (Auth/Storage) usando tu `SUPABASE_URL` y tu `SERVICE_ROLE_KEY`.
+
+##  Características
+
+-  **Introspección de Base de Datos:** Lista tablas y esquemas de tu Postgres.
+-  **Ejecución SQL Raw:** Ejecuta consultas SQL directamente, permitiendo a la IA leer datos o modificar la estructura (bypass de RLS).
+-  **Gestión de Autenticación:** Lista usuarios registrados en tu instancia.
+-  **Gestión de Storage:** Lista buckets de almacenamiento.
+
+##  Requisitos
+
+- Node.js >= 18
+- Docker (opcional, pero recomendado)
+
+##  Instalación y Uso (Local)
+
+1. Clona el repositorio:
+   ```bash
+   git clone https://github.com/tu-usuario/mcp-supabase-selfhosted.git
+   cd mcp-supabase-selfhosted
+   ```
+
+2. Instala las dependencias y compila:
+   ```bash
+   npm install
+   npm run build
+   ```
+
+3. Crea tu archivo de entorno:
+   ```bash
+   cp .env.example .env
+   ```
+   Rellena tus credenciales (asegúrate de usar la **Service Role Key**, ¡nunca la anónima!).
+
+##  Uso con Docker (Recomendado)
+
+La forma más limpia de utilizar este servidor en clientes IA (Cursor, Claude, Gemini) sin ensuciar tu entorno local es usar la imagen de Docker.
+
+1. Construye la imagen localmente:
+   ```bash
+   docker build -t supabase-selfhosted-mcp .
+   ```
+
+### Configuración en Claude Desktop / Cursor
+Añade lo siguiente a tu archivo `claude_desktop_config.json` o configuración de Cursor:
+
+```json
+{
+  "mcpServers": {
+    "supabase-selfhosted": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e", "SUPABASE_URL=http://host.docker.internal:8000",
+        "-e", "SUPABASE_SERVICE_ROLE_KEY=tu-clave-aqui",
+        "-e", "DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/postgres",
+        "supabase-selfhosted-mcp"
+      ]
+    }
+  }
+}
+```
+*(Nota: usa `host.docker.internal` en lugar de `localhost` si tu base de datos corre en tu máquina host).*
+
+### Configuración en Gemini CLI
+Puedes añadirlo en tu archivo `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "supabase-selfhosted": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e", "SUPABASE_URL=...",
+        "-e", "SUPABASE_SERVICE_ROLE_KEY=...",
+        "-e", "DATABASE_URL=...",
+        "supabase-selfhosted-mcp"
+      ]
+    }
+  }
+}
+```
+
+##  Seguridad y Buenas Prácticas
+
+- **Acceso Directo:** Este MCP utiliza conexiones directas a DB y la `SERVICE_ROLE_KEY`. Esto significa que la IA conectada tendrá acceso **total y sin restricciones (bypassing RLS)** a tu instancia.
+- **Entornos:** Se recomienda encarecidamente utilizar esto **sólo en entornos de desarrollo local**, nunca apuntando a una base de datos de producción con datos reales sensibles.
+- **Transporte:** El servidor usa `stdio` (entrada/salida estándar), lo cual es el protocolo de seguridad predeterminado en aplicaciones de escritorio como Cursor y Claude.
+
+##  Contribuir
+
+¡Las contribuciones son bienvenidas! Sientete libre de abrir Issues o Pull Requests. Si planeas añadir una herramienta nueva, añádela en el directorio `src/tools/`.
+
+## Licencia
+MIT

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported Versions
+
+Currently, only the latest version of the Supabase Self-Hosted MCP server is supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+We take security seriously. If you discover a security vulnerability within this project, please **do not open a public issue**. Instead, please report it via GitHub's Private Vulnerability Reporting feature or by contacting the maintainers directly.
+
+### Our Commitment
+- We will acknowledge receipt of your report within 48 hours.
+- We will provide an estimated timeframe for a fix.
+- We will notify the community once a patch is available.
+
+### Bypassing RLS Note
+Please note that this MCP server is designed for **administrative and development purposes**. By definition, using a `Service Role Key` bypasses Row Level Security. This is an intended feature of the tool and not considered a vulnerability in itself. However, exposures of credentials or remote execution flaws are critical bugs.

package/dist/config/env.d.ts

@@ -0,0 +1,5 @@
+export declare function getConfig(): {
+    SUPABASE_URL?: string | undefined;
+    SUPABASE_SERVICE_ROLE_KEY?: string | undefined;
+    DATABASE_URL?: string | undefined;
+};

package/dist/config/env.js

@@ -0,0 +1,36 @@
+import dotenv from 'dotenv';
+import { z } from 'zod';
+// Cargar variables de entorno del archivo .env si existe
+dotenv.config();
+// Esquema de validación para las variables de entorno
+const envSchema = z
+    .object({
+    SUPABASE_URL: z.string().url('La URL de Supabase debe ser válida').optional(),
+    SUPABASE_SERVICE_ROLE_KEY: z.string().optional(),
+    DATABASE_URL: z
+        .string()
+        .url('La URL de la base de datos (Postgres) debe ser válida')
+        .optional(),
+})
+    .refine((data) => {
+    // Al menos una de las dos formas de conexión debe estar configurada
+    const hasSupabaseAPI = !!(data.SUPABASE_URL && data.SUPABASE_SERVICE_ROLE_KEY);
+    const hasDBConnection = !!data.DATABASE_URL;
+    return hasSupabaseAPI || hasDBConnection;
+}, {
+    message: 'Debes configurar al menos DATABASE_URL o (SUPABASE_URL y SUPABASE_SERVICE_ROLE_KEY)',
+});
+export function getConfig() {
+    try {
+        const config = envSchema.parse(process.env);
+        return config;
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            console.error(' Error de configuración. Faltan variables de entorno o son inválidas:');
+            error.issues.forEach((e) => console.error(`  - ${e.message}`));
+            process.exit(1);
+        }
+        throw error;
+    }
+}

package/dist/db/postgres.d.ts

@@ -0,0 +1,9 @@
+import { Pool } from 'pg';
+/**
+ * Inicializa y retorna el pool de conexiones de Postgres si DATABASE_URL está configurada.
+ */
+export declare function getDbPool(): Promise<Pool>;
+/**
+ * Ejecuta una query segura usando el pool.
+ */
+export declare function query(sql: string, params?: unknown[]): Promise<any[]>;

package/dist/db/postgres.js

@@ -0,0 +1,50 @@
+import { Pool } from 'pg';
+import { getConfig } from '../config/env.js';
+let pgPool = null;
+/**
+ * Inicializa y retorna el pool de conexiones de Postgres si DATABASE_URL está configurada.
+ */
+export async function getDbPool() {
+    if (pgPool) {
+        return pgPool;
+    }
+    const config = getConfig();
+    if (!config.DATABASE_URL) {
+        throw new Error('DATABASE_URL no está configurada. Las herramientas de base de datos directa no funcionarán.');
+    }
+    pgPool = new Pool({
+        connectionString: config.DATABASE_URL,
+        max: 10, // Límite máximo de conexiones activas para este MCP
+        idleTimeoutMillis: 30000, // Cerrar conexiones inactivas después de 30s
+        connectionTimeoutMillis: 5000, // Abortar intentos de conexión lentos
+        statement_timeout: 10000, // (10s) Abortar consultas pesadas/erróneas generadas por la IA
+    });
+    try {
+        // Verificamos la conexión con una consulta sencilla
+        const client = await pgPool.connect();
+        client.release();
+        console.error(' Conectado exitosamente a PostgreSQL (Pool con timeouts configurados).');
+        return pgPool;
+    }
+    catch (error) {
+        pgPool = null;
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(' Error conectando a PostgreSQL:', msg);
+        throw error;
+    }
+}
+/**
+ * Ejecuta una query segura usando el pool.
+ */
+export async function query(sql, params = []) {
+    const pool = await getDbPool();
+    try {
+        const result = await pool.query(sql, params);
+        return result.rows;
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(' Error ejecutando query:', msg);
+        throw error;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { getConfig } from './config/env.js';
+import { toolsDefinitions, handleExecuteSql, handleListBuckets, handleCreateBucket, handleDeleteBucket, handleListTables, handleListUsers, handleCreateUser, handleDeleteUser, handleGetSchema, handleGetAdvisors, handleListFiles, handleListRlsPolicies, handleGetActiveConnections, } from './tools/index.js';
+async function main() {
+    // 1. Validar la configuración al inicio
+    getConfig();
+    // 2. Inicializar el servidor MCP
+    const server = new Server({
+        name: 'supabase-selfhosted-mcp',
+        version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // 3. Registrar el manejador para listar herramientas (Tools)
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: toolsDefinitions,
+        };
+    });
+    // 4. Registrar el manejador para ejecutar herramientas
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: params } = request.params;
+        switch (name) {
+            case 'get_schema':
+                return await handleGetSchema(params);
+            case 'get_advisors':
+                return await handleGetAdvisors();
+            case 'list_tables':
+                return await handleListTables(params);
+            case 'execute_sql':
+                return await handleExecuteSql(params);
+            case 'list_users':
+                return await handleListUsers(params);
+            case 'create_user':
+                return await handleCreateUser(params);
+            case 'delete_user':
+                return await handleDeleteUser(params);
+            case 'list_buckets':
+                return await handleListBuckets();
+            case 'create_bucket':
+                return await handleCreateBucket(params);
+            case 'delete_bucket':
+                return await handleDeleteBucket(params);
+            case 'list_files':
+                return await handleListFiles(params);
+            case 'list_rls_policies':
+                return await handleListRlsPolicies(params);
+            case 'get_active_connections':
+                return await handleGetActiveConnections();
+            default:
+                throw new Error(`Tool not found: ${name}`);
+        }
+    });
+    // 5. Configurar el transporte stdio (entrada/salida estándar)
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(' Servidor MCP de Supabase Self-Hosted iniciado correctamente.');
+}
+main().catch((error) => {
+    console.error(' Error fatal al iniciar el servidor MCP:', error);
+    process.exit(1);
+});

package/dist/supabase/client.d.ts

@@ -0,0 +1,5 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+/**
+ * Inicializa y retorna el cliente de Supabase (usando la Service Role Key para bypassing de RLS).
+ */
+export declare function getSupabaseClient(): SupabaseClient;

package/dist/supabase/client.js

@@ -0,0 +1,26 @@
+import { createClient } from '@supabase/supabase-js';
+import { getConfig } from '../config/env.js';
+let supabaseClient = null;
+/**
+ * Inicializa y retorna el cliente de Supabase (usando la Service Role Key para bypassing de RLS).
+ */
+export function getSupabaseClient() {
+    if (supabaseClient) {
+        return supabaseClient;
+    }
+    const config = getConfig();
+    if (!config.SUPABASE_URL || !config.SUPABASE_SERVICE_ROLE_KEY) {
+        throw new Error('SUPABASE_URL y SUPABASE_SERVICE_ROLE_KEY son obligatorias para utilizar las herramientas de Auth y Storage.');
+    }
+    // Creamos el cliente usando la service role key.
+    // IMPORTANTE: En el contexto de un MCP (que actúa como un super admin), es seguro
+    // y necesario usar la service role key, pero el usuario debe estar consciente de esto.
+    supabaseClient = createClient(config.SUPABASE_URL, config.SUPABASE_SERVICE_ROLE_KEY, {
+        auth: {
+            autoRefreshToken: false,
+            persistSession: false,
+        },
+    });
+    console.error(' Cliente Supabase API inicializado.');
+    return supabaseClient;
+}