Selfhosted Supabase Mcp Basic Auth

开发 TypeScript

🚀 自托管Supabase MCP服务器

本项目提供了一个专门用于与自托管Supabase实例进行交互的模型上下文协议（MCP）服务器。它架起了MCP客户端（如IDE扩展）与本地或私有托管的Supabase项目之间的桥梁，让你可以直接在开发环境中进行数据库内省、管理和交互。

本服务器是从头开始构建的，借鉴了对官方Supabase云MCP服务器进行适配的经验，提供了一个专门针对自托管用例的精简、聚焦的实现。

🚀 快速开始

本项目提供的MCP服务器可让MCP客户端（如IDE扩展）与自托管的Supabase实例进行交互。以下将详细介绍其使用方法。

安装

你可以通过Smithery自动为Claude Desktop安装自托管Supabase MCP服务器：

npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude

前提条件

Node.js（建议版本18.x或更高）
npm（通常随Node.js一起安装）
能够访问自托管的Supabase实例（包括URL、密钥，可能还需要直接的数据库连接字符串）

步骤

克隆仓库：

git clone 
cd self-hosted-supabase-mcp

安装依赖：

npm install

构建项目：

npm run build

这将把TypeScript代码编译为JavaScript，并存储在dist目录中。

配置

服务器需要你提供Supabase实例的配置信息。你可以通过命令行参数或环境变量来提供这些信息，命令行参数的优先级更高。

必需配置：

--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辅助函数：许多工具依赖于Supabase数据库中的public.execute_sql函数，以通过RPC安全高效地执行SQL。服务器在启动时会检查该函数是否存在。如果该函数不存在，并且提供了service-key（或SUPABASE_SERVICE_ROLE_KEY）和db-url（或DATABASE_URL），服务器将尝试创建该函数并授予必要的权限。如果创建失败或未提供相应密钥，则仅依赖RPC的工具可能会失败。
直接数据库访问：直接与特权模式（如auth、storage）或系统目录（如pg_catalog）进行交互的工具通常需要配置DATABASE_URL，以便进行直接的pg连接。

运行服务器

使用Node.js运行服务器，并提供必要的配置：

# 使用命令行参数（示例）
node dist/index.js --url http://localhost:8000 --anon-key  --db-url postgresql://postgres:password@localhost:5432/postgres [--service-key ]

# 通过配置文件进行工具白名单设置的示例
node dist/index.js --url http://localhost:8000 --anon-key  --tools-config ./mcp-tools.json

# 或者使用环境变量进行配置并运行：
# export SUPABASE_URL=http://localhost:8000
# export SUPABASE_ANON_KEY=
# export DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres
# export SUPABASE_SERVICE_ROLE_KEY=
# 如果使用了 --tools-config 选项，则必须将其作为命令行参数传递
node dist/index.js

# 使用 npm start 脚本（如果在 package.json 中配置为传递参数/读取环境变量）
npm start -- --url ... --anon-key ...

服务器通过标准输入/输出（stdio）进行通信，设计用于由MCP客户端应用程序（如Cursor等IDE扩展）调用。客户端将连接到服务器的stdio流，以列出和调用可用的工具。

客户端配置示例

以下是如何配置流行的MCP客户端以使用此自托管服务器的示例。

重要提示：

请将、、、等占位符替换为你自己的实际值。
确保编译后的服务器文件（dist/index.js）的路径对你的系统来说是正确的。
注意不要将敏感密钥直接存储在配置文件中，特别是如果这些文件要提交到版本控制系统。如果客户端支持，请考虑使用环境变量或更安全的方法。

Cursor

在项目根目录中创建或打开.cursor/mcp.json文件。
添加以下配置：

