内容
# Supabase MCP Server
一个模型上下文协议（Model Context Protocol，MCP）服务器，允许Claude和其他大型语言模型（LLMs）与Supabase交互，以在Postgres表上执行CRUD操作。
## 功能
- 数据库操作：
- 使用过滤器查询数据
- 插入数据
- 更新数据
- 删除数据
- 列出表格
## 先决条件
- Node.js (v16 或更高版本)
- npm 或 yarn
- Supabase 项目及其 API 密钥
## 安装
### 选项 1：从 npm 安装（推荐）
该包已发布在 npm 上！您可以通过以下命令全局安装：
```bash
npm install -g supabase-mcp
```
或者在您的项目中本地安装：
```bash
npm install supabase-mcp
```
### 选项 2：克隆仓库
```bash
git clone https://github.com/Cappahccino/SB-MCP.git
cd SB-MCP
npm install
npm run build
```
## 配置
创建一个 `.env` 文件，并填写你的 Supabase 凭据：
```
# Supabase 凭证
SUPABASE_URL=你的_supabase_项目_url
SUPABASE_ANON_KEY=你的_supabase_匿名_key
SUPABASE_SERVICE_ROLE_KEY=你的_supabase_服务角色_key
# MCP 服务器配置
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=localhost
MCP_API_KEY=your_secret_api_key
```
## 与Claude的使用
Claude需要特定的传输模式以确保兼容性。此软件包提供了一个专门的二进制文件用于Claude集成：
### 在Claude桌面MCP配置中
```json
"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之外进行测试，可以运行：
```bash
npm run start:claude
```
或者如果已全局安装：
```bash
supabase-mcp-claude
```
## 作为独立服务器的使用
全局安装后：
```bash
supabase-mcp
```
这将启动MCP服务器，地址为 http://localhost:3000（或您在 .env 文件中指定的端口）。
## 在您的代码中的使用
您还可以在自己的 Node.js 项目中将 supabase-mcp 作为库使用：
```javascript
import { createServer, mcpConfig, validateConfig } from 'supabase-mcp';
// 验证配置
validateConfig();
// 创建服务器
const app = createServer();
// 启动服务器
app.listen(mcpConfig.port, mcpConfig.host, () => {
console.log(`Supabase MCP 服务器运行在 http://${mcpConfig.host}:${mcpConfig.port}`);
});
```
## 故障排除
### 常见问题及解决方案
#### 1. "端口 XXXX 已在使用中"
HTTP 服务器尝试自动查找可用端口。您可以通过更改 `.env` 文件中的 `MCP_SERVER_PORT` 值手动指定其他端口。
#### 2. "缺少必需的环境变量"
确保您有一个正确的 `.env` 文件，其中包含所有必需的值，或者您已经在系统中设置了环境变量。
#### 3. "TypeError: Class constructor Server cannot be invoked without 'new'"
如果您看到此错误，您可能正在使用旧版本的包。请更新到最新版本：
```bash
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, 可选): 以逗号分隔的列名列表（默认值："*"）
- `query` (object, 可选): 过滤条件
2. **insertData**
- 参数：
- `table` (string): 表名
- `data` (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
MCP 市场
