Supabase MCP Server 🚀

Supabase MCP 服务 🚀

🔥 一个功能强大的模型上下文协议（MCP）服务，可通过 Cursor 的 Composer 和 Codeium 的 Cascade 全面管理 Supabase PostgreSQL 数据库。此工具提供完善的表操作、记录管理、架构修改等功能，让数据库管理变得轻松顺畅。

📚 目录

• 前提条件
• 快速开始
• 集成
• 功能
• 用法
• 安全说明
• 故障排除
• 贡献
• 许可证

🔧 前提条件

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

🚀 快速开始

📥 安装

# Clone the repository
git clone https://github.com/Quegenx/supabase-mcp-server.git
cd supabase-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

⚙️ 配置

1. 安装依赖并构建项目：

   npm install
   npm run build
   

2. 在 Cursor 的 MCP 设置中，使用以下命令添加服务：

   /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 中的 Agentic 大模型提供自定义工具。此服务可集成到 Cursor 的 Composer 功能中，让你通过自然语言命令直接使用所有数据库管理工具。

在 Cursor 中设置

1. 打开 Cursor Settings > Features > MCP

2. 点击“+ Add New MCP Server”按钮

3. 填写弹出表单：

   • 名称：“Supabase MCP”（或使用你喜欢的昵称）
   • 类型：command（stdio 传输）
   • 命令：包含连接详情的完整命令字符串

4. 先构建项目：

   npm install
   npm run build
   

5. 获取 Node.js 路径：

   # On Mac/Linux
   which node
   # On Windows
   where node
   

6. 添加服务命令：

   /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. 点击“Add Server”，然后点击右上角的刷新按钮

在 Cursor 中使用工具

当你描述数据库任务时，Composer Agent 会自动检测并使用相关工具。例如：

• “列出数据库中的所有表”
• “创建一个新的 users 表”
• “为 email 列添加索引”

Agent 使用工具时，你会看到：

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

注意：对于此类 stdio 服务，命令必须是有效的 shell 命令。如果需要使用环境变量，可考虑编写包装脚本。

Windsurf/Cascade 集成

此 MCP 服务还支持 Codeium 的 Cascade（Windsurf）集成。请注意，此功能目前仅面向付费个人用户开放（不适用于 Teams 或 Enterprise 用户）。

在 Cascade 中设置

1. 创建或编辑 ~/.codeium/windsurf/mcp_config.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 输入框上方的工具栏
   • 点击锤子图标
   • 点击“Configure”以打开 mcp_config.json

3. 在配置中替换：

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

4. 在 Cascade 中：

   • 点击工具栏中的锤子图标
   • 点击“Configure”以验证设置
   • 点击“Refresh”以加载 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/                    # Compiled JavaScript files
│   ├── index.d.ts          # TypeScript declarations
│   └── index.js            # Main JavaScript file
├── src/                    # Source code
│   └── index.ts           # Main TypeScript file
├── package.json           # Project configuration
├── package-lock.json      # Dependency lock file
└── tsconfig.json         # TypeScript configuration

💡 使用方法

配置完成后，MCP 服务会通过 Cursor 的 Composer 提供所有数据库管理工具。只需描述你想对数据库执行的操作，AI 就会使用相应的命令。

示例：

• 📋 “显示数据库中的所有表”
• ➕ “创建一个新的 users 表，包含 id、name 和 email 列”
• 🔍 “在 users 表的 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，以查看详细日志：

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

平台特定说明

Windows 用户

# Use this format for the command
"C:\\Program Files\\nodejs\\node.exe" "C:\\path\\to\\dist\\index.js" "postgresql://..."

Linux 用户

# Find Node.js path
which node

# Make script executable
chmod +x /path/to/dist/index.js

如果问题仍然存在，请提交问题，并提供以下信息：

• 操作系统
• Node.js 版本（node --version）
• 完整错误消息
• 重现步骤

🤝 贡献

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

📄 许可证

---