Supabase自托管MCP服务器

自托管Supabase MCP服务器

概述

该项目提供了 模型上下文协议（MCP） 专为与以下对象交互而设计的服务器 自托管的Supabase实例。它弥合了MCP客户端（如IDE扩展）与本地或私有托管的Supabase项目之间的差距，使数据库自检、管理和交互直接从您的开发环境中实现。

该服务器是从头开始构建的，借鉴了官方Supabase云MCP服务器的经验，为自托管用例提供了一个最小、专注的实现。

目的

此服务器的主要目标是使使用自托管Supabase安装的开发人员能够利用基于MCP的工具完成以下任务：

• 查询数据库模式和数据。
• 管理数据库迁移。
• 检查数据库统计信息和连接。
• 管理身份验证用户。
• 与Supabase存储交互。
• 正在生成类型定义。

它避免了与多项目管理和云特定API相关的官方云服务器的复杂性，为单项目、自托管环境提供了简化的体验。

功能（已实现的工具）

工具按权限级别分类：

• 常规的 任何经过身份验证的Supabase JWT都可以访问这些工具(authenticated 或 service_role 角色）。
• 享有特权的 工具需要 service_role JWT（HTTP模式）或直接数据库/服务密钥访问（stdio模式）。

架构和迁移

数据库操作和统计

安全和RLS

项目配置

开发和扩展工具

身份验证用户管理

存储

实时检测

扩展专用工具

边缘功能

关于 supabase_migrations.schema_migrations

这 list_migrations 和 apply_migration 工具依赖于 supabase_migrations.schema_migrations 桌子。这张桌子是 由Supabase CLI创建和管理 --它不是MCP服务器本身的一部分。

如何创建表：

当您使用Supabase CLI初始化或运行迁移时，会自动创建该表：

supabase db push        # pushes local migrations to a remote database
supabase migration up   # applies pending local migration files

如果您从未对数据库运行过Supabase CLI，则该表将不存在 list_migrations 将返回错误。您可以通过以下方式手动创建：

CREATE SCHEMA IF NOT EXISTS supabase_migrations;
CREATE TABLE IF NOT EXISTS supabase_migrations.schema_migrations (
    version text NOT NULL PRIMARY KEY,
    name    text NOT NULL DEFAULT '',
    inserted_at timestamptz NOT NULL DEFAULT now()
);

模式差异与官方Supabase：

Supabase云平台跟踪其他列（例如。 statements, dirty).此MCP服务器使用与Supabase CLI的本地开发工作流兼容的最小模式（版本+名称+inserted_at）。如果您现有的表有额外的列，它们将被忽略。

设置和安装

通过Smithery安装

通过以下方式自动安装克劳德桌面的自托管Supabase MCP服务器 史密瑟里:

npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude

先决条件

• 包子 v1.1或更高版本（替换Node.js/npm——用于运行时和构建）
• 访问您自托管的Supabase实例（URL、密钥和可选的直接PostgreSQL连接字符串）。

步骤

1. 克隆存储库：
   复制

   git clone <repository-url>
   cd selfhosted-supabase-mcp
   

2. 安装依赖项：
   复制

   bun install
   

3. 构建项目：
   复制

   bun run build
   

   这将TypeScript源代码编译为JavaScript dist 目录。

配置

服务器需要您的Supabase实例的配置详细信息。这些可以通过命令行参数或环境变量提供。CLI参数优先。

必修的：

• --url <url> 或 SUPABASE_URL=<url>：您的Supabase项目的主要HTTP URL（例如。， http://localhost:8000).
• --anon-key <key> 或 SUPABASE_ANON_KEY=<key>：您的Supabase项目的匿名密钥。

可选（但某些工具建议/必需）：

