Supabase MCP Gateway

Supabase MCP网关

将您的自托管Supabase公开为Claude Code、Claude.ai和其他MCP客户端的MCP服务器。

建筑

┌──────────────────────────────────────────────────────────────┐
│  Claude Code (local machine)                                 │
│  └── mcp-sse-bridge.mjs (stdio ↔ SSE)                       │
│          ↓ HTTPS                                             │
├──────────────────────────────────────────────────────────────┤
│  Cloudflare DNS (DNS only — no proxy)                        │
│  mcp-supabase.yourdomain.com → VPS public IP                 │
│          ↓                                                   │
├──────────────────────────────────────────────────────────────┤
│  VPS                                                         │
│  ├── Traefik (TLS termination, Let's Encrypt)                │
│  │       ↓ HTTP                                              │
│  ├── Supergateway (this container, port 3000)                │
│  │   ├── GET  /sse      → SSE subscription                  │
│  │   ├── POST /message  → JSON-RPC messages                 │
│  │   └── GET  /health   → health check                      │
│  │       ↓ stdio                                             │
│  └── selfhosted-supabase-mcp                                 │
│          ↓ PostgreSQL                                        │
│      Supabase Database                                       │
└──────────────────────────────────────────────────────────────┘

可用工具（41+）

先决条件

• 自托管Supabase实例（由Coolify、Docker Compose等管理）
• 带有TLS反向代理（Traefik、Nginx、Caddy）的VPS
• 指向您的VPS的DNS记录（Cloudflare推荐）
• 本地计算机上的Node.js 18+（用于Claude Code桥）

环境变量

数据库URL

容器必须位于 相同的Docker网络 作为你的Supabase堆栈。使用内部容器主机名 DATABASE_URL:

postgresql://postgres:YOUR_PASSWORD@supabase-db-CONTAINER_ID:5432/postgres

使用以下命令查找容器主机名：

docker ps --filter "name=supabase-db" --format "{{.Names}}"

部署

选项1：冷却（推荐）

1. 从此Git存储库创建新应用程序
2. 设置环境变量（见上文）
3. 配置域： mcp-supabase.yourdomain.com
4. 将暴露端口设置为 3000
5. 重要：禁用基本身份验证（如果启用）（它会阻止MCP客户端）
6. 部署

选项2：Docker编写

services:
  supabase-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      SUPABASE_URL: https://supabase.yourdomain.com
      SUPABASE_ANON_KEY: eyJ...
      SUPABASE_SERVICE_ROLE_KEY: eyJ...
      DATABASE_URL: postgresql://postgres:PASSWORD@supabase-db:5432/postgres
    networks:
      - your-supabase-network

networks:
  your-supabase-network:
    external: true

选项3:Docker运行

docker build -t supabase-mcp-gateway .
docker run -d \
  --name supabase-mcp \
  --network your-supabase-network \
  -p 3000:3000 \
  -e SUPABASE_URL=https://supabase.yourdomain.com \
  -e SUPABASE_ANON_KEY=eyJ... \
  -e SUPABASE_SERVICE_ROLE_KEY=eyJ... \
  -e DATABASE_URL=postgresql://postgres:PASSWORD@supabase-db:5432/postgres \
  supabase-mcp-gateway

端点

DNS和TLS设置

Cloudflare（推荐）

创建指向您的VPS公共IP的A记录：

重要：Cloudflare代理（橙色云） 必须禁用Cloudflare缓冲服务器发送的事件，这会中断MCP所需的SSE流。

传输层安全

关闭Cloudflare代理后，您的反向代理将处理TLS：

• 交通：使用 certresolver=letsencrypt （Coolify会自动进行配置）
• Nginx：使用certbot
• 卡迪：自动HTTPS

客户端配置

克劳德代码

Claude Code的内置SSE客户端有一个已知的问题：它在连接之前执行10秒的OAuth发现探测，这会导致未实现OAuth的服务器超时。

解决方案：使用附带的stdio到SSE桥接脚本。

1.安装桥架

# Copy the bridge script to your Claude config directory
cp mcp-sse-bridge.mjs ~/.claude/mcp-sse-bridge.mjs

或创建 ~/.claude/mcp-sse-bridge.mjs 使用此存储库中的内容。

2.配置克劳德代码

claude mcp add supabase-vps -s user -- \
  node ~/.claude/mcp-sse-bridge.mjs \
  https://mcp-supabase.yourdomain.com/sse

3.验证

claude mcp list
# Should show: supabase-vps: ... - ✓ Connected

备选方案：项目级配置

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "supabase-vps": {
      "command": "node",
      "args": [
        "/path/to/.claude/mcp-sse-bridge.mjs",
        "https://mcp-supabase.yourdomain.com/sse"
      ]
    }
  }
}

