Supabase MCP Server

Supabase MCP 服务

一个模型上下文协议（MCP）服务，可让 Claude 和其他大模型与 Supabase 交互，对 Postgres 表执行 CRUD 操作。

功能

• 数据库操作：
  • 使用筛选条件查询数据
  • 插入数据
  • 更新数据
  • 删除数据
  • 列出表

前置条件

• Node.js（v16 或更高版本）
• npm 或 yarn
• Supabase 项目及 API 密钥

安装

选项 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

配置

创建一个 .env 文件，填写你的 Supabase 凭据：

# Supabase credentials
SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# MCP server configuration
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

这将启动 MCP 服务，地址为 http://localhost:3000（或 .env 文件中指定的端口）。

在代码中使用

你也可以在自己的 Node.js 项目中将 supabase-mcp 用作库：

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

// Validate configuration
validateConfig();

// Create the server
const app = createServer();

// Start the server
app.listen(mcpConfig.port, mcpConfig.host, () => {
  console.log(`Supabase MCP server running at http://${mcpConfig.host}:${mcpConfig.port}`);
});

故障排除

常见问题及解决方案

1. “端口 XXXX 已被占用”

HTTP 服务会自动尝试查找可用端口。你可以在 .env 文件中更改 MCP_SERVER_PORT 的值，手动指定其他端口。

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（字符串）：要查询的表名
     • select（字符串，可选）：以逗号分隔的列名列表（默认值："*"）
     • query（对象，可选）：筛选条件

2. insertData

   • 参数：
     • table（字符串）：表名
     • data（对象或对象数组）：要插入的数据

3. updateData

   • 参数：
     • table（字符串）：表名
     • data（对象）：要更新的键值对数据
     • query（对象）：更新的筛选条件

4. deleteData

   • 参数：
     • table（字符串）：表名
     • query（对象）：删除的筛选条件

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