Skip to main content
Glama
Supabase MCP Server

Supabase MCP Server

查询 | Supabase 的 MCP 服务器

🌅 通过 pypi 安装量超过 1.7 万次,在 Smithery.ai 上的下载量接近 3 万次——总之,这真是太有趣了!🥳 感谢过去几个月使用这个服务器的所有人,希望它对你们有所帮助。由于 Supabase 发布了他们自己的官方 MCP 服务器,我决定不再主动维护这个服务器。官方 MCP 服务器功能丰富,未来还会添加更多功能。快来体验吧!

目录

Related MCP server: Self-Hosted Supabase MCP Server

✨ 主要特点

  • 💻 兼容 Cursor、Windsurf、Cline 和其他支持stdio协议的 MCP 客户端

  • 🔐 控制 SQL 查询执行的只读和读写模式

  • 🔍 运行时 SQL 查询验证与风险级别评估

  • 🛡️ SQL 操作的三层安全系统:安全、写入和破坏性

  • 🔄 针对直接和池数据库连接提供强大的事务处理

  • 📝 数据库架构更改的自动版本控制

  • 💻 使用 Supabase 管理 API 管理您的 Supabase 项目

  • 🧑‍💻通过 Python SDK 使用 Supabase Auth Admin 方法管理用户

  • 🔨 预建工具可帮助 Cursor & Windsurf 更有效地与 MCP 配合使用

  • 📦通过包管理器(uv、pipx 等)进行极其简单的安装和设置

入门

先决条件

安装服务器需要您的系统具备以下条件:

  • Python 3.12+

如果您计划通过uv安装,请确保它已安装。

PostgreSQL 安装

MCP 服务器本身不再需要安装 PostgreSQL,因为它现在使用不依赖于 PostgreSQL 开发库的 asyncpg。

但是,如果您正在运行本地 Supabase 实例,则仍然需要 PostgreSQL:

MacOS

brew install postgresql@16

视窗

步骤1.安装

从 v0.2.0 开始,我引入了对软件包安装的支持。你可以使用你最喜欢的 Python 包管理器通过以下方式安装服务器:

# if pipx is installed (recommended)
pipx install supabase-mcp-server

# if uv is installed
uv pip install supabase-mcp-server

推荐使用pipx ,因为它为每个包创建了隔离的环境。

您还可以通过克隆存储库并从根目录运行pipx install -e .来手动安装服务器。

从源代码安装

如果您想从源代码安装,例如用于本地开发:

uv venv
# On Mac
source .venv/bin/activate
# On Windows
.venv\Scripts\activate
# Install package in editable mode
uv pip install -e .

通过 Smithery.ai 安装

您可以在此处找到有关如何使用 Smithery.ai 连接到此 MCP 服务器的完整说明。

步骤2.配置

Supabase MCP 服务器需要进行配置才能连接到您的 Supabase 数据库、访问 Management API 以及使用 Auth Admin SDK。本节介绍所有可用的配置选项以及如何设置它们。

🔑重要提示:自 v0.4 起,MCP 服务器需要 API 密钥,您可以在thequery.dev免费获取该密钥以使用此 MCP 服务器。

环境变量

服务器使用以下环境变量:

多变的

必需的

默认

描述

SUPABASE_PROJECT_REF

是的

127.0.0.1:54322

您的 Supabase 项目参考 ID(或本地主机:端口)

SUPABASE_DB_PASSWORD

是的

postgres

您的数据库密码

SUPABASE_REGION

是的*

us-east-1

您的 Supabase 项目所在的 AWS 区域

SUPABASE_ACCESS_TOKEN

不

没有任何

Supabase 管理 API 的个人访问令牌

SUPABASE_SERVICE_ROLE_KEY

不

没有任何

Auth Admin SDK 的服务角色密钥

QUERY_API_KEY

是的

没有任何

thequery.dev 的 API 密钥(所有操作都需要)

注意:默认值是为本地 Supabase 开发配置的。对于远程 Supabase 项目,您必须为SUPABASE_PROJECT_REF和SUPABASE_DB_PASSWORD提供自己的值。

🚨关键配置说明:对于远程 Supabase 项目,您必须使用SUPABASE_REGION指定项目托管的正确区域。如果您遇到“未找到租户或用户”错误,这几乎肯定是因为您的区域设置与项目的实际区域不匹配。您可以在 Supabase 仪表板的“项目设置”下找到项目的区域。

连接类型

数据库连接
  • 服务器使用事务池端点连接到您的 Supabase PostgreSQL 数据库

  • 本地开发使用直接连接到127.0.0.1:54322

  • 远程项目使用以下格式: postgresql://postgres.[project_ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

⚠️重要提示:不支持会话池连接。服务器仅使用事务池,以便更好地兼容 MCP 服务器架构。

管理 API 连接
  • 需要设置SUPABASE_ACCESS_TOKEN

  • 连接到 Supabase 管理 API,网址为https://api.supabase.com

  • 仅适用于远程 Supabase 项目(不适用于本地开发)

Auth Admin SDK 连接
  • 需要设置SUPABASE_SERVICE_ROLE_KEY

  • 对于本地开发,连接到http://127.0.0.1:54321

  • 对于远程项目,连接到https://[project_ref].supabase.co

配置方法

服务器按以下顺序查找配置(优先级从高到低):

  1. 环境变量:直接在您的环境中设置的值

  2. 本地.env文件:当前工作目录中的.env文件(仅从源运行时有效)

  3. 全局配置文件:

    • Windows: %APPDATA%\supabase-mcp\.env

    • macOS/Linux: ~/.config/supabase-mcp/.env

  4. 默认设置:本地开发默认值(如果未找到其他配置)