Claude.ai（桌面/网络）

添加为具有SSE传输的MCP服务器：

URL: https://mcp-supabase.yourdomain.com/sse

其他MCP客户端

任何支持SSE传输的MCP客户端都可以直接连接：

SSE endpoint: https://mcp-supabase.yourdomain.com/sse
Message endpoint: https://mcp-supabase.yourdomain.com/message

这座桥是如何工作的

Claude Code ←→ stdio ←→ mcp-sse-bridge.mjs ←→ HTTPS/SSE ←→ Supergateway ←→ stdio ←→ selfhosted-supabase-mcp

桥(mcp-sse-bridge.mjs):

1. 打开与网关的SSE连接
2. 接收特定会话 /message?sessionId=... 端点
3. 从stdin读取JSON-RPC消息，将其POST到消息端点
4. 通过SSE接收JSON-RPC响应 message 事件，将它们写入stdout
5. 断开连接时自动重新连接

它避免了OAuth发现开销 mcp-remote Claude Code的本地SSE客户端速度慢/不可靠。

故障排除

claude mcp list 显示“连接失败”

原因：Claude Code的SSE客户端在尝试连接之前在OAuth发现上花费了10秒。

修复：使用stdio网桥而不是直接SSE。看 Claude代码配置 上面。

健康端点返回401

原因：反向代理已启用基本身份验证。

修复（冷却）：基本身份验证作为Traefik标签存储在Coolify数据库中。要删除它：

1. 检查当前标签： docker inspect CONTAINER --format '{{json .Config.Labels}}' | grep basic
2. 移除 basicauth Coolify中Traefik标签生成的中间件 docker-compose.yaml
3. 更新HTTPS路由器 middlewares 要排除的标签 http-basic-auth-*
4. 重新创建容器： docker compose up -d --force-recreate
5. 更新Coolify的数据库，以便在重新部署时保持更改：

   -- In coolify-db container
   -- Decode custom_labels, remove basic auth lines, re-encode, UPDATE

SSE不通过Cloudflare返回任何数据

原因：Cloudflare的代理缓冲SSE响应。

修复：将DNS记录设置为 仅DNS （灰色云图标，不是橙色）。SSE流协议要求无缓冲响应。

集装箱碰撞 __require is not a function

原因：MCP服务器是用 --target bun 但运行在Node.js上。

修复：Dockerfile使用 bun build src/index.ts --outdir dist --target node。如果修改构建，请确保 --target node 已设置。

容器无法连接到数据库

原因：容器与Supabase堆栈不在同一个Docker网络上。

修复：确保容器加入正确的网络（例如。， coolify Coolify部署中的网络）。通过以下方式进行验证：

docker exec CONTAINER node -e "
  const { Client } = require('pg');
  const c = new Client({ connectionString: process.env.DATABASE_URL });
  c.connect().then(() => { console.log('OK'); c.end(); }).catch(e => console.error(e.message));
"

mcp-remote 挂起10+秒

原因: mcp-remote 执行OAuth发现（探测+ .well-known/ 查找），然后再连接。初始探测在10秒后超时，因为SSE端点流式传输而不是返回。

修复：使用 mcp-sse-bridge.mjs 相反。它在不到1秒的时间内连接。

安全注意事项

• MCP服务器可以通过服务角色密钥完全访问数据库
• 在网络/反向代理级别限制访问（IP分配、VPN等）
• 桥接脚本通过HTTPS连接——所有流量都是加密的
• 考虑为生产使用添加Traefik级别的身份验证（API密钥头，mTLS）
• 做 不 在没有TLS的情况下公开服务

许可证

麻省理工学院