如何设置 Supabase MCP Server (2026)

如何在 2026 年设置 Supabase MCP Server

模型上下文协议 (Model Context Protocol, MCP) 是一种开放标准，允许 AI 助手与外部工具和数据源进行交互。Supabase MCP Server 让 Claude Desktop、Claude Code、Cursor、Windsurf 以及其他兼容 MCP 的客户端可以直接访问你的 Supabase 项目——包括执行数据库查询、表管理、Edge Functions 以及 Storage 存储。

这意味着你的 AI 助手可以查询生产环境数据、创建表、运行迁移、管理 RLS 策略以及调试问题，而无需你手动在 SQL 编辑器和 AI 对话框之间来回复制粘贴。

什么是 MCP？

MCP (Model Context Protocol) 由 Anthropic 创建，作为 AI 模型与外部系统交互的标准协议。你可以将其视作为 AI 助手设计的通用插件系统。

工作原理：

AI 助手 <---> MCP 客户端 <---> MCP Server <---> Supabase
(Claude 等)   (内置支持)     (你配置的服务)    (你的项目)

MCP Server 会暴露 AI 可以调用的“工具 (tools)”。对于 Supabase，这些工具包括运行 SQL 查询、列出表清单、管理存储桶 (Storage Buckets) 等。

前提条件

在设置 Supabase MCP Server 之前，你需要：

一个 Supabase 项目（免费版即可）
一个兼容 MCP 的 AI 客户端（Claude Desktop、Claude Code、Cursor 等）
已安装 Node.js 18+
你的 Supabase 项目 URL 和 service role key

获取你的 Supabase 凭据：

登录你的 Supabase Dashboard。
选择你的项目。
导航至 Settings > API。
复制你的 Project URL（例如 https://abcdefg.supabase.co）。
复制你的 service_role key（不要使用 anon key —— MCP 需要高级管理权限）。

方法 1：官方 Supabase MCP Server

Supabase 提供了一个官方的 MCP Server 软件包，适用于所有主流 MCP 客户端。

在 Claude Desktop 中设置

步骤 1：安装 MCP Server

Supabase MCP Server 通过 npx 运行，因此你不需要全局安装它。你只需在 Claude Desktop 的设置中进行配置。

步骤 2：配置 Claude Desktop

打开 Claude Desktop 的配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

添加 Supabase MCP Server 配置：

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "https://your-project-id.supabase.co",
        "--supabase-service-role-key",
        "your-service-role-key-here"
      ]
    }
  }
}

步骤 3：重启 Claude Desktop

关闭并重新打开 Claude Desktop。你应该能在工具菜单（锤子图标）中看到可用的 Supabase 工具。

在 Claude Code 中设置

对于 Claude Code（基于终端的 CLI），将 MCP Server 添加到你的项目配置中：

# 将 Supabase MCP server 添加到你的项目
claude mcp add supabase \
  --command "npx -y @supabase/mcp-server-supabase@latest \
  --supabase-url https://your-project-id.supabase.co \
  --supabase-service-role-key your-service-role-key-here"

或者手动将其添加到 .claude/mcp.json 文件中：

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "https://your-project-id.supabase.co",
        "--supabase-service-role-key",
        "your-service-role-key-here"
      ]
    }
  }
}

在 Cursor 中设置

在 Cursor 中，打开 Settings > MCP，并添加一个新 Server：

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "https://your-project-id.supabase.co",
        "--supabase-service-role-key",
        "your-service-role-key-here"
      ]
    }
  }
}

可用的 MCP 工具

连接后，你的 AI 助手可以访问以下工具：

工具名	描述	使用示例
`list_tables`	列出数据库中的所有表	"显示我项目中的所有表"
`execute_sql`	运行任意 SQL 查询	"查询本周注册的所有用户"
`get_table_schema`	获取表的列信息	"orders 表有哪些列？"
`create_table`	创建一个新表	"创建一个包含名称、价格和 SKU 的 products 表"
`insert_rows`	向表中插入数据	"向 products 表添加 5 个示例产品"
`update_rows`	更新现有行	"将所有不活跃用户的状态设置为已存档"
`delete_rows`	从表中删除行	"从 orders 表中删除所有测试数据"
`list_storage_buckets`	列出存储桶	"显示我所有的存储桶"
`list_edge_functions`	列出 Edge Functions	"部署了哪些 Edge Functions？"
`get_project_info`	获取项目元数据	"显示我的项目配置"
`apply_migration`	应用 SQL 迁移	"创建一个迁移以添加 email 索引"
`list_rls_policies`	列出 RLS 策略	"profiles 表上有哪些安全策略？"

实践示例

示例 1：探索数据库

连接后，只需用自然语言向 AI 助手提问：