⚠️重要提示:使用通过 pipx 或 uv 安装的包时,项目目录中的本地.env文件不会被检测到。您必须使用环境变量或全局配置文件。

设置配置

选项 1:客户端特定配置(推荐)

直接在 MCP 客户端配置中设置环境变量(请参阅步骤 3 中客户端相关的设置说明)。大多数 MCP 客户端都支持此方法,这样可以使您的配置与客户端设置保持一致。

选项 2:全局配置

创建一个全局的.env配置文件,用于所有 MCP 服务器实例:

# Create config directory
# On macOS/Linux
mkdir -p ~/.config/supabase-mcp
# On Windows (PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp"

# Create and edit .env file
# On macOS/Linux
nano ~/.config/supabase-mcp/.env
# On Windows (PowerShell)
notepad "$env:APPDATA\supabase-mcp\.env"

将您的配置值添加到文件中:

QUERY_API_KEY=your-api-key
SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1
SUPABASE_ACCESS_TOKEN=your-access-token
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
选项 3:项目特定配置(仅限源安装)

如果您从源代码(而不是通过包)运行服务器,则可以在项目目录中创建一个与上述格式相同的.env文件。

查找您的 Supabase 项目信息

  • 项目参考:在您的 Supabase 项目 URL 中找到: https://supabase.com/dashboard/project/<project-ref>

  • 数据库密码:在项目创建期间设置或在项目设置→数据库中找到

  • 访问令牌:在https://supabase.com/dashboard/account/tokens生成

  • 服务角色密钥:在项目设置 → API → 项目 API 密钥中找到

支持地区

该服务器支持所有 Supabase 区域:

  • us-west-1 - 美国西部(北加利福尼亚)

  • us-east-1 - 美国东部(北弗吉尼亚)- 默认

  • us-east-2 - 美国东部(俄亥俄州)

  • ca-central-1 - 加拿大(中部)

  • eu-west-1 - 西欧(爱尔兰)

  • eu-west-2 - 西欧(伦敦)

  • eu-west-3 - 西欧(巴黎)

  • eu-central-1 - 欧盟中部(法兰克福)

  • eu-central-2 - 中欧(苏黎世)

  • eu-north-1 - 北欧(斯德哥尔摩)

  • ap-south-1 - 南亚(孟买)

  • ap-southeast-1 - 东南亚(新加坡)

  • ap-northeast-1 - 东北亚(东京)

  • ap-northeast-2 - 东北亚(首尔)

  • ap-southeast-2 - 大洋洲(悉尼)

  • sa-east-1 - 南美洲(圣保罗)

限制

  • 不支持自托管:服务器仅支持官方 Supabase.com 托管项目和本地开发

  • 不支持连接字符串:不支持自定义连接字符串

  • 无会话池:数据库连接仅支持事务池

  • API 和 SDK 功能:管理 API 和 Auth Admin SDK 功能仅适用于远程 Supabase 项目,不适用于本地开发

步骤3.使用

一般来说,任何支持stdio协议的 MCP 客户端都应该可以与此 MCP 服务器兼容。此服务器已明确测试可与以下平台兼容:

  • 光标

  • 风帆冲浪

  • 克莱恩

  • 克劳德桌面

此外,您还可以使用 smithery.ai 为该服务器安装多个客户端,包括上述客户端。

按照以下指南在您的客户端安装此 MCP 服务器。

光标

转到设置 -> 功能 -> MCP 服务器并添加具有以下配置的新服务器:

# can be set to any name
name: supabase
type: command
# if you installed with pipx
command: supabase-mcp-server
# if you installed with uv
command: uv run supabase-mcp-server
# if the above doesn't work, use the full path (recommended)
command: /full/path/to/supabase-mcp-server  # Find with 'which supabase-mcp-server' (macOS/Linux) or 'where supabase-mcp-server' (Windows)

如果配置正确,您应该会看到一个绿点指示器和服务器公开的工具数量。 成功的 Cursor 配置是什么样的

风帆冲浪

进入Cascade->点击锤子图标->配置->填写配置:

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // update path
        "env": {
          "QUERY_API_KEY": "your-api-key",  // Required - get your API key at thequery.dev
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1",  // optional, defaults to us-east-1
          "SUPABASE_ACCESS_TOKEN": "your-access-token",  // optional, for management API
          "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // optional, for Auth Admin SDK
        }
      }
    }
}

如果配置正确,您应该在可用服务器列表中看到绿点指示器和可点击的 supabase 服务器。

成功的 Windsurf 配置是什么样的

克劳德桌面

Claude Desktop 还通过 JSON 配置支持 MCP 服务器。请按照以下步骤设置 Supabase MCP 服务器:

  1. 找到可执行文件的完整路径(此步骤至关重要):

    # On macOS/Linux
    which supabase-mcp-server
    
    # On Windows
    where supabase-mcp-server

    复制返回的完整路径(例如, /Users/username/.local/bin/supabase-mcp-server )。

  2. 在 Claude Desktop 中配置 MCP 服务器:

    • 打开 Claude 桌面

    • 前往“设置”→“开发者”→“编辑配置 MCP 服务器”

    • 使用以下 JSON 添加新配置:

    {
      "mcpServers": {
        "supabase": {
          "command": "/full/path/to/supabase-mcp-server",  // Replace with the actual path from step 1
          "env": {
            "QUERY_API_KEY": "your-api-key",  // Required - get your API key at thequery.dev
            "SUPABASE_PROJECT_REF": "your-project-ref",
            "SUPABASE_DB_PASSWORD": "your-db-password",
            "SUPABASE_REGION": "us-east-1",  // optional, defaults to us-east-1
            "SUPABASE_ACCESS_TOKEN": "your-access-token",  // optional, for management API
            "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // optional, for Auth Admin SDK
          }
        }
      }
    }

