Supabase MCP 服务器

一个模型上下文协议 (MCP) 服务器，允许 Claude 和其他 LLM 与 Supabase 交互，以对 Postgres 表执行 CRUD 操作。

特性

• 数据库操作：
  • 使用过滤器查询数据
  • 插入数据
  • 更新数据
  • 删除数据
  • 列出表

前提条件

• Node.js (v16 或更高版本)
• npm 或 yarn
• 具有 API 密钥的 Supabase 项目

安装

选项 1：从 npm 安装（推荐）

该软件包已发布在 npm 上！ 您可以使用以下命令全局安装它：

npm install -g supabase-mcp

或者在您的项目中本地安装：

npm install supabase-mcp

选项 2：克隆存储库

git clone https://github.com/Cappahccino/SB-MCP.git
cd SB-MCP
npm install
npm run build

配置

创建一个包含您的 Supabase 凭据的 .env 文件：

# Supabase 凭据
SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# MCP 服务器配置
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=localhost
MCP_API_KEY=your_secret_api_key

与 Claude 一起使用

Claude 需要特定的传输模式才能兼容。 此软件包提供了一个专用于 Claude 集成的二进制文件：

在 Claude Desktop MCP 配置中

"supabase": {
  "command": "npx",
  "args": [
    "-y",
    "supabase-mcp@latest",
    "supabase-mcp-claude"
  ],
  "env": {
    "SUPABASE_URL": "your_supabase_project_url",
    "SUPABASE_ANON_KEY": "your_supabase_anon_key", 
    "SUPABASE_SERVICE_ROLE_KEY": "your_service_role_key",
    "MCP_API_KEY": "your_secret_api_key"
  }
}

确保在配置中设置所需的 环境变量。 Claude 将使用 stdio 传输进行通信。

使用 Claude 二进制文件进行手动测试

对于在 Claude 之外的测试，您可以运行：

npm run start:claude

或者如果全局安装：

supabase-mcp-claude

用作独立服务器

全局安装后：

supabase-mcp

这将在 http://localhost:3000（或您的 .env 文件中指定的端口）启动 MCP 服务器。

在您的代码中使用

您还可以将 supabase-mcp 用作您自己的 Node.js 项目中的库：

import { createServer, mcpConfig, validateConfig } from 'supabase-mcp';

// 验证配置
validateConfig();

// 创建服务器
const app = createServer();

// 启动服务器
app.listen(mcpConfig.port, mcpConfig.host, () => {
  console.log(`Supabase MCP server running at http://${mcpConfig.host}:${mcpConfig.port}`);
});

故障排除

常见问题和解决方案

1. "端口 XXXX 已经被使用"

HTTP 服务器尝试自动查找可用端口。 您可以通过更改 MCP_SERVER_PORT 值在 .env 文件中手动指定不同的端口。

2. "缺少必需的环境变量"

确保您有一个正确的 .env 文件，其中包含所有必需的值，或者您已在系统中设置了环境变量。

3. "TypeError: Class constructor Server cannot be invoked without 'new'"

如果您看到此错误，则可能正在运行旧版本的软件包。 更新到最新版本：

npm install -g supabase-mcp@latest

4. Claude 的 JSON 解析错误

确保您使用的是 Claude 专用二进制文件 (supabase-mcp-claude) 而不是常规 HTTP 服务器 (supabase-mcp)。

5. Claude 请求超时

这通常意味着 Claude 发起了连接，但服务器无法及时响应。 检查：

• 您的 Supabase 凭据是否正确？
• 您的服务器是否已正确设置并正在运行？
• 是否有任何东西阻止连接？

工具参考

数据库工具

1. queryDatabase

   • 参数：
     • table (string): 要查询的表的名称
     • select (string, optional): 以逗号分隔的列列表（默认值：“*”）
     • query (object, optional): 筛选条件

2. insertData

   • 参数：
     • table (string): 表的名称
     • data (object 或 object 数组): 要插入的数据

3. updateData

   • 参数：
     • table (string): 表的名称
     • data (object): 要更新的数据，以键值对形式
     • query (object): 更新的筛选条件

4. deleteData

   • 参数：
     • table (string): 表的名称
     • query (object): 删除的筛选条件

5. listTables

   • 参数：无

版本历史

• 1.0.0：初始版本
• 1.0.1：添加了自动端口选择
• 1.0.2：修复了协议兼容性问题
• 1.0.3：添加了 JSON-RPC 支持
• 1.1.0：使用官方 MCP SDK 完全重写
• 1.2.0：添加了单独的 Claude 传输并修复了端口冲突问题
• 1.3.0：更新以提高与 TypeScript 项目的兼容性
• 1.4.0：根据 Supabase 社区最佳实践修复了 Claude stdio 传输集成
• 1.5.0：删除了 Edge Function 支持，以提高稳定性和专注于数据库操作

许可证

MIT