Supabase MCP 服务器

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

特征

• 使用过滤、分页和排序功能从 Supabase 表中读取记录

• 在 Supabase 表中创建新记录（单个或批量）

• 根据过滤条件更新现有记录

• 根据过滤条件从表中删除记录

• 使用 MCP 的 Stdio 传输进行通信

Related MCP server: Supabase MCP Server

先决条件

• Python 3.8 或更高版本

• 已设置表的 Supabase 项目

• Supabase 服务角色密钥用于身份验证

安装

1. 克隆此存储库：

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

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

   # Create a virtual environment
   python -m venv venv
   
   # Activate the virtual environment
   # On Windows:
   venv\Scripts\activate
   # On macOS/Linux:
   source venv/bin/activate

3. 安装依赖项：

   pip install -r requirements.txt

4. 设置环境变量：

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

     cp .env.example .env
     # On Windows, use:
     # 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 的客户端集成。例如，您可以将其与支持 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": {
    // ... other servers
    "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",  // or "venv\\Scripts\\python.exe" on Windows
      "args": [
        "/path/to/your/supabase-mcp/server.py"
      ]
    }
  }
}

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

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

工具描述

该服务器提供以下工具：

1. 读取记录

使用灵活的查询选项从 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. 创建记录

在 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. 更新记录

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

参数：

• table （字符串，必需）：要更新记录的表的名称

• updates （对象，必需）：要更新为键值对的字段

• filters （对象，必需）：用于识别要更新的记录的过滤条件

例子：

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

4. 删除记录

根据过滤条件从 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 请求。