⚠️重要提示:与 Windsurf 和 Cursor 不同,Claude Desktop 需要可执行文件的完整绝对路径。仅使用命令名称 ( supabase-mcp-server ) 将导致“spawn ENOENT”错误。

如果配置正确,您应该会看到 Supabase MCP 服务器在 Claude Desktop 中列为可用。

成功的 Windsurf 配置是什么样的

克莱恩

Cline 也通过类似的 JSON 配置支持 MCP 服务器。请按照以下步骤设置 Supabase MCP 服务器:

  1. 找到可执行文件的完整路径(此步骤至关重要):

    # On macOS/Linux
    which supabase-mcp-server
    
    # On Windows
    where supabase-mcp-server

    复制返回的完整路径(例如, /Users/username/.local/bin/supabase-mcp-server )。

  2. 在 Cline 中配置 MCP 服务器:

    • 在 VS Code 中打开 Cline

    • 点击 Cline 侧栏中的“MCP 服务器”选项卡

    • 点击“配置 MCP 服务器”

    • 这将打开cline_mcp_settings.json文件

    • 添加以下配置:

    {
      "mcpServers": {
        "supabase": {
          "command": "/full/path/to/supabase-mcp-server",  // Replace with the actual path from step 1
          "env": {
            "QUERY_API_KEY": "your-api-key",  // Required - get your API key at thequery.dev
            "SUPABASE_PROJECT_REF": "your-project-ref",
            "SUPABASE_DB_PASSWORD": "your-db-password",
            "SUPABASE_REGION": "us-east-1",  // optional, defaults to us-east-1
            "SUPABASE_ACCESS_TOKEN": "your-access-token",  // optional, for management API
            "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // optional, for Auth Admin SDK
          }
        }
      }
    }

如果配置正确,您应该会在 Cline MCP 服务器列表中的 Supabase MCP 服务器旁边看到一个绿色指示器,并在面板底部看到一条确认“supabase MCP 服务器已连接”的消息。

Cline 中的成功配置是什么样的

故障排除

以下是一些可能对您有帮助的提示和技巧:

  • 调试安装- 直接从终端运行supabase-mcp-server看看它是否正常工作。如果不行,则安装可能有问题。

  • MCP 服务器配置- 如果上述步骤成功,则表示服务器已正确安装和配置。只要您输入了正确的命令,IDE 就应该能够连接。请确保提供正确的服务器可执行文件路径。

  • “未找到工具”错误- 尽管软件包已安装,但如果您看到 Cursor 中显示“客户端已关闭 - 没有可用工具”:

    • 通过运行which supabase-mcp-server (macOS/Linux) 或where supabase-mcp-server (Windows) 找到可执行文件的完整路径

    • 在 MCP 服务器配置中使用完整路径,而不仅仅是supabase-mcp-server

    • 例如: /Users/username/.local/bin/supabase-mcp-server或C:\Users\username\.local\bin\supabase-mcp-server.exe

  • 环境变量- 要连接到正确的数据库,请确保在mcp_config.json或全局配置目录中的.env文件(macOS/Linux 上为~/.config/supabase-mcp/.env ,Windows 上为%APPDATA%\supabase-mcp\.env )中设置环境变量。

  • 访问日志- MCP 服务器将详细日志写入文件:

    • 日志文件位置:

      • macOS/Linux: ~/.local/share/supabase-mcp/mcp_server.log

      • Windows: %USERPROFILE%\.local\share\supabase-mcp\mcp_server.log

    • 日志包括连接状态、配置详情、操作结果

    • 使用任何文本编辑器或终端命令查看日志:

      # On macOS/Linux
      cat ~/.local/share/supabase-mcp/mcp_server.log
      
      # On Windows (PowerShell)
      Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"

如果您遇到困难或者上述任何说明不正确,请提出问题。

MCP 检查器

MCP Inspector 是一款非常实用的工具,可以帮助调试 MCP 服务器问题。如果您是从源代码安装的,则可以从项目仓库运行supabase-mcp-inspector ,它会运行检查器实例。结合日志,它可以让您全面了解服务器的运行情况。

📝 如果从包中安装,则运行supabase-mcp-inspector将无法正常工作 - 我将在即将发布的版本中验证并修复。

功能概述

数据库查询工具

由于 v0.3+ 服务器提供了全面的数据库管理功能并内置了安全控制:

  • SQL 查询执行:执行 PostgreSQL 查询并进行风险评估

    • 三层安全体系:

      • safe :只读操作(SELECT)- 始终允许

      • write :数据修改(插入、更新、删除) - 需要不安全模式

      • destructive :架构更改(DROP、CREATE) - 需要不安全模式+确认

  • SQL解析和验证:

    • 使用 PostgreSQL 的解析器(pglast)进行准确分析,并提供有关安全要求的明确反馈

  • 自动迁移版本控制:

    • 数据库修改操作会自动进行版本控制

    • 根据操作类型和目标生成描述性名称

  • 安全控制:

    • 默认 SAFE 模式仅允许只读操作

    • 所有语句均通过asyncpg以事务模式运行

    • 高风险操作两步确认

  • 可用工具:

    • get_schemas :列出模式的大小和表数

    • get_tables :列出表、外部表和带有元数据的视图

    • get_table_schema :获取详细的表结构(列、键、关系)

    • execute_postgresql :对数据库执行SQL语句

    • confirm_destructive_operation :确认后执行高风险操作

    • retrieve_migrations :获取带有过滤和分页选项的迁移

    • live_dangerously :在安全和不安全模式之间切换

