自托管Supabase MCP服务器
 ](https://smithery.ai/server/@HenkDz/selfhosted-supabase-mcp)
概述
该项目提供了 模型上下文协议（MCP） 专为与以下对象交互而设计的服务器 自托管的Supabase实例。它弥合了MCP客户端（如IDE扩展）与本地或私有托管的Supabase项目之间的差距，使数据库自检、管理和交互直接从您的开发环境中实现。
该服务器是从头开始构建的，借鉴了官方Supabase云MCP服务器的经验，为自托管用例提供了一个最小、专注的实现。
目的
此服务器的主要目标是使使用自托管Supabase安装的开发人员能够利用基于MCP的工具完成以下任务：
- 查询数据库模式和数据。
- 管理数据库迁移。
- 检查数据库统计信息和连接。
- 管理身份验证用户。
- 与Supabase存储交互。
- 正在生成类型定义。
它避免了与多项目管理和云特定API相关的官方云服务器的复杂性，为单项目、自托管环境提供了简化的体验。
功能（已实现的工具）
服务器向MCP客户端公开以下工具：
- 架构和迁移
- list_tables：列出数据库架构中的表。 - list_extensions：列出已安装的PostgreSQL扩展。 - list_migrations：列出应用的Supabase迁移。 - apply_migration：应用SQL迁移脚本。
- 数据库操作和统计
- execute_sql：执行任意SQL查询（通过RPC或直接连接）。 - get_database_connections：显示活动数据库连接(pg_stat_activity). - get_database_stats：检索数据库统计信息(pg_stat_*).
- 项目配置和密钥
- get_project_url：返回配置的Supabase URL。 - get_anon_key：返回配置的Supabase匿名密钥。 - get_service_key：返回配置的Supabase服务角色密钥（如果提供）。 - verify_jwt_secret：检查是否配置了JWT密钥，并返回预览。
- 开发和扩展工具
- generate_typescript_types：从数据库架构生成TypeScript类型。 - rebuild_hooks：尝试重新启动 pg_net 工人（如果使用）。
- 身份验证用户管理
- list_auth_users：列出来自的用户 auth.users. - get_auth_user：检索特定用户的详细信息。 - create_auth_user：创建新用户（需要直接访问数据库，密码处理不安全）。 - delete_auth_user：删除用户（需要直接访问数据库）。 - update_auth_user：更新用户详细信息（需要直接访问数据库，密码处理不安全）。
- 存储洞察
- list_storage_buckets：列出所有存储桶。 - list_storage_objects：列出特定bucket中的对象。
- 实时检测
- list_realtime_publications：列出PostgreSQL出版物（通常 supabase_realtime).
*（注： get_logs 最初是计划好的，但由于在自托管环境中的实现复杂性而被跳过）。*
设置和安装
通过Smithery安装
通过以下方式自动安装克劳德桌面的自托管Supabase MCP服务器 史密瑟里:
npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude先决条件
- Node.js（推荐18.x或更高版本）
- npm（通常包含在Node.js中）
- 访问自托管的Supabase实例（URL、密钥、可能的直接DB连接字符串）。
步骤
- 克隆存储库：
git clone
cd self-hosted-supabase-mcp- 安装依赖项：
npm install- 构建项目：
npm run build这将TypeScript代码编译为JavaScript dist 目录。
配置
服务器需要您的Supabase实例的配置详细信息。这些可以通过命令行参数或环境变量提供。CLI参数优先。
必修的：
--url或SUPABASE_URL=：您的Supabase项目的主要HTTP URL（例如。，http://localhost:8000).--anon-key或SUPABASE_ANON_KEY=：您的Supabase项目的匿名密钥。
可选（但某些工具建议/必需）：
--service-key或SUPABASE_SERVICE_ROLE_KEY=：您的Supabase项目的服务角色密钥。需要提升权限的操作，如尝试自动创建execute_sql辅助函数（如果不存在）。--db-url或DATABASE_URL=：Supabase数据库的PostgreSQL直接连接字符串（例如。，postgresql://postgres:password@localhost:5432/postgres).需要直接访问数据库或处理事务的工具需要(apply_migration、身份验证工具、存储工具、查询pg_catalog等等）。--jwt-secret或SUPABASE_AUTH_JWT_SECRET=：你的Supabase项目的JWT秘密。需要像这样的工具verify_jwt_secret.- `--tools-config
：指定要启用哪些工具的JSON文件的路径（白名单）。如果省略，则启用服务器中定义的所有工具。文件应具有以下格式 {"enabledTools": ["tool_name_1", "tool_name_2"]}`.
重要提示：
execute_sql辅助功能： 许多工具依赖于public.execute_sqlSupabase数据库中的函数，通过RPC安全高效地执行SQL。服务器在启动时尝试检查此功能。如果它不见了 *和* 一service-key（或SUPABASE_SERVICE_ROLE_KEY) *和*db-url（或DATABASE_URL)如果提供了，它将尝试创建该函数并授予必要的权限。如果创建失败或未提供密钥，则仅依赖RPC的工具可能会失败。- 直接数据库访问： 与特权模式直接交互的工具(
auth,storage)或系统目录(pg_catalog)一般要求DATABASE_URL配置为直接pg连接。
用法
使用Node.js运行服务器，提供必要的配置：
# Using CLI arguments (example)
node dist/index.js --url http://localhost:8000 --anon-key --db-url postgresql://postgres:password@localhost:5432/postgres [--service-key ]
# Example with tool whitelisting via config file
node dist/index.js --url http://localhost:8000 --anon-key --tools-config ./mcp-tools.json
# Or configure using environment variables and run:
# export SUPABASE_URL=http://localhost:8000
# export SUPABASE_ANON_KEY=
# export DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres
# export SUPABASE_SERVICE_ROLE_KEY=
# The --tools-config option MUST be passed as a CLI argument if used
node dist/index.js
# Using npm start script (if configured in package.json to pass args/read env)
npm start -- --url ... --anon-key ...服务器通过标准输入/输出（stdio）进行通信，并设计为由MCP客户端应用程序（例如Cursor等IDE扩展）调用。客户端将连接到服务器的stdio流，以列出和调用可用的工具。
客户端配置示例
下面是如何配置流行的MCP客户端以使用此自托管服务器的示例。
重要提示：
- 替换占位符，如 `
,,,
` 等等，用你的实际值。
- 确保已编译服务器文件的路径(
dist/index.js)适用于您的系统。 - 请谨慎将敏感密钥直接存储在配置文件中，特别是在进行版本控制的情况下。考虑在客户端支持的情况下使用环境变量或更安全的方法。
光标
- 创建或打开文件
.cursor/mcp.json在您的项目根目录中。
- 添加以下配置：
{
"mcpServers": {
"selfhosted-supabase": {
"command": "node",
"args": [
"
", // e.g., "F:/Projects/mcp-servers/self-hosted-supabase-mcp/dist/index.js"
"--url",
"", // e.g., "http://localhost:8000"
"--anon-key",
"",
// Optional - Add these if needed by the tools you use
"--service-key",
"",
"--db-url",
"", // e.g., "postgresql://postgres:password@host:port/postgres"
"--jwt-secret",
"",
// Optional - Whitelist specific tools
"--tools-config",
"
" // e.g., "./mcp-tools.json"
]
}
}
}Visual Studio代码（副本）
VS Code Copilot允许使用通过提示输入填充的环境变量，这对密钥来说更安全。
- 创建或打开文件
.vscode/mcp.json在您的项目根目录中。
- 添加以下配置：
{
"inputs": [
{ "type": "promptString", "id": "sh-supabase-url", "description": "Self-Hosted Supabase URL", "default": "http://localhost:8000" },
{ "type": "promptString", "id": "sh-supabase-anon-key", "description": "Self-Hosted Supabase Anon Key", "password": true },
{ "type": "promptString", "id": "sh-supabase-service-key", "description": "Self-Hosted Supabase Service Key (Optional)", "password": true, "required": false },
{ "type": "promptString", "id": "sh-supabase-db-url", "description": "Self-Hosted Supabase DB URL (Optional)", "password": true, "required": false },
{ "type": "promptString", "id": "sh-supabase-jwt-secret", "description": "Self-Hosted Supabase JWT Secret (Optional)", "password": true, "required": false },
{ "type": "promptString", "id": "sh-supabase-server-path", "description": "Path to self-hosted-supabase-mcp/dist/index.js" },
{ "type": "promptString", "id": "sh-supabase-tools-config", "description": "Path to tools config JSON (Optional, e.g., ./mcp-tools.json)", "required": false }
],
"servers": {
"selfhosted-supabase": {
"command": "node",
// Arguments are passed via environment variables set below OR direct args for non-env options
"args": [
"${input:sh-supabase-server-path}",
// Use direct args for options not easily map-able to standard env vars like tools-config
// Check if tools-config input is provided before adding the argument
["--tools-config", "${input:sh-supabase-tools-config}"]
// Alternatively, pass all as args if simpler:
// "--url", "${input:sh-supabase-url}",
// "--anon-key", "${input:sh-supabase-anon-key}",
// ... etc ...
],
"env": {
"SUPABASE_URL": "${input:sh-supabase-url}",
"SUPABASE_ANON_KEY": "${input:sh-supabase-anon-key}",
"SUPABASE_SERVICE_ROLE_KEY": "${input:sh-supabase-service-key}",
"DATABASE_URL": "${input:sh-supabase-db-url}",
"SUPABASE_AUTH_JWT_SECRET": "${input:sh-supabase-jwt-secret}"
// The server reads these environment variables as fallbacks if CLI args are missing
}
}
}
}- 当您在代理模式（@workspace）下使用Copilot Chat时，它应该能检测到服务器。首次调用服务器时，系统将提示您输入详细信息（URL、密钥、路径）。
其他客户（Windsurf、Cline、Claude）
调整Cursor或官方Supabase文档中显示的配置结构，替换 command 和 args 随着 node 命令和此服务器的参数，类似于Cursor示例：
{
"mcpServers": {
"selfhosted-supabase": {
"command": "node",
"args": [
"
",
"--url", "",
"--anon-key", "",
// Optional args...
"--service-key", "",
"--db-url", "",
"--jwt-secret", "",
// Optional tools config
"--tools-config", "
"
]
}
}
}请查阅每个客户的具体文件，了解将 mcp.json 或等效的配置文件。
发展
- 语言： TypeScript
- 构建：
tsc（TypeScript编译器） - 依赖关系： 通过管理
npm(package.json) - 核心库：
@supabase/supabase-js,pg（节点postgres），zod（验证），commander（CLI参数），@modelcontextprotocol/sdk（MCP服务器框架）。
许可证
该项目根据MIT许可证获得许可。有关详细信息，请参阅LICENSE文件。