Supabase MCP 服务器实施计划

本文档概述了创建连接到 Supabase 的模型上下文协议 (MCP) 服务器的计划，允许 GitHub Copilot 等 AI 助手与您的 Supabase 数据库进行交互。

概述

Supabase MCP 服务器将充当 AI 助手（例如 GitHub Copilot）和 Supabase 数据库之间的桥梁。这使得 AI 能够：

了解数据库架构
了解表和关系
协助撰写查询
提供与您的数据模型相关的上下文感知建议

先决条件

已安装 Node.js 18+
npm 或 yarn 包管理器
带有管理员 API 密钥的 Supabase 项目
支持 Copilot/MCP 的 VS Code
Git

实施步骤

1. 创建服务器包

mkdir mcp-server-supabase cd mcp-server-supabase npm init -y

2.安装依赖项

npm install @supabase/supabase-js @modelcontextprotocol/server dotenv

3. 基本服务器结构

创建以下文件：

src/index.js - 主入口点
src/supabase-client.js - Supabase 连接处理
src/schema-provider.js - 数据库模式提取
src/query-handler.js - 安全查询执行
.env.example - 环境变量模板
config.js - 配置管理

4. 服务器实现细节

src/index.js

该文件将初始化 MCP 服务器并连接组件：

const { MCPServer } = require('@modelcontextprotocol/server'); const { getSupabaseClient } = require('./supabase-client'); const { SchemaProvider } = require('./schema-provider'); const { QueryHandler } = require('./query-handler'); const config = require('./config'); async function main() { try { // Initialize Supabase client const supabaseClient = getSupabaseClient(config.supabase.url, config.supabase.key); // Create providers const schemaProvider = new SchemaProvider(supabaseClient); const queryHandler = new QueryHandler(supabaseClient, config.security.allowedQueries); // Initialize MCP server const server = new MCPServer({ name: 'mcp-server-supabase', version: '1.0.0', }); // Register handlers server.registerHandler('getSchema', async () => { return await schemaProvider.getFullSchema(); }); server.registerHandler('getTableInfo', async (params) => { return await schemaProvider.getTableInfo(params.tableName); }); server.registerHandler('executeQuery', async (params) => { return await queryHandler.execute(params.query, params.params); }); // Start the server await server.start(); console.log('MCP Supabase server is running'); } catch (error) { console.error('Failed to start MCP server:', error); process.exit(1); } } main();

src/supabase-client.js

const { createClient } = require('@supabase/supabase-js'); function getSupabaseClient(url, apiKey) { if (!url || !apiKey) { throw new Error('Supabase URL and API key must be provided'); } return createClient(url, apiKey, { auth: { persistSession: false }, }); } module.exports = { getSupabaseClient };

src/schema-provider.js

class SchemaProvider { constructor(supabaseClient) { this.supabase = supabaseClient; } async getFullSchema() { // Query Supabase for full database schema const { data, error } = await this.supabase .rpc('get_schema_information', {}); if (error) throw new Error(`Failed to get schema: ${error.message}`); return data; } async getTableInfo(tableName) { // Get detailed information about a specific table const { data, error } = await this.supabase .rpc('get_table_information', { table_name: tableName }); if (error) throw new Error(`Failed to get table info: ${error.message}`); return data; } } module.exports = { SchemaProvider };

src/query-handler.js

class QueryHandler { constructor(supabaseClient, allowedQueryTypes = ['SELECT']) { this.supabase = supabaseClient; this.allowedQueryTypes = allowedQueryTypes; } validateQuery(queryString) { // Basic SQL injection prevention and query type validation const normalizedQuery = queryString.trim().toUpperCase(); // Check if the query starts with allowed query types const isAllowed = this.allowedQueryTypes.some( type => normalizedQuery.startsWith(type) ); if (!isAllowed) { throw new Error(`Query type not allowed. Allowed types: ${this.allowedQueryTypes.join(', ')}`); } return true; } async execute(queryString, params = {}) { // Validate query before execution this.validateQuery(queryString); // Execute the query through Supabase const { data, error } = await this.supabase .rpc('execute_query', { query_string: queryString, query_params: params }); if (error) throw new Error(`Query execution failed: ${error.message}`); return data; } } module.exports = { QueryHandler };

配置.js

require('dotenv').config(); module.exports = { supabase: { url: process.env.SUPABASE_URL, key: process.env.SUPABASE_SERVICE_KEY, }, server: { port: process.env.PORT || 3000, }, security: { allowedQueries: process.env.ALLOWED_QUERY_TYPES ? process.env.ALLOWED_QUERY_TYPES.split(',') : ['SELECT'], } };

.env.示例

SUPABASE_URL=https://your-project-ref.supabase.co SUPABASE_SERVICE_KEY=your-service-key PORT=3000 ALLOWED_QUERY_TYPES=SELECT

5. Supabase 数据库功能

您需要在 Supabase 中创建这些存储过程：

get_schema_information() - 返回数据库模式
get_table_information(table_name TEXT) - 返回有关特定表的信息
execute_query(query_string TEXT, query_params JSONB) - 安全执行查询

服务器架构

┌─────────────────────┐ ┌───────────────────┐ │ │ │ │ │ VS Code + Copilot │◄────►│ MCP Protocol │ │ │ │ │ └─────────────────────┘ └─────────┬─────────┘ │ ▼ ┌─────────────────────┐ │ │ │ Supabase MCP Server │ │ │ └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ │ │ Supabase Database │ │ │ └─────────────────────┘

配置

将 Supabase MCP 服务器添加到你的 VS Code settings.json ：

"mcp": { "inputs": [], "servers": { // ...existing servers... "mcp-server-supabase": { "command": "node", "args": [ "/path/to/mcp-server-supabase/src/index.js" ], "env": { "SUPABASE_URL": "https://your-project-ref.supabase.co", "SUPABASE_SERVICE_KEY": "your-service-key", "ALLOWED_QUERY_TYPES": "SELECT" } } } }

安全注意事项

API密钥管理：
- 使用具有最低所需权限的范围 API 密钥
- 安全存储 API 密钥，无需进行版本控制
- 考虑使用密钥轮换策略
查询限制：
- 为了安全起见，默认为仅选择
- 考虑实施查询允许列表方法
- 添加速率限制以防止滥用
数据保护：
- 避免暴露 PII 或敏感数据
- 在 Supabase 中实现行级安全性
- 考虑为敏感字段添加数据屏蔽

安装指南

本地开发

克隆存储库
git clone https://github.com/yourusername/mcp-server-supabase.git cd mcp-server-supabase
安装依赖项
npm install
从示例创建.env文件
cp .env.example .env
使用你的 Supabase 凭证编辑.env
启动服务器
node src/index.js

VS Code 集成

使用服务器配置更新 VS Code settings.json
重启 VS Code
在 VS Code MCP 面板中验证服务器是否正在运行

使用示例

集成后，您可以通过多种方式使用 Supabase MCP 服务器：

模式探索：
What tables do I have in my Supabase database?
表格信息：
What columns are in the users table?
查询协助：
Help me write a query to get all users who signed up in the last 7 days

故障排除

服务器无法启动

检查你的 Node.js 版本（应为 18 岁以上）
验证您的 Supabase 凭据
检查终端中的错误日志

架构未加载

验证您的 Supabase 服务密钥是否具有必要的权限
检查数据库函数是否正确创建

VS Code 无法连接

检查settings.json中的服务器路径是否正确
配置更改后重新启动 VS Code
验证服务器进程是否正在运行

Supabase MCP Server