用户：我的 Supabase 项目中有哪些表？

AI：让我帮您检查一下数据库模式。
[调用 list_tables]

您共有 6 张表：
- users (1,247 行) - 用户账户
- profiles (1,245 行) - 用户个人信息
- orders (3,892 行) - 采购订单
- products (156 行) - 产品目录
- order_items (8,431 行) - 订单中的明细项
- categories (12 行) - 产品分类

示例 2：编写并运行查询

用户：显示本月按订单总额排名的前 10 名客户。

AI：我为您查询一下数据库。
[调用 execute_sql]

以下是 2026 年 2 月订单金额排名前 10 的客户：

| 排名 | 客户名称 | 邮箱 | 总支出 |
|------|----------|-------|------------|
| 1 | Jane Smith | jane@... | $2,450.00 |
| 2 | Bob Chen | bob@... | $1,890.50 |
...

示例 3：创建表和迁移

用户：我需要一个 reviews 表。每个评价都应属于一个用户和一个产品，
具有评分 (1-5)、标题、正文和时间戳。添加适当的 RLS 策略，
使用户只能编辑自己的评价，但任何人都可以阅读所有评价。

AI：我将为您创建该表和 RLS 策略。
[调用 apply_migration 并带上 SQL 语句]

完成。我创建了：
- 带有所有指定列的 reviews 表
- 指向 users(id) 和 products(id) 的外键
- 评分在 1 到 5 之间的 CHECK 约束
- RLS 策略：任何人都可以 SELECT
- RLS 策略：已认证用户可以 INSERT (user_id = auth.uid())
- RLS 策略：用户仅能 UPDATE/DELETE 自己的评价

示例 4：调试问题

用户：用户反馈结账失败。检查最近是否有失败的订单，
以及记录了哪些错误。

AI：让我调查一下。
[调用 execute_sql - 查询状态为错误的订单]
[调用 execute_sql - 检查 Edge Function 日志]

我找到了问题。过去一小时内有 23 个订单失败，
报错信息均为 "stripe_payment_intent_failed"。Edge Function
日志显示来自 Stripe 的 401 Unauthorized 响应。
看起来可能是 Stripe API 密钥已过期或已被更换。

方法 2：社区 Postgres MCP Server

如果你不仅想使用 Supabase 特有的工具，还需要更广泛的 PostgreSQL 访问权限，可以使用 Postgres MCP Server 并配合你的 Supabase 连接字符串：

{
  "mcpServers": {
    "supabase-postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://postgres:your-password@db.your-project-id.supabase.co:5432/postgres"
      ]
    }
  }
}

你可以在 Supabase Dashboard 的 Settings > Database > Connection String 中找到你的连接字符串。

安全最佳实践

实践	重要性
仅为 MCP 使用 service role key	anon key 的权限有限
严禁将密钥提交至版本控制	将配置文件添加到 `.gitignore`
使用专门的开发/测试项目	避免在生产数据上直接运行 AI 生成的查询
执行前预览 SQL	某些 MCP 客户端会在运行前显示生成的 SQL
在所有表上启用 RLS	即使拥有 service role 权限，RLS 也是良好的安全习惯
尽可能使用只读凭据	为探索性操作创建一个只读的 Postgres 角色

为更安全的 MCP 访问创建只读角色：

-- 在 Supabase SQL Editor 中运行
CREATE ROLE mcp_readonly WITH LOGIN PASSWORD 'your-secure-password';
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

然后在你的 MCP 配置中使用该角色的连接字符串进行只读访问。

故障排除

问题	解决方法
MCP Server 未在 Claude Desktop 中显示	检查配置文件中的 JSON 语法，重启 Claude
"Connection refused" 错误	验证你的 Supabase URL，并确保项目处于活跃状态
"Permission denied" 错误	确保你使用的是 service_role key，而非 anon key
查询缓慢	MCP 查询限制为 30 秒；请优化您的 SQL
工具未出现	运行 `npx @supabase/mcp-server-supabase@latest --help` 以验证安装

结论

Supabase MCP Server 彻底改变了你与数据库交互的方式。你不再需要在编辑器、Supabase 控制面板和 SQL 客户端之间频繁切换，而是可以通过与 AI 助手的自然对话来探索数据、创建表、编写迁移和调试问题。整个设置过程不到五分钟，却能立即提升开发效率。

如果你的 Supabase 应用需要生成 AI 媒体内容——例如用户头像、宣传视频或语音内容——Hypereal AI 提供了按需付费的 API，涵盖 AI 图像生成、视频创作、数字人对话及语音克隆，可轻松集成到任何 Supabase 后端中。

如何在 2026 年设置 Supabase MCP Server

