Supabase MCP 服务器 🚀

🔥 一个强大的模型上下文协议（MCP）服务器，通过Cursor的Composer和Codeium的Cascade提供对您的Supabase PostgreSQL数据库的完全管理控制。此工具支持无缝数据库管理，包括表操作、记录管理、模式修改等功能。

📚 目录

• 先决条件
• 快速开始
• 集成
• 功能
• 使用方法
• 安全注意事项
• 故障排除
• 贡献
• 许可证

🔧 先决条件

• Node.js >= 16.x
• npm >= 8.x
• 一个包含以下信息的Supabase项目：
  • 项目ID
  • 数据库密码
  • PostgreSQL连接字符串
• Cursor IDE 或 Codeium 的 Cascade（付费用户）

🚀 快速开始

📥 安装

bash

克隆仓库

git clone https://github.com/Quegenx/supabase-mcp-server.git
cd supabase-mcp-server

安装依赖

npm install

构建项目

npm run build

⚙️ 配置

1. 安装依赖并构建项目：
   bash
   npm install
   npm run build

2. 在Cursor的MCP设置中，使用以下命令添加服务器：
   bash
   /opt/homebrew/bin/node /path/to/dist/index.js postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres

   替换：

   • /path/to/dist/index.js 为实际路径
   • [PROJECT-ID] 为您的Supabase项目ID
   • [PASSWORD] 为您的数据库密码

注意：请确保您的数据库凭据安全，并且不要将其提交到版本控制系统中。

🎯 集成

Cursor MCP 集成

模型上下文协议（MCP）允许您向Cursor中的代理LLM提供自定义工具。此服务器可以与Cursor的Composer功能集成，通过自然语言命令直接访问所有数据库管理工具。

在Cursor中设置

1. 打开Cursor设置 > 功能 > MCP

2. 点击“+ 添加新的MCP服务器”按钮

3. 填写模态表单：

   • 名称：“Supabase MCP”（或您喜欢的任何昵称）
   • 类型：command（stdio传输）
   • 命令：带有连接详细信息的完整命令字符串

4. 首先构建项目：
   bash
   npm install
   npm run build

5. 获取您的Node.js路径：
   bash

   在Mac/Linux上

   which node

   在Windows上

   where node

6. 添加服务器命令：
   bash
   /path/to/node /path/to/dist/index.js postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres

   替换：

   • /path/to/node 为您的实际Node.js路径（从步骤5获取）
   • /path/to/dist/index.js 为您的实际JavaScript文件路径
   • [PROJECT-ID] 为您的Supabase项目ID
   • [PASSWORD] 为您的数据库密码

7. 点击“添加服务器”，然后点击右上角的刷新按钮

在Cursor中使用工具Composer 代理会在您描述数据库任务时自动检测并使用相关工具。例如：

• "列出我数据库中的所有表"
• "创建一个新的用户表"
• "为电子邮件列添加索引"

当代理使用某个工具时，您会看到：

1. 一个提示以批准/拒绝工具调用
2. 工具调用参数（可展开）
3. 批准后的响应

注意：对于像这样的 stdio 服务器，命令应为有效的 shell 命令。如果您需要环境变量，请考虑使用包装脚本。

Windsurf/Cascade 集成

此 MCP 服务器还支持 Codeium 的 Cascade (Windsurf) 集成。请注意，此功能目前仅对付费个人用户可用（不适用于团队或企业用户）。

使用 Cascade 设置

1. 创建或编辑 ~/.codeium/windsurf/mcp_config.json:
   json
   {
   "mcpServers": {
   "supabase-mcp": {
   "command": "/path/to/node",
   "args": [
   "/path/to/dist/index.js",
   "postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres"
   ]
   }
   }
   }

2. 快速访问配置：

   • 在 Cascade 输入框上方找到工具栏
   • 点击锤子图标
   • 点击“配置”以打开 mcp_config.json

3. 在配置中替换：

   • 将 /path/to/node 替换为您的实际 Node.js 路径
   • 将 /path/to/dist/index.js 替换为您的实际路径
   • 将 [PROJECT-ID] 替换为您的 Supabase 项目 ID
   • 将 [PASSWORD] 替换为您的数据库密码

4. 在 Cascade 中：

   • 点击工具栏中的锤子图标
   • 点击“配置”以验证您的设置
   • 点击“刷新”以加载 MCP 服务器
   • 点击服务器名称以查看可用工具

对于 Cascade 用户的重要注意事项

• 仅支持工具功能（不支持提示或资源）
• 不论成功或失败，MCP 工具调用都会消耗积分
• 不支持图像输出
• 仅支持 stdio 传输类型
• 工具调用可以调用任意服务器实现者编写的代码
• Cascade 不对 MCP 工具调用失败承担责任

