Supabase MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供与 Supabase 数据库、存储和边缘函数交互的全面工具。该服务器实现了 Supabase 服务和 MCP 兼容应用程序之间的无缝集成。

<a href="https://glama.ai/mcp/servers/vwi6nt8i80"><img width="380" height="200" src="https://glama.ai/mcp/servers/vwi6nt8i80/badge" alt="supabase-mcp MCP server" /></a>

概述

Supabase MCP 服务器充当 MCP 客户端和 Supabase 服务套件之间的桥梁，提供：

• 具有丰富查询功能的数据库操作
• 文件和资产的存储管理
• 边缘函数调用
• 项目和组织管理
• 用户身份验证和管理
• 基于角色的访问控制

架构

该服务器使用 TypeScript 构建，并遵循模块化架构：

supabase-server/
├── src/
│   ├── index.ts              # 主要服务器实现
│   └── types/
│       └── supabase.d.ts     # 类型定义
├── package.json
├── tsconfig.json
├── config.json.example       # 示例配置文件
└── .env.example             # 环境变量模板

关键组件

• 服务器类: 实现 MCP 服务器接口并处理所有客户端请求
• 类型定义: 所有操作的全面 TypeScript 定义
• 环境配置: 通过环境变量进行安全配置管理
• 错误处理: 具有详细错误消息的强大错误处理

前提条件

• Node.js 16.x 或更高版本
• 具有以下内容的 Supabase 项目：
  • 项目 URL
  • 服务角色密钥（用于管理操作）
  • 访问令牌（用于管理操作）
• MCP 兼容的客户端

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Supabase Server：

npx -y @smithery/cli install supabase-server --client claude

1. 克隆存储库：

git clone https://github.com/DynamicEndpoints/supabase-mcp.git
cd supabase-mcp

2. 安装依赖项：

npm install

3. 创建环境配置：

cp .env.example .env

4. 配置环境变量：

SUPABASE_URL=your_project_url_here
SUPABASE_KEY=your_service_role_key_here
SUPABASE_ACCESS_TOKEN=your_access_token_here  # 管理操作需要

5. 创建服务器配置：

cp config.json.example config.json

6. 构建服务器：

npm run build

配置

服务器支持通过环境变量和 config.json 文件进行广泛的配置。以下是配置选项的详细分解：

服务器配置

{
  "server": {
    "name": "supabase-server",    // 服务器名称
    "version": "0.1.0",           // 服务器版本
    "port": 3000,                 // 端口号（如果独立运行）
    "host": "localhost"           // 主机地址（如果独立运行）
  }
}

Supabase 配置

{
  "supabase": {
    "project": {
      "url": "your_project_url",
      "key": "your_service_role_key",
      "accessToken": "your_access_token"
    },
    "storage": {
      "defaultBucket": "public",           // 默认存储桶
      "maxFileSize": 52428800,            // 最大文件大小（字节）（50MB）
      "allowedMimeTypes": [               // 允许的文件类型
        "image/*",
        "application/pdf",
        "text/*"
      ]
    },
    "database": {
      "maxConnections": 10,               // 最大数据库连接数
      "timeout": 30000,                   // 查询超时时间（毫秒）
      "ssl": true                         // SSL 连接
    },
    "auth": {
      "autoConfirmUsers": false,          // 自动确认新用户
      "disableSignup": false,             // 禁用公共注册
      "jwt": {
        "expiresIn": "1h",               // Token 过期时间
        "algorithm": "HS256"              // JWT 算法
      }
    }
  }
}

日志配置

{
  "logging": {
    "level": "info",                      // 日志级别
    "format": "json",                     // 日志格式
    "outputs": ["console", "file"],       // 输出目标
    "file": {
      "path": "logs/server.log",          // 日志文件路径
      "maxSize": "10m",                   // 最大文件大小
      "maxFiles": 5                       // 最大文件数
    }
  }
}

安全配置

{
  "security": {
    "cors": {
      "enabled": true,
      "origins": ["*"],
      "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
      "allowedHeaders": ["Content-Type", "Authorization"]
    },
    "rateLimit": {
      "enabled": true,
      "windowMs": 900000,                 // 15 分钟
      "max": 100                          // 每个窗口的最大请求数
    }
  }
}

监控配置

{
  "monitoring": {
    "enabled": true,
    "metrics": {
      "collect": true,
      "interval": 60000                   // 收集间隔（毫秒）
    },
    "health": {
      "enabled": true,
      "path": "/health"                   // 健康检查端点
    }
  }
}

有关完整的示例配置文件，请参见 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"  // 可选：配置文件路径
    }
  }
}

可用工具

数据库操作

create_record

在表中创建一个新记录，并支持返回特定字段。

{
  table: string;
  data: Record<string, any>;
  returning?: string[];
}

示例：

{
  table: "users",
  data: {
    name: "John Doe",
    email: "john@example.com"
  },
  returning: ["id", "created_at"]
}

read_records

读取具有高级过滤、连接和字段选择的记录。

{
  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"
  }]
}

update_record

更新具有过滤和返回功能的记录。

{
  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"]
}

delete_record

删除具有过滤和返回功能的记录。

{
  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
  }
}

download_file

从 Supabase Storage 下载文件。

{
  bucket: string;
  path: string;
}

示例：

{
  bucket: "documents",
  path: "reports/annual-2023.pdf"
}

边缘函数

invoke_function

使用参数和自定义选项调用 Supabase 边缘函数。

{
  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"
  }
}

用户管理

list_users

列出具有分页支持的用户。

{
  page?: number;
  per_page?: number;
}

create_user

创建一个具有元数据的新用户。

{
  email: string;
  password: string;
  data?: Record<string, any>;
}

update_user

更新用户详细信息。

{
  user_id: string;
  email?: string;
  password?: string;
  data?: Record<string, any>;
}

delete_user

删除用户。

{
  user_id: string;
}

assign_user_role

为用户分配角色。

{
  user_id: string;
  role: string;
}

remove_user_role

从用户删除角色。

{
  user_id: string;
  role: string;
}

错误处理

服务器为常见场景提供详细的错误消息：

• 无效参数
• 身份验证失败
• 权限问题
• 速率限制
• 网络错误
• 数据库约束

错误以标准化格式返回：

{
  code: ErrorCode;
  message: string;
  details?: any;
}

开发

运行测试

npm test

构建

npm run build

代码检查

npm run lint

贡献

1. Fork 存储库
2. 创建一个功能分支
3. 提交您的更改
4. 推送到分支
5. 创建一个 Pull Request

许可证

MIT 许可证 - 有关详细信息，请参见 LICENSE

支持

如需支持，请：

1. 检查 issues 以查找现有问题/解决方案
2. 创建一个包含详细重现步骤的新 issue
3. 包括相关的错误消息和环境详细信息