• --service-key <key> 或 SUPABASE_SERVICE_ROLE_KEY=<key>：您的Supabase项目的服务角色密钥。特权工具和自动创建 execute_sql 启动时的辅助功能。
• --db-url <url> 或 DATABASE_URL=<url>：Supabase数据库的PostgreSQL直接连接字符串（例如。， postgresql://postgres:password@localhost:5432/postgres).需要直接访问数据库的工具需要(apply_migration、身份验证工具、存储工具、， pg_catalog 查询）。
• --jwt-secret <secret> 或 SUPABASE_AUTH_JWT_SECRET=<secret>：你的Supabase项目的JWT秘密。使用时需要 --transport http 并且需要 verify_jwt_secret 工具。
• --tools-config <path>：指定要启用哪些工具的JSON文件的路径（白名单）。如果省略，则启用所有工具。格式： {"enabledTools": ["tool_name_1", "tool_name_2"]}.

HTTP传输选项（使用时 --transport http):

• --port <number>：HTTP服务器端口（默认值： 3000).
• --host <string>：HTTP服务器主机（默认值： 127.0.0.1).
• --cors-origins <origins>：逗号分隔的允许CORS源列表。默认值仅为localhost。
• --rate-limit-window <ms>：速率限制窗口（毫秒）（默认值： 60000).
• --rate-limit-max <count>：每个速率限制窗口的最大请求数（默认值： 100).
• --request-timeout <ms>：请求超时（毫秒）（默认值： 30000).

重要提示：

• execute_sql 辅助功能： 许多工具依赖于 public.execute_sql Supabase数据库中的函数，用于通过RPC执行SQL。服务器在启动时尝试检查此功能。如果它不见了 和 一 service-key 和 db-url 如果提供了，它将尝试自动创建该功能。如果创建失败或未提供密钥，则仅依赖RPC的工具可能会失败。
• 直接数据库访问： 与特权模式直接交互的工具(auth, storage)或系统目录(pg_catalog)一般要求 DATABASE_URL 待配置。
• 冷却/反向代理部署：
  • 这 DATABASE_URL 必须使用可从MCP服务器进程运行的任何地方访问的内部主机名，而不是面向公共的域。
  • 一 ECONNRESET 启动时出错意味着 DATABASE_URL 无法从服务器的网络上下文访问。
  • 服务器仍将成功启动，所有不需要直接数据库连接的工具将继续正常工作。

安全

HTTP传输（建议用于远程访问）

跑步时 --transport http，服务器强制执行：

• JWT身份验证 在所有 /mcp 使用您的端点 SUPABASE_AUTH_JWT_SECRET.
• 基于权限的访问控制（RBAC） --the role JWT中的声明决定了哪些工具是可访问的：
  • service_role：完全访问（所有工具，包括特权工具）。
  • authenticated：仅限常规工具。
  • anon：没有工具访问权限。
• 速率限制 --每个IP地址的可配置请求速率限制。
• 跨域资源共享 --可配置的允许源列表（默认仅限于本地主机）。
• 安全标头 — X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security等等。
• 请求超时 --可配置超时以防止资源耗尽。

标准运输（当地发展）

标准模式具有 无需认证 --所有工具（包括特权工具）都是可访问的。它仅适用于受信任的本地客户端（例如，在本地计算机上运行的IDE扩展）。使用此模式时，启动时会打印警告。

身份验证用户工具的密码处理

create_auth_user 和 update_auth_user 接受来自MCP客户端的纯文本密码，然后立即用哈希值对其进行哈希运算 bcrypt （通过PostgreSQL pgcrypto 扩展名： crypt($password, gen_salt('bf')))在储存之前 auth.users。纯文本密码从不存储。密码作为查询参数传递（不是插入SQL的字符串），防止SQL注入。

注： 密码在MCP客户端和服务器之间以纯文本形式通过MCP传输。这是MCP协议接口固有的，在这一层是不可避免的。使用带有TLS终止的HTTP传输（例如，在Kong/nginx后面）进行网络保护。

SQL执行安全

