Supabase MCP 数据库服务器
该服务器通过 MCP 协议实现与 Supabase PostgreSQL 数据库的交互,能够与 Cursor 和 Windsurf IDE 无缝集成,从而进行安全且经过验证的数据库管理。
可用工具 (11 个)
该服务在 MCP 协议中暴露的工具,AI 可按需调用
get_schemas
List all database schemas with their sizes and table counts.
该工具无需必填参数,直接调用即可
get_tables 1 个参数 需填 1 项
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.
必填参数:schema_name
get_table_schema 2 个参数 需填 2 项
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.
必填参数:schema_name、table
execute_postgresql 2 个参数 需填 1 项
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.
必填参数:query
retrieve_migrations 4 个参数
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.
该工具无需必填参数,直接调用即可
send_management_api_request 5 个参数 需填 5 项
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.
必填参数:method、path、path_params、request_params、request_body
get_management_api_spec 1 个参数
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.
该工具无需必填参数,直接调用即可
get_auth_admin_methods_spec
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.
该工具无需必填参数,直接调用即可
call_auth_admin_method 2 个参数 需填 2 项
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.
必填参数:method、params
live_dangerously 2 个参数 需填 1 项
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.
必填参数:service
confirm_destructive_operation 3 个参数 需填 2 项
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
必填参数:operation_type、confirmation_id
服务介绍
查询 MCP (Supabase MCP 服务器)
ð Supabase MCP 服务器的未来 -> 查询 MCP
我很高兴地宣布 Supabase MCP 服务器正在演变为 thequery.dev!
虽然我对未来有很多计划,但我希望把这些承诺说得非常清楚:
- 核心工具将永远免费 - 免费且开源的软件是我进入编程的方式
- 将在其基础上增加高级功能 - 增强功能而不限制现有功能
- 前2000名早期用户将获得特别福利 - 早点加入享受专属待遇!
ð 即将推出的重大v4版本!
目录
⨠主要特性
- ð» 与支持
stdio协议的Cursor、Windsurf、Cline等MCP客户端兼容 - ð 控制SQL查询执行的只读和读写模式
- ð 运行时SQL查询验证及风险级别评估
- ð¡ï¸ SQL操作的三级安全系统:安全、写入、破坏性
- ð 针对直接数据库连接和池化数据库连接的强大事务处理
- ð 数据库模式变更的自动版本控制
- ð» 使用Supabase管理API管理您的Supabase项目
- ð§âð» 通过Python SDK利用Supabase认证管理员方法管理用户
- ð¨ 为帮助Cursor & Windsurf更有效地与MCP协作而预先构建的工具
- ð¦ 通过包管理器(如uv, pipx等)进行极简安装与设置
开始使用
先决条件
安装服务器需要你的系统满足以下要求:
- Python 3.12+
如果你打算通过uv安装,请确保它已安装。
PostgreSQL 安装
对于MCP服务器本身来说,不再需要安装PostgreSQL了,因为它现在使用asyncpg,这不依赖于PostgreSQL开发库。
但是,如果你正在运行本地Supabase实例,仍然需要PostgreSQL:
MacOS
brew install postgresql@16
Windows
- 从 https://www.postgresql.org/download/windows/ 下载并安装PostgreSQL 16+
- 确保在安装过程中选择了“PostgreSQL Server”和“命令行工具”
第一步. 安装
自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服务器的完整说明,请参阅这里。
第二步. 配置
Supabase MCP 服务器需要配置以连接到您的 Supabase 数据库、访问管理 API 以及使用 Auth Admin SDK。本节解释了所有可用的配置选项及其设置方法。
环境变量
服务器使用以下环境变量:
| 变量 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|
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 的服务角色密钥 |
注意:默认值是为本地 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 - 连接到
https://api.supabase.com上的 Supabase 管理 API - 仅适用于远程 Supabase 项目(不适用于本地开发)
Auth Admin SDK 连接
- 需要设置
SUPABASE_SERVICE_ROLE_KEY - 对于本地开发,连接到
http://127.0.0.1:54321 - 对于远程项目,连接到
https://[project_ref].supabase.co
配置方法
服务器按以下顺序查找配置(优先级从高到低):
- 环境变量:直接在环境中设置的值
- 本地
.env文件:当前工作目录中的.env文件(仅在从源代码运行时有效) - 全局配置文件:
- Windows:
%APPDATA%\supabase-mcp\.env - macOS/Linux:
~/.config/supabase-mcp/.env
- Windows:
- 默认设置:本地开发默认设置(如果未找到其他配置)
⚠️ 重要: 当通过 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"
将您的配置值添加到文件中:
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 服务器配合使用。此服务器已明确测试可与以下客户端配合使用:
- Cursor
- Windsurf
- Cline
- Claude Desktop
此外,您还可以使用 smithery.ai 在多个客户端中安装此服务器,包括上面列出的客户端。
按照以下指南在您的客户端中安装此 MCP 服务器。
Cursor
转到设置 -> 功能 -> 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)
如果配置正确,你应该会看到一个绿色的点指示器和服务器暴露的工具数量。
Windsurf
前往 Cascade -> 点击锤子图标 -> 配置 -> 填写配置:
{
"mcpServers": {
"supabase": {
"command": "/Users/username/.local/bin/supabase-mcp-server", // update path
"env": {
"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 服务器。
Claude Desktop
Claude Desktop 也通过 JSON 配置支持 MCP 服务器。按照以下步骤设置 Supabase MCP 服务器:
-
找到可执行文件的完整路径(这一步很关键):
# 在 macOS/Linux 上 which supabase-mcp-server # 在 Windows 上 where supabase-mcp-server复制返回的完整路径(例如:
/Users/username/.local/bin/supabase-mcp-server)。 -
在 Claude Desktop 中配置 MCP 服务器:
- 打开 Claude Desktop
- 转到 设置 → 开发者 -> 编辑 Config MCP 服务器
- 添加一个新的配置,使用以下 JSON:
{ "mcpServers": { "supabase": { "command": "/full/path/to/supabase-mcp-server", // 用步骤 1 中的实际路径替换 "env": { "SUPABASE_PROJECT_REF": "your-project-ref", "SUPABASE_DB_PASSWORD": "your-db-password", "SUPABASE_REGION": "us-east-1", // 可选,默认为 us-east-1 "SUPABASE_ACCESS_TOKEN": "your-access-token", // 可选,用于管理 API "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key" // 可选,用于 Auth Admin SDK } } } }
â ï¸ 重要提示:与 Windsurf 和 Cursor 不同,Claude Desktop 需要可执行文件的完整绝对路径。仅使用命令名称 (
supabase-mcp-server) 将导致 "spawn ENOENT" 错误。
如果配置正确,你应该会在 Claude Desktop 中看到列出的 Supabase MCP 服务器。
Cline
Cline 也通过类似的 JSON 配置支持 MCP 服务器。按照以下步骤设置 Supabase MCP 服务器:
-
找到可执行文件的完整路径(这一步很关键):
# 在 macOS/Linux 上 which supabase-mcp-server # 在 Windows 上 where supabase-mcp-server复制返回的完整路径(例如:
/Users/username/.local/bin/supabase-mcp-server)。 -
在 Cline 中配置 MCP 服务器:
- 在 VS Code 中打开 Cline
- 点击 Cline 侧边栏中的 "MCP Servers" 标签
- 点击 "Configure MCP Servers"
- 这将打开
cline_mcp_settings.json文件 - 添加以下配置:
{ "mcpServers": { "supabase": { "command": "/full/path/to/supabase-mcp-server", // 用步骤1中得到的实际路径替换 "env": { "SUPABASE_PROJECT_REF": "your-project-ref", "SUPABASE_DB_PASSWORD": "your-db-password", "SUPABASE_REGION": "us-east-1", // 可选,默认为 us-east-1 "SUPABASE_ACCESS_TOKEN": "your-access-token", // 可选,用于管理 API "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key" // 可选,用于 Auth Admin SDK } } } }
如果配置正确,你应该会在 Cline 的 MCP 服务器列表中看到 Supabase MCP 服务器旁边有一个绿色指示器,并且面板底部会有一条消息确认 "supabase MCP server connected"。
故障排除
这里有一些可能对你有帮助的小技巧:
- 调试安装 - 直接从终端运行
supabase-mcp-server以查看其是否正常工作。如果不行,可能是安装过程中出现了问题。 - MCP 服务器配置 - 如果上述步骤有效,说明服务器已正确安装和配置。只要提供了正确的命令,IDE 应该能够连接。请确保提供到服务器可执行文件的正确路径。
- "未找到工具" 错误 - 如果在 Cursor 中看到 "Client closed - no tools available" 的提示,尽管包已经安装:
- 通过运行
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文件 (~/.config/supabase-mcp/.env对于 macOS/Linux 或%APPDATA%\supabase-mcp\.env对于 Windows) 设置了环境变量。 - 访问日志 - MCP 服务器将详细日志写入文件:
- 日志文件位置:
- macOS/Linux:
~/.local/share/supabase-mcp/mcp_server.log - Windows:
%USERPROFILE%\.local\share\supabase-mcp\mcp_server.log
- macOS/Linux:
- 日志包括连接状态、配置详情和操作结果
- 使用任何文本编辑器或终端命令查看日志:
# 在 macOS/Linux 上 cat ~/.local/share/supabase-mcp/mcp_server.log # 在 Windows (PowerShell) 上 Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"
- 日志文件位置:
如果你遇到困难或者发现上面的指导信息有误,请提出问题。
MCP 检查器
一个非常有用的工具来帮助调试 MCP 服务器问题是 MCP 检查器。如果你是从源代码安装的,可以从项目仓库运行 supabase-mcp-inspector 来启动检查器实例。结合日志一起使用,这将给你提供关于服务器内发生情况的全面概览。
ð 运行
supabase-mcp-inspector(如果从包安装),可能无法正常工作 - 我将在接下来的版本中验证并修复这个问题。
功能概述
数据库查询工具
自 v0.3+ 版本起,服务器提供了带有内置安全控制的综合数据库管理能力:
-
SQL 查询执行: 执行带有风险评估的 PostgreSQL 查询
- 三层安全系统:
safe: 只读操作(SELECT)- 始终允许write: 数据修改(INSERT, UPDATE, DELETE)- 需要非安全模式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 管理 API 发送任意请求,并自动注入项目引用get_management_api_spec: 获取带有安全信息的丰富 API 规范- 支持多种查询模式:按域、特定路径/方法或所有路径
- 包含每个端点的风险评估信息
- 提供详细的参数要求和响应格式
- 帮助 LLMs 了解 Supabase 管理 API 的全部功能
get_management_api_safety_rules: 获取所有带有可读解释的安全规则live_dangerously: 在安全和非安全操作模式之间切换
-
安全控制:
- 使用与数据库操作相同的安全部门,以实现一致的风险管理
- 操作按风险级别分类:
safe: 只读操作(GET)- 始终允许unsafe: 状态改变操作(POST, PUT, PATCH, DELETE)- 需要非安全模式blocked: 破坏性操作(删除项目等)- 永不允许
- 默认安全模式防止意外状态更改
- 基于路径的模式匹配以实现精确的安全规则
注意: 管理 API 工具仅适用于远程 Supabase 实例,不兼容本地 Supabase 开发设置。
认证管理工具
我计划为MCP服务器添加对Python SDK方法的支持。经过考虑,我决定仅添加对Auth管理方法的支持,因为我经常发现自己手动创建测试用户,这很容易出错且耗时。现在我可以直接让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无法完成的操作(如邀请、魔力链接、多因素认证)
-
准确性:比在auth模式上创建和执行原始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 方法)根据风险级别进行分类:
低风险:只读操作,不修改数据或结构(SELECT 查询、GET API 请求)中风险:写入操作,修改数据但不修改结构(INSERT/UPDATE/DELETE,大多数 POST/PUT API 请求)高风险:破坏性操作,修改数据库结构或可能导致数据丢失(DROP/TRUNCATE,DELETE API 终端)极高风险:具有严重后果的操作,完全被阻止(删除项目)
根据风险级别应用安全控制:
- 低风险操作始终允许
- 中风险操作需要启用非安全模式
- 高风险操作需要启用非安全模式并明确确认
- 极高风险操作永远不会被允许
确认流程如何工作
# 确认流程如何工作
请提供更多信息或上下文以便进一步翻译该部分的具体内容。如果这部分没有额外的信息,则保留上述翻译。
任何高风险操作(无论是 PostgreSQL 还是 API 请求)即使在 unsafe 模式下也会被阻止。
您必须明确确认并批准每个高风险操作,以便其能够被执行。
更新日志
- ð¦ 通过包管理器简化安装 - â (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)
有关更详细的路线图,请参阅 GitHub 上的讨论。
Star 历史
祝使用愉快! âºï¸