管理 API 工具

自 v0.3.0 服务器提供对 Supabase 管理 API 的安全访问,并内置安全控制:

  • 可用工具:

    • send_management_api_request :向 Supabase Management API 发送任意请求,并自动注入项目引用

    • get_management_api_spec :获取包含安全信息的丰富 API 规范

      • 支持多种查询模式:按域、按特定路径/方法或所有路径

      • 包括每个端点的风险评估信息

      • 提供详细的参数要求和响应格式

      • 帮助 LLM 了解 Supabase 管理 API 的全部功能

    • get_management_api_safety_rules :获取所有安全规则,并提供人类可读的解释

    • live_dangerously :在安全和不安全操作模式之间切换

  • 安全控制:

    • 使用与数据库操作相同的安全管理器,实现一致的风险管理

    • 按风险等级分类的操作:

      • safe :只读操作(GET)- 始终允许

      • unsafe :状态改变操作(POST、PUT、PATCH、DELETE) - 需要不安全模式

      • blocked :破坏性操作(删除项目等)- 绝不允许

    • 默认安全模式可防止意外状态更改

    • 基于路径的模式匹配,实现精确的安全规则

注意:管理 API 工具仅适用于远程 Supabase 实例,与本地 Supabase 开发设置不兼容。

授权管理工具

我原本计划在 MCP 服务器中添加对 Python SDK 方法的支持。经过深思熟虑,我决定只添加对 Auth Admin 方法的支持,因为我经常手动创建测试用户,这很容易出错,而且耗时。现在我可以直接使用 Cursor 创建测试用户,整个过程无缝衔接。查看完整的 Auth Admin SDK 方法文档,了解它的功能。

自 v0.3.6 版本起,服务器支持通过 Python SDK 直接访问 Supabase Auth Admin 方法:

  • 包括以下工具:

    • get_auth_admin_methods_spec检索所有可用的 Auth Admin 方法的文档

    • call_auth_admin_method直接调用 Auth Admin 方法并进行适当的参数处理

  • 支持的方法:

    • get_user_by_id :通过 ID 检索用户

    • list_users :列出所有用户并分页

    • create_user :创建新用户

    • delete_user :通过 ID 删除用户

    • invite_user_by_email :将邀请链接发送到用户的电子邮件

    • generate_link :生成用于各种身份验证目的的电子邮件链接

    • update_user_by_id :通过 ID 更新用户属性

    • delete_factor :删除用户的一个因素(目前 SDK 中尚未实现)

为什么使用 Auth Admin SDK 而不是原始 SQL 查询?