MCP服务器中的所有数据库操作都使用参数化查询($1, $2, ...）以防止SQL注入。这 execute_sql 该工具是一个有意的例外——它按设计执行任意SQL（这是该工具的目的）。此工具仅限于 service_role 限制曝光的特权级别。

用法

标准模式（本地MCP客户端）

使用Bun运行服务器，提供必要的配置：

# Using CLI arguments (stdio mode — default)
bun run dist/index.js --url http://localhost:8000 --anon-key <your-anon-key> \
  --db-url postgresql://postgres:password@localhost:5432/postgres \
  --service-key <your-service-key>

# Example with tool whitelisting via config file
bun run dist/index.js --url http://localhost:8000 --anon-key <your-anon-key> \
  --tools-config ./mcp-tools.json

# Or configure using environment variables and run:
# export SUPABASE_URL=http://localhost:8000
# export SUPABASE_ANON_KEY=<your-anon-key>
# export DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres
# export SUPABASE_SERVICE_ROLE_KEY=<your-service-key>
bun run dist/index.js

HTTP模式（Docker/远程访问）

bun run dist/index.js \
  --transport http \
  --port 3100 \
  --host 0.0.0.0 \
  --url http://kong:8000 \
  --anon-key <your-anon-key> \
  --service-key <your-service-key> \
  --jwt-secret <your-jwt-secret> \
  --db-url postgresql://postgres:password@db:5432/postgres

HTTP模式需要 --jwt-secret.全部 /mcp 请求中必须包含有效的Supabase JWT Authorization: Bearer <token> 头球

服务器通过stdio（默认）或HTTP（流式HTTP传输）进行通信，并设计为由MCP客户端应用程序（例如Cursor等IDE扩展）调用。客户端将连接到服务器的stdio流或HTTP端点，以列出和调用可用的工具。

客户端配置示例

下面是如何配置流行的MCP客户端以使用此自托管服务器的示例。

重要提示：

• 替换占位符，如 <your-supabase-url>, <your-anon-key>, <your-db-url>, <path-to-dist/index.js> 等等，用你的实际值。
• 确保已编译服务器文件的路径(dist/index.js)适用于您的系统。
• 请谨慎将敏感密钥直接存储在配置文件中，特别是在进行版本控制的情况下。考虑在客户端支持的情况下使用环境变量或更安全的方法。

光标

1. 创建或打开文件 .cursor/mcp.json 在您的项目根目录中。

2. 添加以下配置：

   复制

   {
     "mcpServers": {
       "selfhosted-supabase": { 
         "command": "bun",
         "args": [
           "run",
           "<path-to-dist/index.js>", // e.g., "/home/user/selfhosted-supabase-mcp/dist/index.js"
           "--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-your-mcp-tools.json>" // e.g., "./mcp-tools.json"
         ]
       }
     }
   }
   

Visual Studio代码（副本）

VS Code Copilot允许使用通过提示输入填充的环境变量，这对密钥来说更安全。

1. 创建或打开文件 .vscode/mcp.json 在您的项目根目录中。

2. 添加以下配置：

   复制

   {
     "inputs": [
       { "type": "promptString", "id": "sh-supabase-url", "description": "Self-Hosted Supabase URL", "default": "http://localhost:8000" },
       { "type": "promptString", "id": "sh-supabase-anon-key", "description": "Self-Hosted Supabase Anon Key", "password": true },
       { "type": "promptString", "id": "sh-supabase-service-key", "description": "Self-Hosted Supabase Service Key (Optional)", "password": true, "required": false },
       { "type": "promptString", "id": "sh-supabase-db-url", "description": "Self-Hosted Supabase DB URL (Optional)", "password": true, "required": false },
       { "type": "promptString", "id": "sh-supabase-jwt-secret", "description": "Self-Hosted Supabase JWT Secret (Optional)", "password": true, "required": false },
       { "type": "promptString", "id": "sh-supabase-server-path", "description": "Path to self-hosted-supabase-mcp/dist/index.js" },
       { "type": "promptString", "id": "sh-supabase-tools-config", "description": "Path to tools config JSON (Optional, e.g., ./mcp-tools.json)", "required": false }
     ],
     "servers": {
       "selfhosted-supabase": {
         "command": "bun",
         "args": [
           "run",
           "${input:sh-supabase-server-path}",
           "--tools-config", "${input:sh-supabase-tools-config}"
          ],
         "env": {
           "SUPABASE_URL": "${input:sh-supabase-url}",
           "SUPABASE_ANON_KEY": "${input:sh-supabase-anon-key}",
           "SUPABASE_SERVICE_ROLE_KEY": "${input:sh-supabase-service-key}",
           "DATABASE_URL": "${input:sh-supabase-db-url}",
           "SUPABASE_AUTH_JWT_SECRET": "${input:sh-supabase-jwt-secret}"
         }
       }
     }
   }
   

3. 当您在代理模式（@workspace）下使用Copilot Chat时，它应该能检测到服务器。首次调用服务器时，系统将提示您输入详细信息（URL、密钥、路径）。

其他客户（Windsurf、Cline、Claude）

调整Cursor或官方Supabase文档中显示的配置结构，替换 command 和 args 随着 bun run 命令和此服务器的参数，类似于Cursor示例：

{
  "mcpServers": {
    "selfhosted-supabase": { 
      "command": "bun",
      "args": [
        "run",
        "<path-to-dist/index.js>", 
        "--url", "<your-supabase-url>", 
        "--anon-key", "<your-anon-key>", 
        "--service-key", "<your-service-key>", 
        "--db-url", "<your-db-url>", 
        "--jwt-secret", "<your-jwt-secret>",
        "--tools-config", "<path-to-your-mcp-tools.json>"
      ]
    }
  }
}

请查阅每个客户的具体文件，了解将 mcp.json 或等效的配置文件。

Docker与自托管Supabase的集成

此MCP服务器可以直接集成到自托管的Suabase Docker Compose堆栈中，从而通过Kong API网关与其他Suabase服务一起使用。

架构概述

当与Docker集成时：

• MCP服务器以HTTP传输模式（非stdio）运行
• 它是通过孔暴露出来的 /mcp/v1/*
• JWT身份验证由MCP服务器本身处理
• 服务器可以直接访问数据库和所有Supabase密钥

设置步骤

1.将MCP服务器添加为Git子模块

从您的Supabase Docker目录：

git submodule add https://github.com/HenkDz/selfhosted-supabase-mcp.git selfhosted-supabase-mcp

2.创建Dockerfile

创建 volumes/mcp/Dockerfile:

# Dockerfile for selfhosted-supabase-mcp HTTP mode
# Multi-stage build using Bun runtime for self-hosted Supabase

FROM oven/bun:1.1-alpine AS builder

WORKDIR /app

# Copy package files from submodule
COPY selfhosted-supabase-mcp/package.json selfhosted-supabase-mcp/bun.lock* ./

# Install dependencies
RUN bun install --frozen-lockfile || bun install

# Copy source code
COPY selfhosted-supabase-mcp/src ./src
COPY selfhosted-supabase-mcp/tsconfig.json ./

# Build the application
RUN bun build src/index.ts --outdir dist --target bun

# Production stage
FROM oven/bun:1.1-alpine AS runner

WORKDIR /app

# Create non-root user for security
RUN addgroup --system --gid 1001 mcp && \
    adduser --system --uid 1001 --ingroup mcp mcp

# Copy built application from builder
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

# Set ownership
RUN chown -R mcp:mcp /app

USER mcp

# Default environment variables
ENV NODE_ENV=production

# Health check
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3100/health || exit 1

# Expose HTTP port
EXPOSE 3100

# Start the MCP server in HTTP mode
CMD ["bun", "run", "dist/index.js"]

3.将MCP服务添加到docker-compose.yml

将此服务定义添加到您的 docker-compose.yml:

## MCP Server - Model Context Protocol for AI integrations
## DISABLED BY DEFAULT - Add 'mcp' to COMPOSE_PROFILES to enable
mcp:
  container_name: ${COMPOSE_PROJECT_NAME:-supabase}-mcp
  profiles:
    - mcp
  build:
    context: .
    dockerfile: ./volumes/mcp/Dockerfile
  restart: unless-stopped
  healthcheck:
    test:
      [
        "CMD",
        "wget",
        "--no-verbose",
        "--tries=1",
        "--spider",
        "http://localhost:3100/health"
      ]
    timeout: 5s
    interval: 10s
    retries: 3
  depends_on:
    db:
      condition: service_healthy
    rest:
      condition: service_started
  environment:
    SUPABASE_URL: http://kong:8000
    SUPABASE_ANON_KEY: ${ANON_KEY}
    SUPABASE_SERVICE_ROLE_KEY: ${SERVICE_ROLE_KEY}
    SUPABASE_AUTH_JWT_SECRET: ${JWT_SECRET}
    DATABASE_URL: postgresql://postgres:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
  command:
    [
      "bun",
      "run",
      "dist/index.js",
      "--transport", "http",
      "--port", "3100",
      "--host", "0.0.0.0",
      "--url", "http://kong:8000",
      "--anon-key", "${ANON_KEY}",
      "--service-key", "${SERVICE_ROLE_KEY}",
      "--jwt-secret", "${JWT_SECRET}",
      "--db-url", "postgresql://postgres:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}"
    ]

4.添加Kong API网关路由

将MCP路由添加到 volumes/api/kong.yml 在 services 章节：

## MCP Server routes - Model Context Protocol for AI integrations
## Authentication is handled by the MCP server itself (JWT validation)
- name: mcp-v1
  _comment: 'MCP Server: /mcp/v1/* -> http://mcp:3100/*'
  url: http://mcp:3100/
  routes:
    - name: mcp-v1-all
      strip_path: true
      paths:
        - /mcp/v1/
  plugins:
    - name: cors
      config:
        origins:
          - "$SITE_URL_PATTERN"
          - "http://localhost:3000"
          - "http://127.0.0.1:3000"
        methods:
          - GET
          - POST
          - DELETE
          - OPTIONS
        headers:
          - Accept
          - Authorization
          - Content-Type
          - X-Client-Info
          - apikey
          - Mcp-Session-Id
        exposed_headers:
          - Mcp-Session-Id
        credentials: true
        max_age: 3600

5.启用MCP服务

MCP服务使用Docker Compose配置文件，因此默认情况下是禁用的。要启用它，请执行以下操作：

选项A：设置 .env 文件：

COMPOSE_PROFILES=mcp

选项B：在运行时启用：

docker compose --profile mcp up -d

访问MCP服务器

运行后，MCP服务器可在以下位置使用：

• 内部（来自其他容器）： http://mcp:3100
• 外部（通过香港）： http://localhost:8000/mcp/v1/

认证

在HTTP模式下运行时，MCP服务器使用配置的验证JWT JWT_SECRET。客户端必须在中包含有效的Supabase JWT Authorization 头球

Authorization: Bearer <supabase-jwt>

JWT的 role 索赔决定访问：

• service_role：完全访问所有工具（常规+特权）
• authenticated：只能使用常规工具
• anon：无工具访问权限

健康检查

MCP服务器公开了一个健康端点：

curl http://localhost:8000/mcp/v1/health

安全注意事项

通过Docker部署时：

1. MCP服务器以非root用户身份运行(mcp:mcp)
2. 对所有工具调用强制执行JWT身份验证
3. 特权工具（如 execute_sql)要求 service_role JWT
4. CORS是通过Kong-adjust origins为您的部署配置的

发展

• 语言： TypeScript
• 构建： bun build （通过 bun run build)
• 运行时间： 包子 v1.1+
• 试运行器： bun test
• 依赖关系： 通过管理 bun (bun.lock)
• 核心库： @supabase/supabase-js, pg （诺埃尔·奥斯特格雷斯）， zod （验证）， commander （CLI参数）， @modelcontextprotocol/sdk （MCP服务器框架）， express, jsonwebtoken.

许可证

该项目根据MIT许可证获得许可。有关详细信息，请参阅LICENSE文件。