什么是 MCP？

MCP (Model Context Protocol) 由 Anthropic 创建，作为 AI 模型与外部系统交互的标准协议。你可以将其视作为 AI 助手设计的通用插件系统。

工作原理：

AI 助手 <---> MCP 客户端 <---> MCP Server <---> Supabase
(Claude 等)   (内置支持)     (你配置的服务)    (你的项目)

MCP Server 会暴露 AI 可以调用的“工具 (tools)”。对于 Supabase，这些工具包括运行 SQL 查询、列出表清单、管理存储桶 (Storage Buckets) 等。

前提条件

在设置 Supabase MCP Server 之前，你需要：

一个 Supabase 项目（免费版即可）
一个兼容 MCP 的 AI 客户端（Claude Desktop、Claude Code、Cursor 等）
已安装 Node.js 18+
你的 Supabase 项目 URL 和 service role key

获取你的 Supabase 凭据：

登录你的 Supabase Dashboard。
选择你的项目。
导航至 Settings > API。
复制你的 Project URL（例如 https://abcdefg.supabase.co）。
复制你的 service_role key（不要使用 anon key —— MCP 需要高级管理权限）。

方法 1：官方 Supabase MCP Server

Supabase 提供了一个官方的 MCP Server 软件包，适用于所有主流 MCP 客户端。

在 Claude Desktop 中设置

步骤 1：安装 MCP Server

Supabase MCP Server 通过 npx 运行，因此你不需要全局安装它。你只需在 Claude Desktop 的设置中进行配置。

步骤 2：配置 Claude Desktop

打开 Claude Desktop 的配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

添加 Supabase MCP Server 配置：

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "https://your-project-id.supabase.co",
        "--supabase-service-role-key",
        "your-service-role-key-here"
      ]
    }
  }
}

步骤 3：重启 Claude Desktop

关闭并重新打开 Claude Desktop。你应该能在工具菜单（锤子图标）中看到可用的 Supabase 工具。

在 Claude Code 中设置

对于 Claude Code（基于终端的 CLI），将 MCP Server 添加到你的项目配置中：

# 将 Supabase MCP server 添加到你的项目
claude mcp add supabase \
  --command "npx -y @supabase/mcp-server-supabase@latest \
  --supabase-url https://your-project-id.supabase.co \
  --supabase-service-role-key your-service-role-key-here"

或者手动将其添加到 .claude/mcp.json 文件中：

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "https://your-project-id.supabase.co",
        "--supabase-service-role-key",
        "your-service-role-key-here"
      ]
    }
  }
}

在 Cursor 中设置

在 Cursor 中，打开 Settings > MCP，并添加一个新 Server：

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "https://your-project-id.supabase.co",
        "--supabase-service-role-key",
        "your-service-role-key-here"
      ]
    }
  }
}

可用的 MCP 工具

连接后，你的 AI 助手可以访问以下工具：

工具名	描述	使用示例
`list_tables`	列出数据库中的所有表	"显示我项目中的所有表"
`execute_sql`	运行任意 SQL 查询	"查询本周注册的所有用户"
`get_table_schema`	获取表的列信息	"orders 表有哪些列？"
`create_table`	创建一个新表	"创建一个包含名称、价格和 SKU 的 products 表"
`insert_rows`	向表中插入数据	"向 products 表添加 5 个示例产品"
`update_rows`	更新现有行	"将所有不活跃用户的状态设置为已存档"
`delete_rows`	从表中删除行	"从 orders 表中删除所有测试数据"
`list_storage_buckets`	列出存储桶	"显示我所有的存储桶"
`list_edge_functions`	列出 Edge Functions	"部署了哪些 Edge Functions？"
`get_project_info`	获取项目元数据	"显示我的项目配置"
`apply_migration`	应用 SQL 迁移	"创建一个迁移以添加 email 索引"
`list_rls_policies`	列出 RLS 策略	"profiles 表上有哪些安全策略？"

实践示例

示例 1：探索数据库

连接后，只需用自然语言向 AI 助手提问：

用户：我的 Supabase 项目中有哪些表？

AI：让我帮您检查一下数据库模式。
[调用 list_tables]

您共有 6 张表：
- users (1,247 行) - 用户账户
- profiles (1,245 行) - 用户个人信息
- orders (3,892 行) - 采购订单
- products (156 行) - 产品目录
- order_items (8,431 行) - 订单中的明细项
- categories (12 行) - 产品分类

示例 2：编写并运行查询

用户：显示本月按订单总额排名的前 10 名客户。

AI：我为您查询一下数据库。
[调用 execute_sql]

以下是 2026 年 2 月订单金额排名前 10 的客户：