与直接 SQL 操作相比,Auth Admin SDK 具有几个主要优势:

  • 功能:实现仅使用 SQL 无法实现的操作(邀请、魔术链接、MFA)

  • 准确性:比在身份验证模式上创建和执行原始 SQL 查询更可靠

  • 简单性:提供清晰的方法,并进行适当的验证和错误处理

    • 响应格式:

      • 所有方法都返回结构化的 Python 对象,而不是原始字典

      • 可以使用点符号访问对象属性(例如, user.id而不是user["id"] )

    • 边缘情况和限制:

      • UUID 验证:许多方法要求用户 ID 具有有效的 UUID 格式,并将返回特定的验证错误

      • 电子邮件配置: invite_user_by_email和generate_link等方法需要在您的 Supabase 项目中配置电子邮件发送

      • 链接类型:生成链接时,不同的链接类型有不同的要求:

        • signup链接不需要用户存在

        • magiclink和recovery链接要求用户已经存在于系统中

      • 错误处理:服务器提供来自 Supabase API 的详细错误消息,这可能与仪表板界面不同

      • 方法可用性:某些方法(例如delete_factor在 API 中公开,但未在 SDK 中完全实现

日志和分析

该服务器提供对 Supabase 日志和分析数据的访问,从而更轻松地监控和排除应用程序故障:

  • 可用工具: retrieve_logs - 从任何 Supabase 服务访问日志

  • 日志收集:

    • postgres :数据库服务器日志

    • api_gateway :API 网关请求

    • auth :身份验证事件

    • postgrest :RESTful API 服务日志

    • pooler :连接池日志

    • storage :对象存储操作

    • realtime :WebSocket 订阅日志

    • edge_functions :无服务器函数执行

    • cron :计划作业日志

    • pgbouncer :连接池日志

  • 功能:按时间过滤、搜索文本、应用字段过滤器或使用自定义 SQL 查询

简化 Supabase 堆栈中的调试,无需在界面之间切换或编写复杂的查询。

数据库更改的自动版本控制

“能力越大,责任越大。” 虽然execute_postgresql工具与恰如其名的live_dangerously工具相结合,提供了一种强大而简便的Supabase数据库管理方法,但这也意味着删除表或修改表只需一条聊天消息即可。为了降低不可逆更改的风险,自v0.3.8版本起,服务器支持:

  • 为数据库上执行的所有写入和破坏性 SQL 操作自动创建迁移脚本

  • 改进了查询执行的安全模式,其中所有查询都分为以下几类:

    • safe类型:始终允许。包括所有只读操作。

    • write类型:需要用户启用write模式。

    • destructive类型:需要用户启用write模式,并且对于不自动执行工具的客户端,需要两步确认查询执行。

通用安全模式

自 v0.3.8 版本起,安全模式已在所有服务(数据库、API、SDK)中实现标准化,并使用通用安全管理器。这为整个 MCP 服务器提供了一致的风险管理和统一的安全设置控制界面。

所有操作(SQL 查询、API 请求、SDK 方法)都分为以下风险级别:

  • Low风险:不修改数据或结构的只读操作(SELECT 查询、GET API 请求)

  • Medium风险:修改数据但不修改结构的写入操作(INSERT/UPDATE/DELETE,大多数 POST/PUT API 请求)

  • High风险:修改数据库结构或可能导致数据丢失的破坏性操作(DROP/TRUNCATE、DELETE API 端点)

  • Extreme风险:后果严重的操作将被彻底阻止(删除项目)

根据风险级别应用安全控制:

  • 始终允许低风险操作

  • 中等风险操作需要启用不安全模式

  • 高风险操作需要不安全模式和明确确认

  • 绝不允许极端风险操作

确认流程如何运作

即使在unsafe模式下,任何高风险操作(无论是 postgresql 还是 api 请求)都会被阻止。 每一个高风险的操作都被阻止您必须明确确认并批准每个高风险操作才能执行。 始终需要明确批准

变更日志

  • 📦通过包管理器简化安装 - ✅(v0.2.0)

  • 🌎 支持不同的 Supabase 区域 - ✅ (v0.2.2)

  • 🎮 通过安全控制以编程方式访问 Supabase 管理 API - ✅ (v0.3.0)

  • 👷‍♂️ 具有安全控制的读取和读写数据库 SQL 查询 - ✅(v0.3.0)

  • 🔄 针对直接连接和池连接的强大事务处理 - ✅(v0.3.2)

  • 🐍 支持原生 Python SDK 中可用的方法和对象 - ✅ (v0.3.6)

  • 🔍 更强大的 SQL 查询验证✅(v0.3.8)

  • 📝 数据库更改的自动版本控制✅(v0.3.8)

  • 📖 从根本上改进了 api 规范的知识和工具✅(v0.3.8)

  • ✍️ 改进了与迁移相关的工具的一致性,以实现更有条理的数据库 vcs✅(v0.3.10)

  • 🥳 查询 MCP 已发布 (v0.4.0)

有关更详细的路线图,请参阅 GitHub 上的讨论。

星史

星空历史图


尽情享受吧!☺️

Available Tools

12 tools
call_auth_admin_methodA

Call an Auth Admin method from Supabase Python SDK.

This tool provides a safe, validated interface to the Supabase Auth Admin SDK, allowing you to:

  • Manage users (create, update, delete)

  • List and search users

  • Generate authentication links

  • Manage multi-factor authentication

  • And more

IMPORTANT NOTES:

  • Request bodies must adhere to the Python SDK specification

  • Some methods may have nested parameter structures

  • The tool validates all parameters against Pydantic models

  • Extra fields not defined in the models will be rejected

AVAILABLE METHODS:

  • get_user_by_id: Retrieve a user by their ID

  • list_users: List all users with pagination

  • create_user: Create a new user

  • delete_user: Delete a user by their ID

  • invite_user_by_email: Send an invite link to a user's email

  • generate_link: Generate an email link for various authentication purposes

  • update_user_by_id: Update user attributes by ID

  • delete_factor: Delete a factor on a user

EXAMPLES:

  1. Get user by ID: method: "get_user_by_id" params: {"uid": "user-uuid-here"}

  2. Create user: method: "create_user" params: { "email": "user@example.com", "password": "secure-password" }

  3. Update user by ID: method: "update_user_by_id" params: { "uid": "user-uuid-here", "attributes": { "email": "new@email.com" } }

For complete documentation of all methods and their parameters, use the get_auth_admin_methods_spec tool.

Inputs: method (required), params (required).

confirm_destructive_operationA

Execute a destructive database or API operation after confirmation. Use this only after reviewing the risks with the user.

HOW IT WORKS:

  • This tool executes a previously rejected high-risk operation using its confirmation ID

  • The operation will be exactly the same as the one that generated the ID

  • No need to retype the query or api request params - the system remembers it

STEPS:

  1. Explain the risks to the user and get their approval

  2. Use this tool with the confirmation ID from the error message

  3. The original query will be executed as-is

PARAMETERS:

  • operation_type: Type of operation ("api" or "database")

  • confirmation_id: The ID provided in the error message (required)

  • user_confirmation: Set to true to confirm execution (default: false)

NOTE: Confirmation IDs expire after 5 minutes for security

Inputs: confirmation_id (required), operation_type (required), user_confirmation.

execute_postgresqlA

Execute PostgreSQL statements against your Supabase database.

IMPORTANT: All SQL statements must end with a semicolon (;).

OPERATION TYPES AND REQUIREMENTS:

  1. READ Operations (SELECT, EXPLAIN, etc.):

    • Can be executed directly without special requirements

    • Example: SELECT * FROM public.users LIMIT 10;

  2. WRITE Operations (INSERT, UPDATE, DELETE):

    • Require UNSAFE mode (use live_dangerously('database', True) first)

    • Example: INSERT INTO public.users (email) VALUES ('user@example.com');

  3. SCHEMA Operations (CREATE, ALTER, DROP):

    • Require UNSAFE mode (use live_dangerously('database', True) first)

    • Destructive operations (DROP, TRUNCATE) require additional confirmation

    • Example: CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT);

