Supabase Coolify Mcp Server

Supabase Coolify MCP 服务

⚡ 一键安装

直接安装到你喜爱的 AI 编码工具中：

Claude Code：

claude mcp add supabase-coolify -- npx -y supabase-coolify-mcp-server

注意： 安装后，你需要配置所需的环境变量。请参阅下方的配置。

---

一款功能全面的 TypeScript MCP（Model Context Protocol）服务，用于在 Coolify 上管理可自托管的 Supabase。此服务支持 AI Agent 轻松完成迁移部署、推送边缘函数、配置服务以及管理 Supabase 部署。

📦 NPM 包 • 📚 文档 • 🚀 快速开始

🚀 功能

Supabase 管理

• 数据库迁移：部署、跟踪、回滚和管理数据库迁移
• 迁移回滚：借助 down SQL 支持，安全地回滚迁移
• Supabase CLI 集成：全面集成 CLI，支持本地开发和部署
• 边缘函数：部署、调用、监控和删除边缘函数
• 存储管理：创建和管理存储桶
• Auth 配置：配置身份验证提供方和设置
• Realtime 配置：管理实时服务设置
• 运行状况监控：检查所有 Supabase 服务的状态
• 类型生成：根据数据库架构生成 TypeScript 类型

生产环境功能

• 输入验证：使用基于 Zod 的验证来校验所有工具输入
• 运行状况检查：自动执行启动检查，并提供验证工具
• 错误处理：提供全面的错误消息和故障排除提示
• 类型安全：全程提供完整的 TypeScript 支持

Coolify 集成

• 应用管理：列出、部署、启动、停止和重启应用
• 服务管理：控制 Coolify 服务
• 数据库管理：管理由 Coolify 托管的数据库
• 环境变量：安全地更新应用配置
• 日志：访问应用日志以进行调试

部署自动化

• 一键部署：在 Coolify 上部署完整的 Supabase 实例
• 配置管理：动态更新部署设置
• 状态监控：跟踪部署的运行状况和状态

📋 前提条件

• Node.js >= 18.0.0
• 一个 Coolify 实例（可自托管或使用云端实例）
• 具有相应权限的 Coolify API 令牌
• 一个可自托管的 Supabase 实例（或准备好部署一个实例）

🔧 安装

方法 1：NPM（推荐）

通过 NPM 全局安装：

npm install -g supabase-coolify-mcp-server

或者使用 npx 直接运行（无需安装）：

npx supabase-coolify-mcp-server

软件包： https://www.npmjs.com/package/supabase-coolify-mcp-server

方法 2：从源代码构建

从 GitHub 克隆并构建：

git clone https://github.com/dj-pearson/supabase-coolify-mcp-server.git
cd supabase-coolify-mcp-server
npm install
npm run build

⚙️ 配置

环境变量

创建 .env 文件，或设置以下环境变量：

# Required: Coolify Configuration
COOLIFY_API_URL=http://localhost:8000
COOLIFY_API_TOKEN=your-coolify-api-token-here

# Required: Supabase Configuration
SUPABASE_URL=https://your-supabase-instance.example.com
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key

# Optional: Coolify Team
COOLIFY_TEAM_ID=optional-team-id

# Optional: Supabase Additional Config
SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_PROJECT_ID=your-project-id
SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_FUNCTIONS_URL=https://your-supabase-instance.example.com/functions/v1

# Optional: Direct Database Access
SUPABASE_DB_HOST=localhost
SUPABASE_DB_PORT=5432
SUPABASE_DB_NAME=postgres
SUPABASE_DB_USER=postgres
SUPABASE_DB_PASSWORD=your-db-password

获取 API 令牌

Coolify API 令牌

1. 登录 Coolify 实例
2. 前往“Keys & Tokens” > “API tokens”
3. 点击“Create New Token”
4. 选择权限（推荐：使用 * 获得完整访问权限）
5. 复制生成的令牌

Supabase 服务角色密钥

对于可自托管的 Supabase：

1. 登录 Supabase 控制面板
2. 前往 Settings > API
3. 复制 service_role 密钥（请妥善保管！）

也可以从 Supabase 部署环境变量中获取：

