内容
# Supabase 管理 MCP 服务器
> **Supabase MCP 服务器** — 用于管理自托管 Supabase 实例的 MCP（模型上下文协议）工具。
>
> 将边缘函数 CRUD、迁移管理、日志监控和 Studio MCP 代理合并为单个端点。
> Vibe 编码。
[](LICENSE)
[](package.json)
[](package.json)
---
## 🚀 功能
| 类别 | 工具数量 | 描述 |
|----------|-----------|-------------|
| **边缘函数** | 6 | CRUD + 部署（列出、查看、创建、更新、删除、重启） |
| **迁移** | 4 | SQL 迁移管理（列出、查看、应用、原始 SQL 执行） |
| **日志** | 2 | Docker 容器日志（边缘运行时 + 任意容器） |
| **Studio 代理** | ~11 | 代理 Supabase Studio 内置的 MCP 工具 |
**总计：12 个管理工具 + ~11 个 Studio 工具 = ~23 个工具**，均在一个 MCP 端点上！
---
## 📦 快速开始
### 1. 克隆和构建
```bash
git clone https://github.com/ubeydtalha/supabase-mgmt-mcp.git
cd supabase-mgmt-mcp
cp .env.example .env
# 在 .env 中填写您的 Supabase 凭证
npm install
npm run build
```
### 2. 运行
```bash
# 直接使用 Node.js
npm start
# 使用 Docker
docker compose up -d
```
### 3. 连接到 VS Code
在 VS Code 中添加以下内容到 `~/.vscode/mcp.json`：
```json
{
"servers": {
"supabase-mgmt": {
"type": "url",
"url": "http://localhost:3200/mcp",
"headers": {
"apikey": "supabase_mgmt_api_key_here",
"MCP-Protocol-Version": "2025-06-18"
}
}
}
}
```
---
## 🛠️ 工具参考
### 边缘函数
| 工具 | 描述 |
|------|-------------|
| `supabase_mgmt_list_functions` | 列出所有边缘函数 |
| `supabase_mgmt_get_function` | 显示函数源代码和详细信息 |
| `supabase_mgmt_create_function` | 创建新的边缘函数 |
| `supabase_mgmt_update_function` | 更新函数源代码 / JWT 设置 |
| `supabase_mgmt_delete_function` | 删除函数（需要 `confirm: true`） |
| `supabase_mgmt_deploy` | 重启边缘运行时（激活更改） |
### 迁移和 SQL
| 工具 | 描述 |
|------|-------------|
| `supabase_mgmt_list_migrations` | 列出迁移文件 |
| `supabase_mgmt_get_migration` | 查看迁移 SQL 内容 |
| `supabase_mgmt_apply_migration` | 应用迁移文件 |
| `supabase_mgmt_run_sql` | 执行原始 SQL |
### 日志
| 工具 | 描述 |
|------|-------------|
| `supabase_mgmt_get_logs` | 获取边缘运行时日志 |
| `supabase_mgmt_get_container_logs` | 获取任意 Docker 容器的日志 |
### Studio 代理（可选，启用时需要设置 STUDIO_MCP_URL）
| 工具 | 描述 |
|------|-------------|
| `list_tables` | 列出数据库表 |
| `list_extensions` | 列出扩展 |
| `execute_sql` | 执行 SQL 查询 |
| `apply_migration` | 应用迁移 |
| `get_logs` | 获取 Supabase 服务日志 |
| `search_docs` | 搜索 Supabase 文档 |
| `get_advisors` | 获取性能/安全建议 |
| `get_project_url` | 显示项目 URL |
| `get_publishable_keys` | 显示 API 密钥 |
| `generate_typescript_types` | 生成 TypeScript 类型定义 |
| `list_migrations` | 列出迁移 |
---
## 🔧 环境变量
| 变量 | 是否必填 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `PORT` | 否 | `3200` | 服务器端口 |
| `SUPABASE_URL` | **是** | — | Supabase 项目 URL（例如 `https://supabase.example.com`） |
| `SUPABASE_SERVICE_ROLE_KEY` | **是** | — | 服务角色密钥（用于管理员操作） |
| `SUPABASE_MGMT_API_KEY` | **是** | — | 连接到 MCP 服务器的 API 密钥 |
| `SUPABASE_MGMT_API_KEYS` | 否 | — | 其他 API 密钥（逗号分隔） |
| `FUNCTIONS_PATH` | 否 | `/functions` | 边缘函数文件路径 |
| `MIGRATIONS_PATH` | 否 | `/migrations` | 迁移 SQL 文件路径 |
| `EDGE_CONTAINER_NAME` | 否 | `supabase-functions` | 边缘运行时 Docker 容器名称 |
| `STUDIO_MCP_URL` | 否 | — | 启用 Studio MCP 代理 |
---
## 🐳 Docker 部署
### 与自托管 Supabase 集成
```yaml
# docker-compose.yml（添加到您的堆栈中）
services:
supabase-mgmt-mcp:
image: ghcr.io/ubeydtalha/supabase-mgmt-mcp:latest
container_name: supabase-mgmt-mcp
restart: unless-stopped
ports:
- "3200:3200"
env_file: .env
volumes:
- /path/to/functions:/functions
- /path/to/migrations:/migrations
- /var/run/docker.sock:/var/run/docker.sock:ro
networks:
- supabase
```
### 与 Kong API 网关集成
```yaml
# 添加到 Kong 声明性配置
services:
- name: supabase-mgmt-mcp
url: http://supabase-mgmt-mcp:3200/mcp
routes:
- name: mcp
strip_path: false
paths:
- /mcp
```
---
## ⚠️ 重要注意事项
1. **会话管理**：MCP StreamableHTTP 传输期望每个 `tools/call` 使用 **新会话**。VS Code Copilot 自动处理此问题。
2. **exec_sql 先决条件**：`exec_sql` 函数必须存在于 PostgreSQL 中，才能使用 `apply_migration` 和 `run_sql` 工具：
```sql
CREATE OR REPLACE FUNCTION public.exec_sql(sql_text text)
RETURNS void LANGUAGE plpgsql SECURITY DEFINER SET search_path = public AS $$
BEGIN EXECUTE sql_text; END; $$;
GRANT EXECUTE ON FUNCTION public.exec_sql(text) TO anon, authenticated, service_role;
```
3. **Docker 套接字**：必须挂载 `/var/run/docker.sock` 以获取容器日志和重启边缘运行时。
4. **激活更改**：创建/更新/删除函数后，运行 `supabase_mgmt_deploy` 以应用更改。
---
## 📚 文档
- [设置指南](docs/SETUP.md) — 详细的设置说明
- [架构](docs/ARCHITECTURE.md) — 系统架构和设计决策
- [使用示例](docs/USAGE.md) — Copilot Chat 使用场景
---
## 📄 许可证
MIT 许可证 — 请参阅 [LICENSE](LICENSE)。
---
## 🤝 贡献
欢迎 PR 和问题。请先为重大更改打开问题。