| 排名 | 客户名称 | 邮箱 | 总支出 |
|------|----------|-------|------------|
| 1 | Jane Smith | jane@... | $2,450.00 |
| 2 | Bob Chen | bob@... | $1,890.50 |
...

示例 3：创建表和迁移

用户：我需要一个 reviews 表。每个评价都应属于一个用户和一个产品，
具有评分 (1-5)、标题、正文和时间戳。添加适当的 RLS 策略，
使用户只能编辑自己的评价，但任何人都可以阅读所有评价。

AI：我将为您创建该表和 RLS 策略。
[调用 apply_migration 并带上 SQL 语句]

完成。我创建了：
- 带有所有指定列的 reviews 表
- 指向 users(id) 和 products(id) 的外键
- 评分在 1 到 5 之间的 CHECK 约束
- RLS 策略：任何人都可以 SELECT
- RLS 策略：已认证用户可以 INSERT (user_id = auth.uid())
- RLS 策略：用户仅能 UPDATE/DELETE 自己的评价

示例 4：调试问题

用户：用户反馈结账失败。检查最近是否有失败的订单，
以及记录了哪些错误。

AI：让我调查一下。
[调用 execute_sql - 查询状态为错误的订单]
[调用 execute_sql - 检查 Edge Function 日志]

我找到了问题。过去一小时内有 23 个订单失败，
报错信息均为 "stripe_payment_intent_failed"。Edge Function
日志显示来自 Stripe 的 401 Unauthorized 响应。
看起来可能是 Stripe API 密钥已过期或已被更换。

方法 2：社区 Postgres MCP Server

如果你不仅想使用 Supabase 特有的工具，还需要更广泛的 PostgreSQL 访问权限，可以使用 Postgres MCP Server 并配合你的 Supabase 连接字符串：

{
  "mcpServers": {
    "supabase-postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://postgres:your-password@db.your-project-id.supabase.co:5432/postgres"
      ]
    }
  }
}

你可以在 Supabase Dashboard 的 Settings > Database > Connection String 中找到你的连接字符串。

安全最佳实践

实践	重要性
仅为 MCP 使用 service role key	anon key 的权限有限
严禁将密钥提交至版本控制	将配置文件添加到 `.gitignore`
使用专门的开发/测试项目	避免在生产数据上直接运行 AI 生成的查询
执行前预览 SQL	某些 MCP 客户端会在运行前显示生成的 SQL
在所有表上启用 RLS	即使拥有 service role 权限，RLS 也是良好的安全习惯
尽可能使用只读凭据	为探索性操作创建一个只读的 Postgres 角色

为更安全的 MCP 访问创建只读角色：

-- 在 Supabase SQL Editor 中运行
CREATE ROLE mcp_readonly WITH LOGIN PASSWORD 'your-secure-password';
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

然后在你的 MCP 配置中使用该角色的连接字符串进行只读访问。

故障排除

问题	解决方法
MCP Server 未在 Claude Desktop 中显示	检查配置文件中的 JSON 语法，重启 Claude
"Connection refused" 错误	验证你的 Supabase URL，并确保项目处于活跃状态
"Permission denied" 错误	确保你使用的是 service_role key，而非 anon key
查询缓慢	MCP 查询限制为 30 秒；请优化您的 SQL
工具未出现	运行 `npx @supabase/mcp-server-supabase@latest --help` 以验证安装

开始使用 Hypereal 构建

如何在 2026 年设置 Supabase MCP Server

什么是 MCP？

前提条件

方法 1：官方 Supabase MCP Server

在 Claude Desktop 中设置

在 Claude Code 中设置

在 Cursor 中设置

可用的 MCP 工具

实践示例

示例 1：探索数据库

示例 2：编写并运行查询

示例 3：创建表和迁移

示例 4：调试问题

方法 2：社区 Postgres MCP Server

安全最佳实践

故障排除

结论

相关文章

如何设置 PostgreSQL MCP Server (2026)

如何从零开始构建 MCP Server (2026)

如何设置 Context7 MCP Server (2026)

立即开始构建

开始使用 Hypereal 构建

如何在 2026 年设置 Supabase MCP Server

什么是 MCP？

前提条件

方法 1：官方 Supabase MCP Server

在 Claude Desktop 中设置

在 Claude Code 中设置

在 Cursor 中设置

可用的 MCP 工具

实践示例

示例 1：探索数据库

示例 2：编写并运行查询

示例 3：创建表和迁移

示例 4：调试问题

方法 2：社区 Postgres MCP Server

安全最佳实践

故障排除

结论

相关文章

如何设置 PostgreSQL MCP Server (2026)

如何从零开始构建 MCP Server (2026)

如何设置 Context7 MCP Server (2026)

立即开始构建