MIGRATION HANDLING: All queries that modify the database will be automatically version controlled by the server. You can provide optional migration name, if you want to name the migration.

  • Respect the following format: verb_noun_detail. Be descriptive and concise.

  • Examples:

    • create_users_table

    • add_email_to_profiles

    • enable_rls_on_users

  • If you don't provide a migration name, the server will generate one based on the SQL statement

  • The system will sanitize your provided name to ensure compatibility with database systems

  • Migration names are prefixed with a timestamp in the format YYYYMMDDHHMMSS

SAFETY SYSTEM: Operations are categorized by risk level:

  • LOW RISK: Read operations (SELECT, EXPLAIN) - allowed in SAFE mode

  • MEDIUM RISK: Write operations (INSERT, UPDATE, DELETE) - require UNSAFE mode

  • HIGH RISK: Schema operations (CREATE, ALTER) - require UNSAFE mode

  • EXTREME RISK: Destructive operations (DROP, TRUNCATE) - require UNSAFE mode and confirmation

TRANSACTION HANDLING:

  • DO NOT use transaction control statements (BEGIN, COMMIT, ROLLBACK)

  • The database client automatically wraps queries in transactions

  • The SQL validator will reject queries containing transaction control statements

  • This ensures atomicity and provides rollback capability for data modifications

MULTIPLE STATEMENTS:

  • You can send multiple SQL statements in a single query

  • Each statement will be executed in order within the same transaction

  • Example: CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT); INSERT INTO public.test_table (name) VALUES ('test');

CONFIRMATION FLOW FOR HIGH-RISK OPERATIONS:

  • High-risk operations (DROP TABLE, TRUNCATE, etc.) will be rejected with a confirmation ID

  • The error message will explain what happened and provide a confirmation ID

  • Review the risks with the user before proceeding

  • Use the confirm_destructive_operation tool with the provided ID to execute the operation

IMPORTANT GUIDELINES:

  • The database client starts in SAFE mode by default for safety

  • Only enable UNSAFE mode when you need to modify data or schema

  • Never mix READ and WRITE operations in the same transaction

  • For destructive operations, be prepared to confirm with the confirm_destructive_operation tool

WHEN TO USE OTHER TOOLS INSTEAD:

  • For Auth operations (users, authentication, etc.): Use call_auth_admin_method instead of direct SQL The Auth Admin SDK provides safer, validated methods for user management

  • For project configuration, functions, storage, etc.: Use send_management_api_request The Management API handles Supabase platform features that aren't directly in the database

Note: This tool operates on the PostgreSQL database only. API operations use separate safety controls.

Inputs: query (required), migration_name.

get_auth_admin_methods_specA

Get Python SDK methods specification for Auth Admin.

Returns a comprehensive dictionary of all Auth Admin methods available in the Supabase Python SDK, including:

  • Method names and descriptions

  • Required and optional parameters for each method

  • Parameter types and constraints

  • Return value information

This tool is useful for exploring the capabilities of the Auth Admin SDK and understanding how to properly format parameters for the call_auth_admin_method tool.

No parameters required.

Inputs: no named parameters.

get_management_api_specA

Get the complete Supabase Management API specification.

Returns the full OpenAPI specification for the Supabase Management API, including:

  • All available endpoints and operations

  • Required and optional parameters for each operation

  • Request and response schemas

  • Authentication requirements

  • Safety information for each operation

This tool can be used in four different ways:

  1. Without parameters: Returns all domains (default)

  2. With path and method: Returns the full specification for a specific API endpoint

  3. With domain only: Returns all paths and methods within that domain

  4. With all_paths=True: Returns all paths and methods

Parameters:

  • params: Dictionary containing optional parameters:

    • path: Optional API path (e.g., "/v1/projects/{ref}/functions")

    • method: Optional HTTP method (e.g., "GET", "POST")

    • domain: Optional domain/tag name (e.g., "Auth", "Storage")

    • all_paths: Optional boolean, if True returns all paths and methods

Available domains:

  • Analytics: Analytics-related endpoints

  • Auth: Authentication and authorization endpoints

  • Database: Database management endpoints

  • Domains: Custom domain configuration endpoints

  • Edge Functions: Serverless function management endpoints

  • Environments: Environment configuration endpoints

  • OAuth: OAuth integration endpoints

  • Organizations: Organization management endpoints

  • Projects: Project management endpoints

  • Rest: RESTful API endpoints

  • Secrets: Secret management endpoints

  • Storage: Storage management endpoints

This specification is useful for understanding:

  • What operations are available through the Management API

  • How to properly format requests for each endpoint

  • Which operations require unsafe mode

  • What data structures to expect in responses

SAFETY: This is a low-risk read operation that can be executed in SAFE mode.

Inputs: params.

get_schemasB

List all database schemas with their sizes and table counts.

Inputs: no named parameters.

get_tablesA

List all tables, foreign tables, and views in a schema with their sizes, row counts, and metadata.

Provides detailed information about all database objects in the specified schema:

  • Table/view names

  • Object types (table, view, foreign table)

  • Row counts

  • Size on disk

  • Column counts

  • Index information

  • Last vacuum/analyze times

Parameters:

  • schema_name: Name of the schema to inspect (e.g., 'public', 'auth', etc.)

SAFETY: This is a low-risk read operation that can be executed in SAFE mode.

Inputs: schema_name (required).

get_table_schemaA

Get detailed table structure including columns, keys, and relationships.

Returns comprehensive information about a specific table's structure:

  • Column definitions (names, types, constraints)

  • Primary key information

  • Foreign key relationships

  • Indexes

  • Constraints

  • Triggers

Parameters:

  • schema_name: Name of the schema (e.g., 'public', 'auth')

  • table: Name of the table to inspect

