Supabase数据库MCP服务器

Supabase MCP服务器

模型上下文协议（MCP）服务器，提供AI助手和Supabase数据库之间的无缝集成。该服务器使LLM能够通过标准化、文档完善的工具在任何Supabase数据库上执行CRUD操作。

🚀 特性

• 完整的CRUD操作：读取、创建、更新和删除任何辅助数据库表中的记录
• 高级过滤：支持具有多种过滤条件的复杂查询
• 安全第一：针对破坏性操作的内置安全检查
• 类型安全：完整的类型提示和Pydantic验证
• 全面的错误处理：详细的错误消息和日志记录
• 灵活查询：支持分页、排序和列选择
• 升级支持：在单个操作中插入或更新记录

📋 先决条件

• Python 3.11或更高版本
• Supabase项目（自托管或云）
• 为服务角色密钥赋予适当的权限

🛠️ 安装

1. 克隆或下载项目:

   复制

   git clone <repository-url>
   cd supabase-mcp-server
   

2. 安装依赖项:

   复制

   pip install -r requirements.txt
   

3. 设置环境变量:

   复制

   cp .env.example .env
   # Edit .env with your Supabase credentials
   

4. 配置您的环境: 编辑 .env 使用您的Supabase凭据文件：

   复制

   SUPABASE_URL=https://your-project-id.supabase.co
   SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
   

🔧 配置

环境变量

编辑 .env 使用您的配置文件：

# Required: Your existing Supabase instance
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

# Optional: Server configuration
LOG_LEVEL=INFO

查找您的Supabase凭据

1. 转到您的Supabase项目仪表板
2. 引导到 设置 → API
3. 复制 项目Url 为了 SUPABASE_URL
4. 复制 服务角色机密 为了 SUPABASE_SERVICE_ROLE_KEY

⚠️ 重要：使用 service_role 关键，而不是 anon 密钥，因为它具有完全的数据库访问权限。

📁 GitHub存储库设置

🔗 完整的GitHub设置和SSH部署指南

快速设置：

1. 创建GitHub存储库
2. 推送代码： git init && git add . && git commit -m "Initial commit" && git push
3. SSH部署： git clone YOUR_REPO && cd PROJECT && ./scripts/deploy.sh

💡 SSH快速部署参考 -3命令部署

🚀 用法

地方发展

运行服务器

python src/server.py

服务器将从stdio传输开始，这是MCP服务器的标准。

在Claude Desktop中安装

1. 添加到您的Claude Desktop MCP配置中：
   复制

   {
     "servers": {
       "supabase": {
         "command": "python",
         "args": ["path/to/supabase-mcp-server/src/server.py"],
         "env": {
           "SUPABASE_URL": "https://your-project-id.supabase.co",
           "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
         }
       }
     }
   }
   

与MCP检查器一起使用

对于开发和测试：

npx @modelcontextprotocol/inspector python src/server.py

🐳 云部署

在几分钟内部署到您的云Docker实例！

快速部署（自动化）

1. 将文件上传到您的云服务器:

   复制

   scp -r supabase-mcp-server/ user@your-server.com:/home/user/
   

2. SSH和部署:

   复制

   ssh user@your-server.com
   cd supabase-mcp-server
   chmod +x scripts/deploy.sh
   ./scripts/deploy.sh
   

手动部署

# Configure environment
cp .env.production .env
nano .env  # Add your Supabase credentials

# Deploy MCP server only (recommended)
docker-compose -f docker-compose.mcp-only.yml up -d

# Or deploy full stack (includes self-hosted Supabase)
docker-compose up -d

访问：服务器在端口8085上可用

📖 完整部署指南 -包括安全性、监控、扩展和故障排除

🔨 可用工具

1.读取表行

通过过滤、排序和分页从任何表中查询数据。

用法：“显示状态为‘活动’的所有用户”

{
  "table_name": "users",
  "filters": [{"column": "status", "operator": "eq", "value": "active"}],
  "order_by": "created_at",
  "limit": 10
}

2.创建表记录

使用可选的追加销售功能将新记录插入任何表中。

用法：“创建一个名为'John'和电子邮件的新用户”john@example.com'"

{
  "table_name": "users",
  "records": [{"name": "John", "email": "john@example.com"}]
}

3.更新表格记录

根据指定条件修改现有记录。

用法：“将id为123的任务的状态更新为“已完成””

{
  "table_name": "tasks",
  "set_data": {"status": "completed"},
  "where_conditions": [{"column": "id", "operator": "eq", "value": 123}]
}

4.删除表格记录

通过安全检查和确认从表中删除记录。

用法：“删除2023年之前创建的所有非活动用户”

{
  "table_name": "users",
  "where_conditions": [
    {"column": "status", "operator": "eq", "value": "inactive"},
    {"column": "created_at", "operator": "lt", "value": "2023-01-01"}
  ],
  "confirm_delete": true
}

🔍 过滤器操作员

服务器支持多种过滤运算符进行精确查询：

🧪 测试

运行测试套件：

pytest tests/

跑步覆盖：

pytest tests/ --cov=src

🛡️ 安全功能

• 环境变量验证：确保设置了所需的凭据
• 输入验证：Pydantic模型验证所有输入数据
• 安全检查：需要确认破坏性操作
• 何处条款要求：更新和删除需要明确的条件
• 错误处理：全面的错误处理和详细的日志记录

📁 项目结构

supabase-mcp-server/
├── src/
│   └── server.py           # Main MCP server implementation
├── tests/
│   └── test_server.py      # Comprehensive test suite
├── requirements.txt        # Python dependencies
├── .env.example           # Environment variables template
├── README.md              # This file
├── PLANNING.md            # Project planning and architecture
├── TASK.md               # Task breakdown and progress
└── GLOBAL_RULES.md       # Development rules and standards

🔄 示例使用场景

场景1：内容管理

“按发布日期排序，显示今年发布的所有博客文章”

场景2：用户管理

“创建新的管理员用户并更新其权限”

场景3：数据清理

“查找并删除所有过期的会话令牌”

场景4：分析

“按注册月份获取过去一年的用户数”

🐛 故障排除

常见问题

1. 未设置环境变量

   • 错误：“缺少环境变量”
   • 解决方案：确保 .env 文件存在且正确 SUPABASE_URL 和 SUPABASE_SERVICE_ROLE_KEY

2. 数据库连接失败

   • 错误：“初始化Supabase客户端失败”
   • 解决方案：验证您的Supabase URL和服务角色密钥是否正确

3. 权限不足

   • 错误：各种与权限相关的错误
   • 解决方案：确保您的服务角色密钥对您正在访问的表具有适当的权限

4. 找不到表

   • 错误：表特定错误
   • 解决方案：验证Supabase数据库中是否存在表名

📚 发展

代码的风格

• 遵循PEP 8标准
• 对所有函数使用类型提示
• 包含全面的文档字符串
• 每个文件最多500行

测试要求

• 最低95%的测试覆盖率
• 测试所有CRUD操作
• 包括边缘情况和错误场景
• 对所有测试使用pytest

🤝 贡献

1. 遵循中定义的全局规则 GLOBAL_RULES.md
2. 在提交更改之前，确保所有测试都通过
3. 更新任何新功能的文档
4. 添加适当的错误处理和日志记录

📄 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

🙏 致谢

• 与 模型上下文协议
• 使用 Supabase Python客户端
• 基于 FastMCP 框架