echo $SERVICE_ROLE_KEY

🎯 用法

⚠️ 重要：需要设置环境变量

MCP 服务需要环境变量才能连接到 Coolify 和 Supabase。

推荐设置方式（适用于所有用户）：

直接将环境变量添加到 MCP 配置中：

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "npx",
      "args": ["-y", "supabase-coolify-mcp-server"],
      "env": {
        "COOLIFY_API_URL": "http://your-coolify-url:8000",
        "COOLIFY_API_TOKEN": "your-actual-token",
        "SUPABASE_URL": "https://your-supabase-url.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-actual-service-role-key"
      }
    }
  }
}

请将占位值替换为你的实际凭据！

---

📖 配置选项

此服务支持三种提供环境变量的方式（按优先级排序）：

1. MCP 配置中的 env 部分 ⭐ 推荐——适用于所有用户，配置自包含
2. 系统环境变量——适合希望将凭据放在配置之外的高级用户
3. 使用包装脚本的 .env 文件——仅适用于本地开发（不适合扩展）

各方式的详细设置说明请参阅： MCP_CONFIGURATION.md

常见错误： ❌ 保留 https://your-supabase-instance.example.com 等占位值
解决方案： ✅ 将所有占位值替换为你的实际 URL 和凭据！

---

使用 Claude Desktop

将以下内容添加到 Claude Desktop 配置中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%/Claude/claude_desktop_config.json