✨ 功能

🎯 可用的数据库工具

表管理

• 表：list_tables, create_table, drop_table, rename_table
• 列：add_column, drop_column, alter_column
• 记录：fetch_records, create_record, update_record, delete_record

索引与约束

• 索引：list_indexes, create_index, delete_index, update_index
• 约束：list_constraints, add_constraint, remove_constraint, update_constraint

数据库函数与触发器

• 函数：list_functions, create_function, update_function, delete_function
• 触发器：list_triggers, create_trigger, update_trigger, delete_trigger

安全与访问控制

• 策略：list_policies, create_policy, update_policy, delete_policy
• 角色：list_roles, create_role, update_role, delete_role

存储管理

• 桶：list_buckets, create_bucket, delete_bucket
• 文件：delete_file, bulk_delete_files
• 文件夹：list_folders

数据类型与发布

• 枚举类型：list_enumerated_types, create_enumerated_type, update_enumerated_type, delete_enumerated_type
• 发布：list_publications, create_publication, update_publication, delete_publication

实时功能

• 策略：list_realtime_policies, create_realtime_policy, update_realtime_policy, delete_realtime_policy
• 通道：list_realtime_channels, manage_realtime_channels, send_realtime_message, get_realtime_messages
• 管理：manage_realtime_status, manage_realtime_views

用户管理

• 认证：list_users, create_user, update_user, delete_user

直接 SQL 访问

• 查询：query - 执行自定义 SQL 查询

🚀 主要优势

• 自然语言控制：通过简单的对话命令管理您的 Supabase 数据库- 全面覆盖：提供涵盖表、记录、索引、函数、安全等的全套工具
• 无缝集成：直接在Cursor的Composer和Codeium的Cascade中工作
• 开发者友好：减少IDE与数据库管理工具之间的上下文切换
• 安全访问：通过适当的认证保持数据库的安全性

📁 项目结构

supabase-mcp-server/
├── dist/ # 编译后的JavaScript文件
│ ├── index.d.ts # TypeScript声明文件
│ └── index.js # 主JavaScript文件
├── src/ # 源代码
│ └── index.ts # 主TypeScript文件
├── package.json # 项目配置
├── package-lock.json # 依赖锁定文件
└── tsconfig.json # TypeScript配置

💡 使用方法

配置完成后，MCP服务器将通过Cursor的Composer提供所有数据库管理工具。只需描述您想对数据库进行的操作，AI将使用适当的命令执行。

示例：

• 📋 "显示我数据库中的所有表"
• ➕ "创建一个包含id、name和email列的新用户表"
• 🔍 "在用户表的email列上添加索引"

🔒 安全注意事项

• 🔐 确保您的数据库连接字符串安全
• ⚠️ 切勿将敏感凭据提交到版本控制
• 👮 使用适当的访问控制和权限
• 🛡️ 验证并清理所有输入以防止SQL注入

🛠️ 故障排除

常见连接问题

1. Node.js路径问题

   • 确保您使用的是正确的Node.js路径
   • 在Mac/Linux上：使用which node找到正确路径
   • 在Windows上：使用where node找到正确路径
   • 将/usr/local/bin/node替换为您的实际Node.js路径

2. 文件路径问题

   • 使用绝对路径而不是相对路径
   • 在Mac/Linux上：在项目目录中使用pwd获取完整路径
   • 在Windows上：使用cd获取完整路径
   • 示例：/Users/username/projects/supabase-mcp-server/dist/index.js

3. MCP未检测到工具

   • 单击Cursor的MCP设置中的刷新按钮
   • 确保服务器正在运行（无错误消息）
   • 检查您的连接字符串是否正确
   • 验证您的Supabase凭据是否有效

4. 权限问题

   • 确保dist目录存在（运行npm run build）
   • 检查文件权限（在Unix系统上使用chmod +x）
   • 使用适当权限运行npm install

调试模式

在命令前添加DEBUG=true以查看详细日志：

bash
DEBUG=true /usr/local/bin/node /path/to/dist/index.js [connection-string]

平台特定说明

Windows用户

bash

使用以下格式的命令

"C:\Program Files\nodejs\node.exe" "C:\path\to\dist\index.js" "postgresql://..."

Linux用户

bash

查找Node.js路径

which node

使脚本可执行

chmod +x /path/to/dist/index.js

如果您仍然遇到问题，请打开一个问题，并附上以下信息：

• 您的操作系统
• Node.js版本 (node --version)
• 完整的错误消息
• 复现步骤

🤝 贡献

欢迎贡献！请随时提交Pull Request。

📄 许可证

---