Supabase MCP 服务器
模型上下文协议 (MCP) 服务器，提供与 Supabase 数据库、存储和边缘函数交互的全面工具。该服务器支持 Supabase 服务与兼容 MCP 的应用程序之间的无缝集成。
概述
Supabase MCP 服务器充当 MCP 客户端和 Supabase 服务套件之间的桥梁，提供：
- 具有丰富查询功能的数据库操作
- 文件和资产的存储管理
- 边缘函数调用
- 项目和组织管理
- 用户身份验证和管理
- 基于角色的访问控制
建筑学
该服务器使用 TypeScript 构建并遵循模块化架构：
supabase-server/
├── src/
│ ├── index.ts # Main server implementation
│ └── types/
│ └── supabase.d.ts # Type definitions
├── package.json
├── tsconfig.json
├── config.json.example # Example configuration file
└── .env.example # Environment variables template
关键组件
- 服务器类：实现 MCP 服务器接口并处理所有客户端请求
- 类型定义：所有操作的综合 TypeScript 定义
- 环境配置：通过环境变量进行安全配置管理
- 错误处理：强大的错误处理功能，提供详细的错误消息
先决条件
- Node.js 16.x 或更高版本
- Supabase 项目包括：
- 项目网址
- 服务角色密钥（用于管理操作）
- 访问令牌（用于管理操作）
- MCP 兼容客户端
安装
通过 Smithery 安装
要通过Smithery自动为 Claude Desktop 安装 Supabase Server：
npx -y @smithery/cli install supabase-server --client claude
- 克隆存储库：
git clone https://github.com/DynamicEndpoints/supabase-mcp.git
cd supabase-mcp
- 安装依赖项：
- 创建环境配置：
- 配置环境变量：
SUPABASE_URL=your_project_url_here
SUPABASE_KEY=your_service_role_key_here
SUPABASE_ACCESS_TOKEN=your_access_token_here # Required for management operations
- 创建服务器配置：
cp config.json.example config.json
- 构建服务器：
配置
该服务器支持通过环境变量和 config.json 文件进行广泛的配置。以下是配置选项的详细分类：
服务器配置
{
"server": {
"name": "supabase-server", // Server name
"version": "0.1.0", // Server version
"port": 3000, // Port number (if running standalone)
"host": "localhost" // Host address (if running standalone)
}
}
Supabase 配置
{
"supabase": {
"project": {
"url": "your_project_url",
"key": "your_service_role_key",
"accessToken": "your_access_token"
},
"storage": {
"defaultBucket": "public", // Default storage bucket
"maxFileSize": 52428800, // Max file size in bytes (50MB)
"allowedMimeTypes": [ // Allowed file types
"image/*",
"application/pdf",
"text/*"
]
},
"database": {
"maxConnections": 10, // Max DB connections
"timeout": 30000, // Query timeout in ms
"ssl": true // SSL connection
},
"auth": {
"autoConfirmUsers": false, // Auto-confirm new users
"disableSignup": false, // Disable public signups
"jwt": {
"expiresIn": "1h", // Token expiration
"algorithm": "HS256" // JWT algorithm
}
}
}
}
日志配置
{
"logging": {
"level": "info", // Log level
"format": "json", // Log format
"outputs": ["console", "file"], // Output destinations
"file": {
"path": "logs/server.log", // Log file path
"maxSize": "10m", // Max file size
"maxFiles": 5 // Max number of files
}
}
}
安全配置
{
"security": {
"cors": {
"enabled": true,
"origins": ["*"],
"methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
"allowedHeaders": ["Content-Type", "Authorization"]
},
"rateLimit": {
"enabled": true,
"windowMs": 900000, // 15 minutes
"max": 100 // Max requests per window
}
}
}
监控配置
{
"monitoring": {
"enabled": true,
"metrics": {
"collect": true,
"interval": 60000 // Collection interval in ms
},
"health": {
"enabled": true,
"path": "/health" // Health check endpoint
}
}
}
请参阅config.json.example以获取完整的示例配置文件。
MCP 集成
将服务器添加到您的 MCP 设置（cline_mcp_settings.json）：
{
"mcpServers": {
"supabase": {
"command": "node",
"args": ["path/to/supabase-server/build/index.js"],
"env": {
"SUPABASE_URL": "your_project_url",
"SUPABASE_KEY": "your_service_role_key",
"SUPABASE_ACCESS_TOKEN": "your_access_token"
},
"config": "path/to/config.json" // Optional: path to configuration file
}
}
}
可用工具
数据库操作
创建记录
在表中创建新记录并支持返回特定字段。
{
table: string;
data: Record<string, any>;
returning?: string[];
}
例子：
{
table: "users",
data: {
name: "John Doe",
email: "john@example.com"
},
returning: ["id", "created_at"]
}
读取记录
使用高级过滤、连接和字段选择读取记录。
{
table: string;
select?: string[];
filter?: Record<string, any>;
joins?: Array<{
type?: 'inner' | 'left' | 'right' | 'full';
table: string;
on: string;
}>;
}
例子：
{
table: "posts",
select: ["id", "title", "user.name"],
filter: { published: true },
joins: [{
type: "left",
table: "users",
on: "posts.user_id=users.id"
}]
}
更新记录
使用过滤和返回功能更新记录。
{
table: string;
data: Record<string, any>;
filter?: Record<string, any>;
returning?: string[];
}
例子：
{
table: "users",
data: { status: "active" },
filter: { email: "john@example.com" },
returning: ["id", "status", "updated_at"]
}
删除记录
删除具有过滤和返回功能的记录。
{
table: string;
filter?: Record<string, any>;
returning?: string[];
}
例子：
{
table: "posts",
filter: { status: "draft" },
returning: ["id", "title"]
}
存储操作
upload_file
使用可配置选项将文件上传到 Supabase Storage。
{
bucket: string;
path: string;
file: File | Blob;
options?: {
cacheControl?: string;
contentType?: string;
upsert?: boolean;
};
}
例子：
{
bucket: "avatars",
path: "users/123/profile.jpg",
file: imageBlob,
options: {
contentType: "image/jpeg",
upsert: true
}
}
下载文件
从 Supabase Storage 下载文件。
{
bucket: string;
path: string;
}
例子：
{
bucket: "documents",
path: "reports/annual-2023.pdf"
}
边函数
调用函数
使用参数和自定义选项调用 Supabase Edge 函数。
{
function: string;
params?: Record<string, any>;
options?: {
headers?: Record<string, string>;
responseType?: 'json' | 'text' | 'arraybuffer';
};
}
例子：
{
function: "process-image",
params: {
url: "https://example.com/image.jpg",
width: 800
},
options: {
responseType: "json"
}
}
用户管理
列出用户
列出支持分页的用户。
{
page?: number;
per_page?: number;
}
创建用户
使用元数据创建新用户。
{
email: string;
password: string;
data?: Record<string, any>;
}
更新用户
更新用户详细信息。
{
user_id: string;
email?: string;
password?: string;
data?: Record<string, any>;
}
删除用户
删除用户。
分配用户角色
为用户分配角色。
{
user_id: string;
role: string;
}
删除用户角色
删除用户的角色。
{
user_id: string;
role: string;
}
错误处理
服务器提供了常见场景的详细错误信息：
- 参数无效
- 身份验证失败
- 权限问题
- 速率限制
- 网络错误
- 数据库约束
错误以标准格式返回：
{
code: ErrorCode;
message: string;
details?: any;
}
发展
运行测试
建筑
代码检查
运行评估
evals 包会加载一个 mcp 客户端，然后运行 index.ts 文件，因此测试之间无需重新构建。您可以通过在 npx 命令前添加前缀来加载环境变量。完整文档可在此处找到。
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts
贡献
- 分叉存储库
- 创建功能分支
- 提交你的更改
- 推送到分支
- 创建拉取请求
执照
MIT 许可证 - 详情请参阅许可证
支持
如需支持，请：
- 检查问题是否存在问题/解决方案
- 创建新问题并附上详细的复现步骤
- 包括相关的错误消息和环境详细信息