Supabase MCP 服务器

一个用于与 Supabase 数据库交互的模型上下文协议（MCP）服务器。该服务器使用 FastMCP Python SDK 实现了 Model Context Protocol，为大型语言模型（LLMs）提供数据库操作工具。

功能特性

• 支持过滤、分页和排序的 Supabase 表记录读取
• 在 Supabase 表中创建新记录（单条或批量）
• 基于过滤条件更新现有记录
• 基于过滤条件删除表记录
• 使用 MCP 的 Stdio 传输协议进行通信

前置要求

• Python 3.8 或更高版本
• 已设置好表格的 Supabase 项目
• 用于身份验证的 Supabase 服务角色密钥

安装指南

1. 克隆本仓库：

   bash 复制代码

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

2. 设置虚拟环境（推荐）：

   bash 复制代码

   # 创建虚拟环境
   python -m venv venv
   
   # 激活虚拟环境
   # Windows系统：
   venv\Scripts\activate
   # macOS/Linux系统：
   source venv/bin/activate

3. 安装依赖项：

   bash 复制代码

   pip install -r requirements.txt

4. 配置环境变量：

   • 复制 .env.example 文件为 .env：
     bash 复制代码

     cp .env.example .env
     # Windows系统请使用：
     # copy .env.example .env

   • 在 .env 文件中填写您的 Supabase URL 和服务角色密钥：
     复制代码

     SUPABASE_URL=您的supabase项目url
     SUPABASE_SERVICE_ROLE_KEY=您的supabase服务角色密钥

使用说明

启动服务器

确保虚拟环境已激活，然后运行服务器：

python server.py

服务器使用 Stdio 传输协议，因此将通过标准输入监听 MCP 请求并通过标准输出响应。

与 MCP 客户端集成

该服务器实现了模型上下文协议，可与任何兼容 MCP 的客户端集成。例如，您可以在支持 MCP 工具的 LLM 框架中使用它。

添加到 Windsurf/Cursor MCP 配置

要将此 MCP 服务器添加到您的 Windsurf 或 Cursor 配置中：

1. 找到 mcp_config.json 文件：

   • Windows: C:\Users\<用户名>\.codeium\windsurf\mcp_config.json
   • macOS: ~/.codeium/windsurf/mcp_config.json
   • Linux: ~/.codeium/windsurf/mcp_config.json

2. 在 mcpServers 部分添加 Supabase MCP 服务器：

{
  "mcpServers": {
    // ... 其他服务器
    "supabase": {
      "command": "python",
      "args": [
        "/您的/supabase-mcp/server.py路径"
      ],
      "env": {
        "SUPABASE_URL": "您的supabase_url",
        "SUPABASE_SERVICE_ROLE_KEY": "您的supabase密钥"
      }
    }
  }
}

将 /您的/supabase-mcp/server.py路径 替换为 server.py 文件的绝对路径。

注意：为了更好的隔离性，可以使用虚拟环境中的 Python 可执行文件：

{
  "mcpServers": {
    "supabase": {
      "command": "/您的/venv/bin/python路径",  // Windows系统使用："venv\\Scripts\\python.exe"
      "args": [
        "/您的/supabase-mcp/server.py路径"
      ]
    }
  }
}

3. 重启您的 Windsurf/Cursor 应用以应用更改。

4. Supabase MCP 工具现在将可供您的 AI 助手使用。

工具说明

服务器提供以下工具：

1. read_records

从 Supabase 数据库表中读取记录，支持灵活的查询选项。

参数：

• table (字符串, 必填)：要读取的表名
• columns (字符串, 可选, 默认："*")：要选择的列（逗号分隔或 * 表示所有列）
• filters (对象, 可选)：作为键值对的过滤条件
• limit (整数, 可选)：返回的最大记录数
• offset (整数, 可选)：分页跳过的记录数
• order_by (对象, 可选)：作为列:方向对的排序选项

示例：

{
  "table": "users",
  "columns": "id,name,email",
  "filters": {"is_active": true},
  "limit": 10,
  "offset": 0,
  "order_by": {"created_at": "desc"}
}

2. create_records

在 Supabase 数据库表中创建一条或多条记录。

参数：

• table (字符串, 必填)：要创建记录的表名
• records (对象或数组, 必填)：要创建的单个记录对象或记录对象数组

示例（单条记录）：

{
  "table": "users",
  "records": {
    "name": "张三",
    "email": "zhangsan@example.com",
    "role": "user"
  }
}

示例（多条记录）：

{
  "table": "users",
  "records": [
    {
      "name": "张三",
      "email": "zhangsan@example.com",
      "role": "user"
    },
    {
      "name": "李四",
      "email": "lisi@example.com",
      "role": "admin"
    }
  ]
}

3. update_records

基于过滤条件更新 Supabase 数据库表中的现有记录。

参数：

• table (字符串, 必填)：要更新记录的表名
• updates (对象, 必填)：作为键值对的要更新字段
• filters (对象, 必填)：用于识别要更新记录的过滤条件

示例：

{
  "table": "users",
  "updates": {
    "is_verified": true,
    "last_login_at": "2025-04-04T15:30:00Z"
  },
  "filters": {
    "id": 123
  }
}

4. delete_records

基于过滤条件从 Supabase 数据库表中删除记录。

参数：

• table (字符串, 必填)：要删除记录的表名
• filters (对象, 必填)：用于识别要删除记录的过滤条件

示例：

{
  "table": "expired_sessions",
  "filters": {
    "expires_at": {"lt": "2025-01-01T00:00:00Z"}
  }
}

开发指南

项目结构

• server.py：主 MCP 服务器实现
• supabase_client.py：Supabase 客户端包装器
• requirements.txt：Python 依赖项
• .env.example：示例环境变量文件

添加新工具

要向服务器添加新工具：

1. 在 server.py 中为工具请求参数定义 Pydantic 模型
2. 向 SupabaseMCPServer 类添加处理方法
3. 在 _register_tools 方法中注册工具，并提供描述性名称和文档

许可证

MIT 许可证

贡献指南

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