使用 NPX（推荐——始终使用最新版本）

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "npx",
      "args": ["-y", "supabase-coolify-mcp-server"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-coolify-api-token",
        "SUPABASE_URL": "https://your-supabase-instance.example.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

使用全局安装

首先进行全局安装：

npm install -g supabase-coolify-mcp-server

然后进行配置：

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "supabase-coolify-mcp",
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-coolify-api-token",
        "SUPABASE_URL": "https://your-supabase-instance.example.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

开发模式

# Using environment variables
export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-token"
export SUPABASE_URL="https://your-instance.example.com"
export SUPABASE_SERVICE_ROLE_KEY="your-key"

npm run dev

# Or with .env file
npm run dev

运行构建版本

npm run build
npm start

🛠️ 可用工具

数据库迁移工具

list_migrations

列出所有数据库迁移及其状态。

// No parameters required

deploy_migration

部署新的数据库迁移。

{
  "sql": "CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT);",
  "name": "create_users_table"
}

execute_sql

在 Supabase 数据库上执行原始 SQL 查询。

{
  "sql": "SELECT * FROM users LIMIT 10;"
}

get_migration_status

获取特定迁移的状态。

{
  "version": "20231201120000"
}

Edge Functions 工具

list_edge_functions

列出所有已部署的 Edge Functions。

deploy_edge_function

部署新的 Edge Function。

{
  "name": "hello-world",
  "code": "export default function handler(req) { return new Response('Hello World'); }",
  "verify_jwt": true
}

delete_edge_function

删除 Edge Function。

{
  "name": "hello-world"
}

get_edge_function_logs

获取 Edge Function 的日志。

{
  "name": "hello-world",
  "limit": 100
}

invoke_edge_function

调用 Edge Function。

{
  "name": "hello-world",
  "payload": { "key": "value" }
}

存储工具

list_storage_buckets

列出所有存储桶。

create_storage_bucket

创建新的存储桶。

{
  "id": "avatars",
  "public": true,
  "file_size_limit": 5242880
}

delete_storage_bucket

删除存储桶。

{
  "id": "avatars"
}

身份验证与配置工具

get_auth_config

获取身份验证配置。

update_auth_config

更新身份验证配置。

{
  "config": {
    "site_url": "https://myapp.com",
    "enable_signup": true
  }
}

check_supabase_health

检查所有 Supabase 服务的运行状况。

get_supabase_version

获取 Supabase 版本信息。

verify_setup ⭐

验证系统设置并检查所有服务（Coolify、Supabase、CLI）的健康状况。

这个综合工具会检查：

• Coolify 连接和身份验证
• Supabase 连接和身份验证
• 数据库可访问性
• CLI 是否可用
• 响应时间和服务状态

**返回：**详细的健康报告，并针对发现的问题提供建议。

完整验证指南请参阅 docs/VERIFICATION.md。

Coolify 管理工具

list_coolify_applications

列出所有 Coolify 应用。

get_coolify_application

获取特定应用的详细信息。

{
  "uuid": "app-uuid-here"
}

update_coolify_application_env

更新应用环境变量。

{
  "uuid": "app-uuid-here",
  "env": {
    "NODE_ENV": "production",
    "API_KEY": "secret"
  }
}

deploy_coolify_application

部署 Coolify 应用。

{
  "uuid": "app-uuid-here"
}

start_coolify_application / stop_coolify_application / restart_coolify_application

控制应用生命周期。

{
  "uuid": "app-uuid-here"
}

get_coolify_logs

获取应用日志。

{
  "uuid": "app-uuid-here",
  "lines": 100
}

部署工具

deploy_supabase_to_coolify

在 Coolify 上部署完整的 Supabase 实例。

{
  "name": "my-supabase",
  "config": {
    "postgres_version": "15",
    "enable_realtime": true,
    "enable_storage": true,
    "enable_auth": true,
    "custom_domain": "https://supabase.myapp.com",
    "environment_variables": {
      "CUSTOM_VAR": "value"
    }
  }
}

update_supabase_deployment

更新现有的 Supabase 部署。

{
  "uuid": "app-uuid-here",
  "config": {
    "enable_graphql": true
  }
}

get_deployment_status

获取 Supabase 部署状态。

{
  "uuid": "app-uuid-here"
}

📚 MCP 资源

该服务会向 MCP 客户端提供以下资源：

• supabase://migrations - 所有数据库迁移
• supabase://edge-functions - 所有边缘函数
• supabase://storage-buckets - 所有存储桶
• supabase://auth-config - 身份验证配置
• supabase://health - 服务健康状态
• coolify://applications - 所有 Coolify 应用
• coolify://services - 所有 Coolify 服务
• coolify://databases - 所有 Coolify 数据库

🔒 安全最佳实践

1. 切勿将 API 令牌提交到版本控制系统
2. 使用环境变量存储敏感数据
3. 将 API 令牌权限限制在最低所需范围
4. 定期轮换令牌
5. 仅在安全的服务器上使用服务角色密钥
6. 为边缘函数启用 JWT 验证
7. 验证所有输入（通过 Zod schemas 自动完成）
8. 在生产部署前验证设置
9. 为配置文件设置适当的文件权限：

chmod 600 ~/.env
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

🧪 测试与验证

构建和类型检查

# Run type checking
npm run typecheck

# Run linter
npm run lint

# Build project
npm run build

验证设置

启动服务后，验证所有功能是否正常：

# Start the server
npm start

# Then ask Claude:
"Run verify_setup to check if everything is configured correctly"

完整验证指南请参阅 docs/VERIFICATION.md。

🔍 诊断与测试

报告问题前，或遇到连接问题时，请使用内置诊断工具：

快速诊断

运行自动诊断工具，检查你的设置：

# Using npm
npm run diagnose

# Or on Windows
.\diagnose.ps1

# Or on Linux/Mac
./diagnose.sh

诊断工具会自动检查：

• ✅ .env 文件是否存在及其配置
• ✅ 所需环境变量
• ✅ Coolify API 连接和身份验证
• ✅ Supabase 连接和身份验证
• ✅ 所有 Supabase 服务的健康状况
• ✅ 网络连接

预期输出（正常运行时）

🟢 ALL CHECKS PASSED - MCP Server should work correctly

✅ Passed:   10
❌ Failed:   0
⚠️  Warnings: 0

常见诊断问题

缺少 .env 文件

❌ .env file NOT found!

修复方法：运行 cp env.example .env，然后编辑文件并填写你的凭据

占位值

❌ ENV: COOLIFY_API_TOKEN: Contains placeholder value

修复方法：将 your-coolify-api-token-here 替换为 Coolify Dashboard → Keys & Tokens 中的实际令牌

Supabase 密钥错误

❌ Supabase Authentication: Invalid service role key

修复方法：请确保使用 service_role 密钥，而不是 anon 密钥！
在此处获取：Supabase Dashboard → Settings → API → service_role 密钥

连接失败

❌ Coolify Connection: ECONNREFUSED

修复方法：确认 Coolify 正在运行，并可通过配置的 URL 访问

获取凭据

Coolify API Token：

1. Coolify Dashboard → Profile → Keys & Tokens → API Tokens
2. 点击“Create New Token”
3. 复制令牌（之后将无法再次查看！）
4. 将其添加到 .env 中，变量名为 COOLIFY_API_TOKEN

Supabase Service Role Key：

• Supabase Cloud：Dashboard → Settings → API → 复制 service_role 密钥
• 可自托管：在 Coolify 部署环境变量中查找 SERVICE_ROLE_KEY

快速入门指南

如需了解详细的故障排查方法，请参阅：

• START_HERE.md - 快速入门与诊断
• DIAGNOSE_NOW.md - 分步诊断
• TROUBLESHOOTING.md - 全面的故障排查指南

🐛 故障排查

常见问题

1. 缺少环境变量

错误：Missing required environment variables: COOLIFY_API_URL, COOLIFY_API_TOKEN

解决方案：确保已设置所有必需的环境变量。检查 .env 文件或 Claude Desktop 配置。

2. 连接失败

错误：Failed to connect to Coolify API

解决方案：

• 确认 Coolify 实例正在运行
• 检查 API URL 是否正确（包含 http:// 或 https://）
• 确保 API 令牌具有适当的权限
• 检查网络连接

3. 身份验证失败

错误：Unauthorized 或 401

解决方案：

• 确认 API 令牌正确
• 检查令牌是否已过期
• 确保令牌具有所需权限

4. 未显示 MCP 服务

解决方案：

• 重启 Claude Desktop
• 检查配置文件路径是否适用于你的操作系统
• 确认配置中的 JSON 语法正确
• 检查服务日志中的错误

调试模式

运行并输出调试信息：

DEBUG=* npm start

📖 示例用例

1. 部署新的 Supabase 实例

// Using the MCP tool
deploy_supabase_to_coolify({
  name: "production-supabase",
  config: {
    postgres_version: "15",
    enable_realtime: true,
    enable_storage: true,
    custom_domain: "https://api.myapp.com"
  }
})

2. 部署数据库迁移

deploy_migration({
  name: "add_user_profiles",
  sql: `
    CREATE TABLE user_profiles (
      id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
      user_id UUID REFERENCES auth.users(id),
      display_name TEXT,
      avatar_url TEXT,
      created_at TIMESTAMP DEFAULT NOW()
    );
  `
})

3. 部署 Edge Function

deploy_edge_function({
  name: "send-email",
  code: `
    import { serve } from 'https://deno.land/[email protected]/http/server.ts'
    
    serve(async (req) => {
      const { to, subject, body } = await req.json()
      // Send email logic here
      return new Response(JSON.stringify({ success: true }))
    })
  `,
  verify_jwt: true
})

4. 监控部署运行状况

// Check overall health
check_supabase_health()

// Get specific deployment status
get_deployment_status({ uuid: "your-app-uuid" })

// View logs
get_coolify_logs({ uuid: "your-app-uuid", lines: 100 })

🤝 参与贡献

欢迎贡献！请随时提交 Pull Request。

📄 许可证

MIT

🔗 链接

• NPM Package：https://www.npmjs.com/package/supabase-coolify-mcp-server
• GitHub Repository：https://github.com/dj-pearson/supabase-coolify-mcp-server
• Coolify：https://coolify.io - 可自托管的 Heroku/Netlify 替代方案
• Supabase：https://supabase.com - 开源 Firebase 替代方案
• Model Context Protocol：https://modelcontextprotocol.io - MCP 规范

📞 支持

如有问题或疑问：

• 在 GitHub 上创建问题
• 查看故障排查部分
• 查阅 Coolify 和 Supabase 文档

---

注意：此 MCP 服务专为在 Coolify 上运行的可自托管 Supabase 实例而设计。它在通过环境变量和妥善处理令牌来保障安全的同时，提供全面的管理功能。