{
"mcpServers": {
"selfhosted-supabase": {
"command": "node",
"args": [
"", // 例如："F:/Projects/mcp-servers/self-hosted-supabase-mcp/dist/index.js"
"--url",
"", // 例如："http://localhost:8000"
"--anon-key",
"",
// 可选 - 根据你使用的工具添加这些参数
"--service-key",
"",
"--db-url",
"", // 例如："postgresql://postgres:password@host:port/postgres"
"--jwt-secret",
"",
// 可选 - 白名单特定工具
"--tools-config",
"" // 例如："./mcp-tools.json"
]
}
}
}

Visual Studio Code（Copilot）

VS Code Copilot允许通过提示输入来填充环境变量，这对于存储密钥更安全。

在项目根目录中创建或打开.vscode/mcp.json文件。
添加以下配置：

{
"inputs": [
{ "type": "promptString", "id": "sh-supabase-url", "description": "自托管Supabase URL", "default": "http://localhost:8000" },
{ "type": "promptString", "id": "sh-supabase-anon-key", "description": "自托管Supabase匿名密钥", "password": true },
{ "type": "promptString", "id": "sh-supabase-service-key", "description": "自托管Supabase服务角色密钥（可选）", "password": true, "required": false },
{ "type": "promptString", "id": "sh-supabase-db-url", "description": "自托管Supabase数据库URL（可选）", "password": true, "required": false },
{ "type": "promptString", "id": "sh-supabase-jwt-secret", "description": "自托管Supabase JWT密钥（可选）", "password": true, "required": false },
{ "type": "promptString", "id": "sh-supabase-server-path", "description": "自托管Supabase MCP服务器 dist/index.js 文件的路径" },
{ "type": "promptString", "id": "sh-supabase-tools-config", "description": "工具配置JSON文件的路径（可选，例如：./mcp-tools.json）", "required": false }
],
"servers": {
"selfhosted-supabase": {
"command": "node",
// 参数通过下面设置的环境变量传递，或者对于非环境变量选项使用直接参数
"args": [
"${input:sh-supabase-server-path}",
// 对于不易映射到标准环境变量的选项（如 tools-config），使用直接参数
// 在添加参数之前检查是否提供了 tools-config 输入
["--tools-config", "${input:sh-supabase-tools-config}"]
// 或者，如果更简单，可以将所有参数都作为直接参数传递：
// "--url", "${input:sh-supabase-url}",
// "--anon-key", "${input:sh-supabase-anon-key}",
// ... 等等 ... 
],
"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}"
// 如果命令行参数缺失，服务器将读取这些环境变量作为备用
}
}
}
}

当你在代理模式（@workspace）下使用Copilot Chat时，它应该会检测到服务器。首次调用服务器时，系统会提示你输入详细信息（URL、密钥、路径）。

其他客户端（Windsurf、Cline、Claude）

参考Cursor的配置结构或官方Supabase文档，将command和args替换为node命令和此服务器的参数，类似于Cursor的示例：

{
"mcpServers": {
"selfhosted-supabase": {
"command": "node",
"args": [
"",
"--url", "",
"--anon-key", "",
// 可选参数...
"--service-key", "",
"--db-url", "",
"--jwt-secret", "",
// 可选工具配置
"--tools-config", ""
]
}
}
}

请查阅每个客户端的具体文档，了解将mcp.json或等效配置文件放置的位置。

✨ 主要特性

本服务器为使用自托管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：列出特定存储桶中的对象。

实时检查

list_realtime_publications：列出PostgreSQL发布（通常为supabase_realtime）。

(注意：get_logs最初有计划实现，但由于在自托管环境中的实现复杂性而被跳过。)

📚 详细文档

开发信息

编程语言：TypeScript
构建工具：tsc（TypeScript编译器）
依赖管理：通过npm（package.json）管理
核心库：@supabase/supabase-js、pg（node-postgres）、zod（验证）、commander（命令行参数）、@modelcontextprotocol/sdk（MCP服务器框架）。

📄 许可证

本项目采用MIT许可证。有关详细信息，请参阅LICENSE文件。

0 条评论
分类：开发