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+）
| 类别 | 工具 |
|---|---|
| 数据库 | execute_sql, list_tables, list_table_columns, list_extensions, explain_query |
| 模式 | list_indexes, list_constraints, list_foreign_keys, list_triggers, get_function_definition |
| 迁移 | apply_migration, list_migrations |
| 安全 | list_rls_policies, get_rls_status, get_advisors （安全/性能） |
| 认证 | list_auth_users, get_auth_user, create_auth_user, update_auth_user, delete_auth_user |
| 存储 | list_storage_buckets, list_storage_objects, get_storage_config, update_storage_config |
| 函数 | list_database_functions, get_function_definition, list_edge_functions, get_edge_function_details |
| 监控 | get_logs, get_database_connections, get_database_stats, get_index_stats |
| 矢量 | list_vector_indexes, get_vector_index_stats |
| 克龙 | list_cron_jobs, get_cron_job_history |
| 其他 | get_project_url, verify_jwt_secret, rebuild_hooks, generate_typescript_types |
先决条件
- 自托管Supabase实例（由Coolify、Docker Compose等管理）
- 带有TLS反向代理（Traefik、Nginx、Caddy）的VPS
- 指向您的VPS的DNS记录（Cloudflare推荐）
- 本地计算机上的Node.js 18+（用于Claude Code桥）
环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
SUPABASE_URL | 是 | 您的Supabase项目URL（例如。， https://supabase.yourdomain.com) |
SUPABASE_ANON_KEY | 是 | 提供匿名/可发布密钥（JWT） |
SUPABASE_SERVICE_ROLE_KEY | 是 | 支持服务角色密钥（JWT） |
DATABASE_URL | 是 | 直接PostgreSQL连接字符串 |
PORT | 无 | 服务器端口（默认值： 3000) |
数据库URL
容器必须位于 相同的Docker网络 作为你的Supabase堆栈。使用内部容器主机名 DATABASE_URL:
postgresql://postgres:YOUR_PASSWORD@supabase-db-CONTAINER_ID:5432/postgres使用以下命令查找容器主机名：
docker ps --filter "name=supabase-db" --format "{{.Names}}"部署
选项1：冷却（推荐）
- 从此Git存储库创建新应用程序
- 设置环境变量（见上文）
- 配置域：
mcp-supabase.yourdomain.com - 将暴露端口设置为
3000 - 重要：禁用基本身份验证（如果启用）（它会阻止MCP客户端）
- 部署
选项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端点
| 方法 | 路径 | 描述 |
|---|---|---|
GET | /sse | 上交所认购——回报 event: endpoint 具有会话特定的消息URL |
POST | /message?sessionId=... | 发送JSON-RPC消息（MCP协议） |
GET | /health | 健康检查-退货 ok |
DNS和TLS设置
Cloudflare（推荐）
创建指向您的VPS公共IP的A记录：
| 类型 | 名称 | 内容 | 代理 |
|---|---|---|---|
A. mcp-supabase | YOUR_VPS_IP | 仅DNS （灰云） |
重要：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/sse3.验证
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):
- 打开与网关的SSE连接
- 接收特定会话
/message?sessionId=...端点 - 从stdin读取JSON-RPC消息，将其POST到消息端点
- 通过SSE接收JSON-RPC响应
message事件，将它们写入stdout - 断开连接时自动重新连接
它避免了OAuth发现开销 mcp-remote Claude Code的本地SSE客户端速度慢/不可靠。
故障排除
claude mcp list 显示“连接失败”
原因：Claude Code的SSE客户端在尝试连接之前在OAuth发现上花费了10秒。
修复：使用stdio网桥而不是直接SSE。看 Claude代码配置 上面。
健康端点返回401
原因：反向代理已启用基本身份验证。
修复（冷却）：基本身份验证作为Traefik标签存储在Coolify数据库中。要删除它：
- 检查当前标签：
docker inspect CONTAINER --format '{{json .Config.Labels}}' | grep basic - 移除
basicauthCoolify中Traefik标签生成的中间件docker-compose.yaml - 更新HTTPS路由器
middlewares要排除的标签http-basic-auth-* - 重新创建容器：
docker compose up -d --force-recreate - 更新Coolify的数据库，以便在重新部署时保持更改：
-- In coolify-db container
-- Decode custom_labels, remove basic auth lines, re-encode, UPDATESSE不通过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的情况下公开服务
许可证
麻省理工学院