Supabase MCP 服务器

一个模型上下文协议（MCP）服务器，允许Claude和其他大型语言模型与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 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桌面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服务器。

在代码中使用

你也可以在自己的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: 类构造函数Server不能没有'new'调用"

如果你看到这个错误，可能是正在运行软件包的旧版本。升级到最新版本：

npm install -g supabase-mcp@latest

4. Claude的JSON解析错误

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

5. 与Claude连接超时

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

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

工具参考

数据库工具

queryDatabase
- 参数:
  - table (字符串): 要查询的表名
  - select (字符串, 可选): 逗号分隔的列列表 (默认: "*")
  - query (对象, 可选): 过滤条件
insertData
- 参数:
  - table (字符串): 表名
  - data (对象或对象数组): 要插入的数据
updateData
- 参数:
  - table (字符串): 表名
  - data (对象): 作为键值对更新的数据
  - query (对象): 更新的过滤条件
deleteData
- 参数:
  - table (字符串): 表名
  - query (对象): 删除的过滤条件
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