Supabase MCP 服务器

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

特性

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

前提条件

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

安装

1. 克隆此存储库：

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

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

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

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 设置环境变量：

   • 将 .env.example 文件复制到 .env：

     cp .env.example .env
     # 在 Windows 上，使用：
     # copy .env.example .env
     

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

     SUPABASE_URL=your_supabase_project_url
     SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
     

用法

启动服务器

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

python server.py

该服务器使用 Stdio 传输，因此它将监听标准输入上的 MCP 请求并在标准输出上响应。

与 MCP 客户端集成

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

添加到 Windsurf/Cursor MCP 配置

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

1. 找到您的 mcp_config.json 文件：

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

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

{
  "mcpServers": {
    // ... 其他服务器
    "supabase": {
      "command": "python",
      "args": [
        "/path/to/your/supabase-mcp/server.py"
      ],
      "env": {
        "SUPABASE_URL": "your_supabase_url",
        "SUPABASE_SERVICE_ROLE_KEY": "your_supabase_key"
      }
    }
  }
}

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

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

{
  "mcpServers": {
    "supabase": {
      "command": "/path/to/your/venv/bin/python",  // 或 Windows 上的 "venv\\Scripts\\python.exe"
      "args": [
        "/path/to/your/supabase-mcp/server.py"
      ]
    }
  }
}

3. 重新启动您的 Windsurf/Cursor 应用程序以应用更改。

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

工具描述

该服务器提供以下工具：

1. read_records

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

参数：

• table (字符串，必需): 要从中读取的表的名称
• columns (字符串，可选，默认值: "*"): 要选择的列（逗号分隔或 * 表示全部）
• filters (对象，可选): 作为键值对的过滤条件
• limit (整数，可选): 要返回的最大记录数
• offset (整数，可选): 要跳过的记录数，用于分页
• order_by (对象，可选): 作为 column:direction 对的排序选项

示例：

{
  "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": "John Doe",
    "email": "john@example.com",
    "role": "user"
  }
}

示例（多个记录）：

{
  "table": "users",
  "records": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "user"
    },
    {
      "name": "Jane Smith",
      "email": "jane@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。