SAFETY: This is a low-risk read operation that can be executed in SAFE mode.

Inputs: schema_name (required), table (required).

live_dangerouslyA

Toggle unsafe mode for either Management API or Database operations.

WHAT THIS TOOL DOES: This tool switches between safe (default) and unsafe operation modes for either the Management API or Database operations.

SAFETY MODES EXPLAINED:

  1. Database Safety Modes:

    • SAFE mode (default): Only low-risk operations like SELECT queries are allowed

    • UNSAFE mode: Higher-risk operations including INSERT, UPDATE, DELETE, and schema changes are permitted

  2. API Safety Modes:

    • SAFE mode (default): Only low-risk operations that don't modify state are allowed

    • UNSAFE mode: Higher-risk state-changing operations are permitted (except those explicitly blocked for safety)

OPERATION RISK LEVELS: The system categorizes operations by risk level:

  • LOW: Safe read operations with minimal impact

  • MEDIUM: Write operations that modify data but don't change structure

  • HIGH: Operations that modify database structure or important system settings

  • EXTREME: Destructive operations that could cause data loss or service disruption

WHEN TO USE THIS TOOL:

  • Use this tool BEFORE attempting write operations or schema changes

  • Enable unsafe mode only when you need to perform data modifications

  • Always return to safe mode after completing write operations

USAGE GUIDELINES:

  • Start in safe mode by default for exploration and analysis

  • Switch to unsafe mode only when you need to make changes

  • Be specific about which service you're enabling unsafe mode for

  • Consider the risks before enabling unsafe mode, especially for database operations

  • For database operations requiring schema changes, you'll need to enable unsafe mode first

Parameters:

  • service: Which service to toggle ("api" or "database")

  • enable_unsafe_mode: True to enable unsafe mode, False for safe mode (default: False)

Examples:

  1. Enable database unsafe mode: live_dangerously(service="database", enable_unsafe_mode=True)

  2. Return to safe mode after operations: live_dangerously(service="database", enable_unsafe_mode=False)

  3. Enable API unsafe mode: live_dangerously(service="api", enable_unsafe_mode=True)

Note: This tool affects ALL subsequent operations for the specified service until changed again.

Inputs: service (required), enable_unsafe_mode.

retrieve_logsA

Retrieve logs from your Supabase project's services for debugging and monitoring.

Returns log entries from various Supabase services with timestamps, messages, and metadata. This tool provides access to the same logs available in the Supabase dashboard's Logs & Analytics section.

AVAILABLE LOG COLLECTIONS:

  • postgres: Database server logs including queries, errors, warnings, and system messages

  • api_gateway: API requests, responses, and errors processed by the Kong API gateway

  • auth: Authentication and authorization logs for sign-ups, logins, and token operations

  • postgrest: Logs from the RESTful API service that exposes your PostgreSQL database

  • pooler: Connection pooling logs from pgbouncer and supavisor services

  • storage: Object storage service logs for file uploads, downloads, and permissions

  • realtime: Logs from the real-time subscription service for WebSocket connections

  • edge_functions: Serverless function execution logs including invocations and errors

  • cron: Scheduled job logs (can be queried through postgres logs with specific filters)

  • pgbouncer: Connection pooler logs

PARAMETERS:

  • collection: The log collection to query (required, one of the values listed above)

  • limit: Maximum number of log entries to return (default: 20)

  • hours_ago: Retrieve logs from the last N hours (default: 1)

  • filters: List of filter objects with field, operator, and value (default: []) Format: [{"field": "field_name", "operator": "=", "value": "value"}]

  • search: Text to search for in event messages (default: "")

  • custom_query: Complete custom SQL query to execute instead of the pre-built queries (default: "")

HOW IT WORKS: This tool makes a request to the Supabase Management API endpoint for logs, sending either a pre-built optimized query for the selected collection or your custom query. Each log collection has a specific table structure and metadata format that requires appropriate CROSS JOIN UNNEST operations to access nested fields.

EXAMPLES:

  1. Using pre-built parameters: collection: "postgres" limit: 20 hours_ago: 24 filters: [{"field": "parsed.error_severity", "operator": "=", "value": "ERROR"}] search: "connection"

  2. Using a custom query: collection: "edge_functions" custom_query: "SELECT id, timestamp, event_message, m.function_id, m.execution_time_ms FROM function_edge_logs CROSS JOIN unnest(metadata) AS m WHERE m.execution_time_ms > 1000 ORDER BY timestamp DESC LIMIT 10"

METADATA STRUCTURE: The metadata structure is important because it determines how to access nested fields in filters:

  • postgres_logs: Use "parsed.field_name" for fields like error_severity, query, application_name

  • edge_logs: Use "request.field_name" or "response.field_name" for HTTP details

  • function_edge_logs: Use "function_id", "execution_time_ms" for function metrics

NOTE FOR LLM CLIENTS: When encountering errors with field access, examine the error message to see what fields are actually available in the structure. Start with basic fields before accessing nested metadata.

SAFETY CONSIDERATIONS:

  • This is a low-risk read operation that can be executed in SAFE mode

  • Requires a valid Supabase Personal Access Token to be configured

  • Not available for local Supabase instances (requires cloud deployment)

Inputs: collection (required), custom_query, filters, hours_ago, +2 more.

retrieve_migrationsA

Retrieve a list of all migrations a user has from Supabase.

Returns a list of migrations with the following information:

  • Version (timestamp)

  • Name

  • SQL statements (if requested)

  • Statement count

  • Version type (named or numbered)

