内容
# 阿里云RDS Supabase MCP服务器
适用于运行在阿里云RDS上的Supabase实例的MCP（模型上下文协议）服务器。使Claude等AI助手能够与托管在阿里云基础设施上的Supabase实例进行交互。
本项目改编自[HenkDz](https://github.com/HenkDz)的原始作品，现由阿里云RDS维护。
## 阿里云操作
该服务器专为运行在阿里云RDS AI上的Supabase实例而设计。主要功能：
- 自动从阿里云开放API获取Supabase凭证
- 只需要阿里云访问密钥（AK）和秘密密钥（SK）
- 支持多个Supabase实例，交互式选择
- 无需手动配置`anon-key`、`service-key`或`jwt-secret`
## 功能
该服务器为运行在阿里云RDS上的Supabase实例提供了丰富的交互工具：
* **阿里云管理**（仅阿里云模式）
* `list_aliyun_supabase_instances`：列出阿里云RDS AI中的所有Supabase实例。
* `connect_to_supabase_instance`：按名称连接特定的Supabase实例。
* `get_current_supabase_instance`：显示当前连接的实例。
* `disconnect_supabase_instance`：断开与当前实例的连接。
* **数据库模式**
* `list_tables`：列出`public`模式中的所有表。
* `list_extensions`：列出已安装的PostgreSQL扩展。
* `get_database_connections`：检索当前数据库连接信息。
* `get_database_stats`：获取数据库统计信息（例如表大小）。
* **迁移和SQL**
* `list_migrations`：列出`supabase_migrations`模式中已应用的迁移。
* `apply_migration`：通过RPC应用新的SQL迁移。
* `execute_sql`：执行任意SQL（需要数据库中的辅助函数或直接数据库访问）。
* `install_execute_sql_function`：在数据库中安装`execute_sql` RPC函数。
* `generate_typescript_types`：从数据库模式生成TypeScript类型。
* **项目配置**
* `get_project_url`：返回配置的Supabase项目URL。
* `get_anon_key`：返回配置的Supabase匿名密钥。
* `get_service_key`：返回配置的Supabase服务角色密钥（如果提供）。
* `verify_jwt_secret`：验证提供的JWT秘密是否与数据库匹配（需要直接数据库访问）。
* **基础设施**
* `rebuild_hooks`：尝试重启`pg_net`工作进程（如果使用）。
* **身份验证用户管理**
* `list_auth_users`：列出`auth.users`中的用户。
* `get_auth_user`：检索特定用户的详细信息。
* `create_auth_user`：使用Supabase管理员API创建新用户。
* `delete_auth_user`：使用Supabase管理员API删除用户。
* `update_auth_user`：使用Supabase管理员API更新用户详细信息。
* **存储洞察**
* `list_storage_buckets`：列出所有存储桶。
* `list_storage_objects`：列出特定存储桶中的对象。
* **实时检查**
* `list_realtime_publications`：列出PostgreSQL发布（通常为`supabase_realtime`）。
* **文档**
* `search_docs`：使用GraphQL查询搜索Supabase官方文档。
* **RAG代理工具**（当设置`--enable-rag-agent`时）
* 所有RAG代理工具都动态加载并以`rag_`前缀（例如`rag_check_health`、`rag_list_datasets`、`rag_get_dataset`、`rag_query_dataset`、`rag_query_multi_datasets`）。
* 这些工具为语义搜索和文档管理提供检索增强生成能力。
* 连接到阿里云模式中的Supabase实例后可用。
*(注意：`get_logs`最初计划但由于在上游自托管环境中观察到的实现复杂性而被跳过)。*
## 工作原理
该MCP服务器与Claude Desktop、Cursor等AI助手工具配合使用。一旦配置完成，这些AI助手就可以自动使用此服务器提供的工具与您的阿里云RDS托管的Supabase实例进行交互。
例如，当您向AI助手询问“列出我的数据库中的所有表”时，它将：
1. 识别需要使用数据库工具
2. 调用此服务器的`list_tables`工具
3. 对您的Supabase实例执行该工具
4. 以人类可读的格式呈现结果
## 身份验证模式和权限级别
服务器支持三种身份验证模式，自动工具过滤：
- **模式1 – 阿里云多实例（身份验证模式`aliyun`，权限`full`）**
使用`--aliyun-ak`、`--aliyun-sk`和`--aliyun-region`发现和管理多个阿里云RDS Supabase实例。授予所有工具的访问权限，包括阿里云管理工具。
- **模式2 – 单实例管理员（身份验证模式`admin`，权限`admin`）**
使用`--supabase-url`、`--supabase-anon-key`和`--supabase-service-role-key`进行单个项目。仅管理员工具可用；阿里云管理工具被隐藏。
- **模式3 – 单实例用户（身份验证模式`user`，权限`user`）**
使用`--supabase-url`、`--supabase-anon-key`，以及`--supabase-user-email`和`--supabase-user-password`。在用户的RLS范围内运行；管理员工具和阿里云管理工具被禁用。
工具可见性自动强制：
- **仅阿里云工具**（例如`list_aliyun_supabase_instances`、`connect_to_supabase_instance`、`get_current_supabase_instance`、`disconnect_supabase_instance`）需要`full`权限。
- **仅管理员工具**（身份验证管理、`get_service_key`、`verify_jwt_secret`、`install_execute_sql_function`、`rebuild_hooks`）需要`full`或`admin`权限。
模式选择优先级：如果提供多个配置，服务器优先选择阿里云；如果阿里云不存在且用户凭证完整，则选择用户模式；否则使用管理员模式。当检测到多个模式时，将记录警告。
## 安全模型
该MCP服务器设计用于受信任的本地或受控MCP客户端。根据身份验证模式，它可以访问高特权数据库凭证并在您的Supabase实例上运行SQL。
- 优先使用**单实例用户**模式，当RLS范围访问足够时。
- 仅在受信任的操作员和受信任的MCP客户端下使用**单实例管理员**和**阿里云多实例**模式。
- 不要提交包含阿里云AK/SK、Supabase服务角色密钥、数据库URL、JWT秘密或用户密码的MCP客户端配置文件。
- `execute_sql`、迁移、身份验证管理和帮助函数安装工具可以更改数据或数据库对象。
- 凭证检查工具是管理员范围的，可以为授权的MCP调用者返回配置的密钥。
- 使用`--tools-config`对工具进行白名单，指定部署所需的最小工具集。
## 设置和安装
### 阿里云模式设置
#### 快速入门
```bash
npx @aliyun-rds/supabase-mcp-server \
--aliyun-ak <您的访问密钥ID> \
--aliyun-sk <您的访问密钥秘密> \
--aliyun-region cn-hangzhou
```
**重要**：`--aliyun-region`参数是**必需的**。如果没有它，API将返回空实例列表，即使没有报告错误。常用区域包括：
- `cn-hangzhou`（中国东部1）
- `cn-beijing`（中国北部2）
- `cn-shanghai`（中国东部2）
- `cn-shenzhen`（中国南部1）
CLI标志定义自动发现的默认区域。当您需要检查其他区域的实例时，请调用`list_aliyun_supabase_instances`工具，并提供其可选的`region_id`参数（例如`cn-beijing`）以覆盖该请求的默认区域。
#### Claude Desktop配置
添加到您的`claude_desktop_config.json`：
```json
{
"mcpServers": {
"aliyun-supabase": {
"command": "npx",
"args": [
"@aliyun-rds/supabase-mcp-server",
"--aliyun-ak", "<您的访问密钥ID>",
"--aliyun-sk", "<您的访问密钥秘密>",
"--aliyun-region", "cn-hangzhou"
]
}
}
}
```
**启用RAG代理集成：**
```json
{
"mcpServers": {
"aliyun-supabase": {
"command": "npx",
"args": [
"@aliyun-rds/supabase-mcp-server",
"--aliyun-ak", "<您的访问密钥ID>",
"--aliyun-sk", "<您的访问密钥秘密>",
"--aliyun-region", "cn-hangzhou",
"--enable-rag-agent"
]
}
}
}
```
或使用环境变量：
```json
{
"mcpServers": {
"aliyun-supabase": {
"command": "npx",
"args": [
"@aliyun-rds/supabase-mcp-server",
"--enable-rag-agent"
],
"env": {
"ALIYUN_ACCESS_KEY_ID": "<您的访问密钥ID>",
"ALIYUN_ACCESS_KEY_SECRET": "<您的访问密钥秘密>",
"ALIYUN_REGION": "cn-hangzhou"
}
}
}
}
```
#### 使用流程
1. **列出实例**：使用`list_aliyun_supabase_instances`查看所有Supabase实例
2. **连接**：使用`connect_to_supabase_instance`和实例名称
3. **使用工具**：现在可以使用所有Supabase工具（`list_tables`、`execute_sql`等）
4. **断开连接**（可选）：使用`disconnect_supabase_instance`切换实例
### 单实例管理员模式设置
```bash
npx @aliyun-rds/supabase-mcp-server \
--supabase-url https://<您的项目>.supabase.co \
--supabase-anon-key <匿名密钥> \
--supabase-service-role-key <服务角色密钥> \
[--db-url <PostgreSQL连接字符串>] \
[--jwt-secret <JWT秘密>] \
[--enable-rag-agent]
```
环境变量替代：
```bash
SUPABASE_URL=https://<您的项目>.supabase.co \
SUPABASE_ANON_KEY=<匿名密钥> \
SUPABASE_SERVICE_ROLE_KEY=<服务角色密钥> \
supabase-mcp
```
Claude Desktop / Cursor JSON示例：
```json
{
"mcpServers": {
"supabase-admin": {
"command": "npx",
"args": [
"@aliyun-rds/supabase-mcp-server",
"--supabase-url", "https://<您的项目>.supabase.co",
"--supabase-anon-key", "<匿名密钥>",
"--supabase-service-role-key", "<服务角色密钥>"
]
}
}
}
```
### 单实例用户模式设置（RLS限制）
```bash
npx @aliyun-rds/supabase-mcp-server \
--supabase-url https://<您的项目>.supabase.co \
--supabase-anon-key <匿名密钥> \
--supabase-user-email <用户邮箱> \
--supabase-user-password <用户密码> \
[--enable-rag-agent]
```
环境变量替代：
```bash
SUPABASE_URL=https://<您的项目>.supabase.co \
SUPABASE_ANON_KEY=<匿名密钥> \
SUPABASE_USER_EMAIL=<用户邮箱> \
SUPABASE_USER_PASSWORD=<用户密码> \
supabase-mcp
```
Claude Desktop / Cursor JSON示例：
```json
{
"mcpServers": {
"supabase-user": {
"command": "npx",
"args": [
"@aliyun-rds/supabase-mcp-server",
"--supabase-url", "https://<您的项目>.supabase.co",
"--supabase-anon-key", "<匿名密钥>",
"--supabase-user-email", "<用户邮箱>",
"--supabase-user-password", "<用户密码>"
]
}
}
}
```
### 其他安装选项
#### 全局安装
```bash
npm install -g @aliyun-rds/supabase-mcp-server
supabase-mcp \
--aliyun-ak <您的访问密钥ID> \
--aliyun-sk <您的访问密钥秘密> \
--aliyun-region cn-hangzhou
```
## 配置
选择一种配置路径。CLI标志覆盖环境变量。
### 模式1 — 阿里云多实例（权限：full）
必需：
- `--aliyun-ak <密钥>`或`ALIYUN_ACCESS_KEY_ID=<密钥>`
- `--aliyun-sk <秘密>`或`ALIYUN_ACCESS_KEY_SECRET=<秘密>`
- `--aliyun-region <区域>`或`ALIYUN_REGION=<区域>`（例如`cn-hangzhou`、`cn-beijing`；必需用于发现）
行为：为选定的实例从阿里云拉取Supabase URL/密钥/数据库URL/JWT秘密。
### 模式2 — 单实例管理员（权限：admin）
必需：
- `--supabase-url <URL>`或`SUPABASE_URL`
- `--supabase-anon-key <密钥>`或`SUPABASE_ANON_KEY`
- `--supabase-service-role-key <密钥>`或`SUPABASE_SERVICE_ROLE_KEY`
可选：
- `--db-url <PostgreSQL连接字符串>`或`DB_URL`
- `--jwt-secret <秘密>`或`JWT_SECRET`
旧标志别名仍然被接受：`--url`、`--anon-key`、`--service-key`、`--db-url`、`--jwt-secret`。
### 模式3 — 单实例用户（权限：user，RLS强制）
必需：
- `--supabase-url <URL>`或`SUPABASE_URL`
- `--supabase-anon-key <密钥>`或`SUPABASE_ANON_KEY`
- `--supabase-user-email <邮箱>`或`SUPABASE_USER_EMAIL`
- `--supabase-user-password <密码>`或`SUPABASE_USER_PASSWORD`
行为：在提供用户的RLS策略下运行；管理员工具和阿里云管理工具被过滤掉。
### 常用选项
- `--tools-config <路径>`：指定启用哪些工具的JSON文件（白名单）。格式：`{"enabledTools": ["工具名称1", "工具名称2"]}`。
- `--enable-rag-agent`或`ENABLE_RAG_AGENT=true`：启用RAG代理MCP集成。启用后，服务器在选择阿里云RDS Supabase实例后自动连接到RAG代理MCP服务器。
- `--workspace-path <路径>`：文件操作的根目录（可选）。
### RAG 代理集成
该服务器可以与[rag-agent-mcp](https://pypi.org/project/rag-agent-mcp/)集成，提供RAG（检索增强生成）功能以及Supabase数据库工具。
**工作原理：
- 当设置`--enable-rag-agent`时，服务器在您选择阿里云RDS Supabase实例后自动连接到RAG代理MCP服务器。
- Supabase主机/端口从阿里云OpenAPI返回的实例元数据中导出。
- 连接实例检索的匿名密钥作为RAG代理的API密钥重复使用（无需手动密钥共享）。
- 所有RAG代理工具都以`rag_`前缀命名，以避免命名冲突（例如`rag_create_collection`、`rag_add_documents`、`rag_query`）。
**示例配置：**
```bash
npx @aliyun-rds/supabase-mcp-server \
--aliyun-ak <您的访问密钥ID> \
--aliyun-sk <您的访问密钥秘密> \
--aliyun-region cn-hangzhou \
--enable-rag-agent
```
**要求：
- 您的系统必须安装`uvx`
- 必须通过`uvx`提供`rag-agent-mcp`包
- RAG代理服务必须在Supabase实例报告的主机/端口上可访问
**行为说明：
- RAG代理工具在启动时被宣传，但在调用`connect_to_supabase_instance`之前保持功能完整。
- 切换实例会自动使用新的主机/端口重新初始化RAG代理连接。
- 所有RAG代理工具都以前缀`rag_`命名（例如`rag_create_collection`、`rag_add_documents`、`rag_query`）。
### 重要说明：
* **`execute_sql`辅助函数：** 许多工具依赖于RPC的`public.execute_sql`函数。对于SQL执行，通过RPC，在您连接到阿里云RDS实例后，服务器检查此函数，如果您的AK/SK授予所需的特权，它会自动创建并分配最小特权权限。将其视为管理员功能。
* **直接数据库访问：** 涉及特权模式（`auth`、`storage`）或`pg_catalog`的工具仍然需要直接数据库连接。连接字符串由阿里云拉取；确保您的凭证可以检索它，否则这些工具将不可用。
* **数据库URL特殊字符：** 当阿里云返回包含`#`或`$`等字符的数据库URL时，服务器会自动对它们进行URL编码（`#` → `%23`，`$` → `%24`）。`@`符号保持不变，因为它将凭证与主机名分开。
## 与AI助手工具一起使用
### 游标
1. 在项目根目录中创建或打开文件`.cursor/mcp.json`。
2. 根据身份验证模式添加以下配置之一：
**模式1（阿里云多实例，权限：full）**
授予所有工具的访问权限，包括阿里云管理。
```json
{
"mcpServers": {
"aliyun-supabase": {
"command": "npx",
"args": [
"@aliyun-rds/supabase-mcp-server",
"--aliyun-ak", "<您的访问密钥ID>",
"--aliyun-sk", "<您的访问密钥秘密>",
"--aliyun-region", "cn-hangzhou",
"--enable-rag-agent"
],
"env": {
// 可选：工具白名单或切换功能
"TOOLS_CONFIG": "<path-to-tools-config.json>",
"ENABLE_RAG_AGENT": "true"
}
}
}
}
```
**模式2（单实例管理员，权限：admin）**
可用管理员工具；隐藏阿里云管理工具。
```json
{
"mcpServers": {
"supabase-admin": {
"command": "npx",
"args": [
"@aliyun-rds/supabase-mcp-server",
"--supabase-url", "https://<您的项目>.supabase.co",
"--supabase-anon-key", "<匿名密钥>",
"--supabase-service-role-key", "<服务角色密钥>",
"--enable-rag-agent"
]
}
}
}
```
**模式3（单实例用户，权限：user，RLS强制）**
在用户RLS下运行；禁用管理员/阿里云工具。
```json
{
"mcpServers": {
"supabase-user": {
"command": "npx",
"args": [
"@aliyun-rds/supabase-mcp-server",
"--supabase-url", "https://<您的项目>.supabase.co",
"--supabase-anon-key", "<匿名密钥>",
"--supabase-user-email", "<用户邮箱>",
"--supabase-user-password", "<用户密码>",
"--enable-rag-agent"
]
}
}
}
```
**RAG代理重要说明：
- RAG代理工具在您调用`connect_to_supabase_instance`并选择阿里云RDS Supabase项目之前保持非活动状态。
- 切换实例会自动使用新的主机/端口重新初始化RAG代理连接。
- 所有RAG代理工具都以前缀`rag_`命名（例如`rag_create_collection`、`rag_add_documents`、`rag_query`）。
### 克劳德桌面
对于克劳德桌面，打开设置 → 开发者 → 启用“自定义MCP服务器”，然后添加一个与您的模式匹配的配置：
**模式1（阿里云，权限：full）**
```json
{
"name": "阿里云 Supabase",
"command": "npx",
"args": [
"@aliyun-rds/supabase-mcp-server",
"--aliyun-ak", "<您的访问密钥ID>",
"--aliyun-sk", "<您的访问密钥秘密>",
"--aliyun-region", "cn-hangzhou",
"--enable-rag-agent"
]
}
```
**模式2（单实例管理员，权限：admin）**
```json
{
"name": "Supabase 管理员",
"command": "npx",
"args": [
"@aliyun-rds/supabase-mcp-server",
"--supabase-url", "https://<您的项目>.supabase.co",
"--supabase-anon-key", "<匿名密钥>",
"--supabase-service-role-key", "<服务角色密钥>",
"--enable-rag-agent"
]
}
```
**模式3（单实例用户，权限：user，RLS强制）**
```json
{
"name": "Supabase 用户",
"command": "npx",
"args": [
"@aliyun-rds/supabase-mcp-server",
"--supabase-url", "https://<您的项目>.supabase.co",
"--supabase-anon-key", "<匿名密钥>",
"--supabase-user-email", "<用户邮箱>",
"--supabase-user-password", "<用户密码>",
"--enable-rag-agent"
]
}
```
### 其他MCP兼容工具
大多数MCP兼容工具都遵循类似的配置模式。一般格式是:
- 命令：`npx`
- 参数：`[@aliyun-rds/supabase-mcp-server, --aliyun-ak, <您的访问密钥ID>, --aliyun-sk, <您的访问密钥秘密>, --aliyun-region, <您的区域>, ...]`
## 许可
本项目根据MIT许可协议授权 - 请参阅 [LICENSE](LICENSE) 文件获取详细信息。
原始开发人员为 [HenkDz](https://github.com/HenkDz)，现由阿里云RDS维护。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器