Parameters:

  • limit: Maximum number of migrations to return (default: 50, max: 100)

  • offset: Number of migrations to skip for pagination (default: 0)

  • name_pattern: Optional pattern to filter migrations by name. Uses SQL ILIKE pattern matching (case-insensitive). The pattern is automatically wrapped with '%' wildcards, so "users" will match "create_users_table", "add_email_to_users", etc. To search for an exact match, use the complete name.

  • include_full_queries: Whether to include the full SQL statements in the result (default: false)

SAFETY: This is a low-risk read operation that can be executed in SAFE mode.

Inputs: include_full_queries, limit, name_pattern, offset.

send_management_api_requestA

Execute a Supabase Management API request.

This tool allows you to make direct calls to the Supabase Management API, which provides programmatic access to manage your Supabase project settings, resources, and configurations.

REQUEST FORMATTING:

  • Use paths exactly as defined in the API specification

  • The {ref} parameter will be automatically injected from settings

  • Format request bodies according to the API specification

PARAMETERS:

  • method: HTTP method (GET, POST, PUT, PATCH, DELETE)

  • path: API path (e.g. /v1/projects/{ref}/functions)

  • path_params: Path parameters as dict (e.g. {"function_slug": "my-function"}) - use empty dict {} if not needed

  • request_params: Query parameters as dict (e.g. {"key": "value"}) - use empty dict {} if not needed

  • request_body: Request body as dict (e.g. {"name": "test"}) - use empty dict {} if not needed

PATH PARAMETERS HANDLING:

  • The {ref} placeholder (project reference) is automatically injected - you don't need to provide it

  • All other path placeholders must be provided in the path_params dictionary

  • Common placeholders include:

    • {function_slug}: For Edge Functions operations

    • {id}: For operations on specific resources (API keys, auth providers, etc.)

    • {slug}: For organization operations

    • {branch_id}: For database branch operations

    • {provider_id}: For SSO provider operations

    • {tpa_id}: For third-party auth operations

EXAMPLES:

  1. GET request with path and query parameters: method: "GET" path: "/v1/projects/{ref}/functions/{function_slug}" path_params: {"function_slug": "my-function"} request_params: {"version": "1"} request_body: {}

  2. POST request with body: method: "POST" path: "/v1/projects/{ref}/functions" path_params: {} request_params: {} request_body: {"name": "test-function", "slug": "test-function"}

SAFETY SYSTEM: API operations are categorized by risk level:

  • LOW RISK: Read operations (GET) - allowed in SAFE mode

  • MEDIUM/HIGH RISK: Write operations (POST, PUT, PATCH, DELETE) - require UNSAFE mode

  • EXTREME RISK: Destructive operations - require UNSAFE mode and confirmation

  • BLOCKED: Some operations are completely blocked for safety reasons

SAFETY CONSIDERATIONS:

  • By default, the API client starts in SAFE mode, allowing only read operations

  • To perform write operations, first use live_dangerously(service="api", enable=True)

  • High-risk operations will be rejected with a confirmation ID

  • Use confirm_destructive_operation with the provided ID after reviewing risks

  • Some operations may be completely blocked for safety reasons

For a complete list of available API endpoints and their parameters, use the get_management_api_spec tool. For details on safety rules, use the get_management_api_safety_rules tool.

Inputs: method (required), path (required), path_params (required), request_body (required), +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have distinct purposes, such as call_auth_admin_method for auth operations, execute_postgresql for SQL queries, and send_management_api_request for API calls. However, get_auth_admin_methods_spec and get_management_api_spec are both specification-fetching tools that could be confused, and confirm_destructive_operation overlaps with safety mechanisms in other tools like execute_postgresql and send_management_api_request, causing minor ambiguity.

    Naming Consistency3/5

    The naming is mixed with some consistent patterns (e.g., get_* for read operations like get_schemas, get_tables) but deviations like call_auth_admin_method (verb_noun_noun), live_dangerously (phrase), and confirm_destructive_operation (verb_adjective_noun). While readable, the lack of a uniform verb_noun convention across all tools reduces consistency.

    Tool Count5/5

    With 12 tools, the count is well-scoped for a Supabase server covering database operations, auth management, API requests, logs, migrations, and safety controls. Each tool serves a clear purpose, such as execute_postgresql for SQL and retrieve_logs for monitoring, making the set comprehensive without being overwhelming.

    Completeness4/5

    The tool set provides broad coverage for Supabase domains, including CRUD for auth (via call_auth_admin_method), database queries, API management, and monitoring. Minor gaps exist, such as no direct tool for managing storage or edge functions beyond API requests, but agents can work around this using send_management_api_request with specifications from get_management_api_spec.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A protocol server that enables interaction with self-hosted Supabase instances directly from development environments, allowing database introspection, management of migrations, auth users, and storage through MCP clients like IDE extensions.
      21
      138
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables interaction with self-hosted Supabase instances, allowing developers to query database schemas, manage migrations, inspect statistics, and interact with Supabase features directly from MCP-compatible development environments.
      21
      1
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      A general-purpose PostgreSQL MCP server with full read-write SQL access, atomic multi-statement transactions, and schema inspection. Works with any PostgreSQL instance — local, Supabase, AWS RDS, or self-hosted — and connects to Claude, Cursor, Windsurf, or any MCP-compatible AI client.
      123 npm
      3
      ISC
    • A
      license
      Not graded
      quality
      F
      maintenance
      MCP server for self-hosted Supabase with RLS-aware PostgreSQL and PostgREST layers, enabling safe database introspection, SQL queries, and PostgREST access via natural language.
      MIT