Supabase Coolify MCP Server

Supabase Coolify MCP服务器

](https://www.npmjs.com/package/supabase-coolify-mcp-server) ](https://www.npmjs.com/package/supabase-coolify-mcp-server)   ](https://nodejs.org)

⚡ 一键安装

直接安装在您最喜欢的AI编码工具中：

  

克劳德代码：

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

注： 安装后，您需要配置所需的环境变量。看 配置 在......下面

______________________________________________________________________

一个全面的TypeScript MCP（模型上下文协议）服务器，用于管理Coolify上的自托管Supabase。该服务器使AI代理能够轻松地全面部署迁移、推送边缘功能、配置服务和管理Supabase部署。

** • 📚 文档 • 🚀 快速开始**

🚀 特性

数据库管理

• 数据库迁移：部署、跟踪、回滚和管理数据库迁移
• 迁移回滚：通过降低SQL支持安全回滚迁移
• Supabase CLI集成：完全集成CLI以进行本地开发和部署
• 边缘功能：部署、调用、监视和删除边缘功能
• 存储管理：创建和管理存储桶
• 身份验证配置：配置身份验证提供程序和设置
• 实时配置：管理实时服务设置
• 健康监测：检查所有Supabase服务的状态
• 类型生成：从数据库架构生成TypeScript类型

生产特点

• 输入验证：对所有工具输入进行基于Zod的验证
• 健康检查：自动启动检查和验证工具
• 错误处理：包含故障排除提示的全面错误消息
• 类型安全：全面支持TypeScript

冷却集成

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

部署自动化

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

📋 先决条件

• Node.js>=18.0.0
• Coolify实例（自托管或云）
• 使用适当权限冷却API令牌
• 自托管的Supabase实例（或准备部署的实例）

🔧 安装

方法1:NPM（推荐）

通过NPM进行全局安装：

npm install -g supabase-coolify-mcp-server

或者直接与npx一起使用（无需安装）：

npx 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. 导航到“密钥和令牌”>“API令牌”
3. 点击“创建新令牌”
4. 选择权限（建议： * 完全访问）
5. 复制生成的令牌

Supabase服务角色键

对于自托管的Supabase：

1. 登录您的Supabase仪表板
2. 前往“设置”>“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配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\ 视窗: %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"
}

边缘功能工具

list_edge_functions

列出所有已部署的边缘功能。

deploy_edge_function

部署新的边缘功能。

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

delete_edge_function

删除边函数。

{
  "name": "hello-world"
}

get_edge_function_logs

获取边缘函数的日志。

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

invoke_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）的运行状况。

此综合工具检查：

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

退货： 详细的健康报告，对发现的任何问题提出建议。

看 文档/验证.md 获取完整的验证指南。

冷却管理工具

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模式自动）
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"

看 文档/验证.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中的实际令牌→ 密钥和令牌

大写键错误

❌ Supabase Authentication: Invalid service role key

修复：确保您正在使用 service_role 钥匙，不是匿名钥匙！\ 从以下网址获取：Supabase Dashboard→ 设置→ API → service_role 钥匙

连接失败

❌ Coolify Connection: ECONNREFUSED

修复：验证Coolify是否正在运行，并且可以在配置的URL上访问

获取凭据

Coolify API代币:

1. Coolify仪表板→ 个人资料→ 密钥和令牌→ API令牌
2. 点击“创建新令牌”
3. 复制令牌（您将不会再看到它！）
4. 增添 .env 作为 COOLIFY_API_TOKEN

Supabase服务角色键:

• Supabase云：仪表板→ 设置→ API → Copy service_role 钥匙
• 自托管：检查Coolify部署环境变量 SERVICE_ROLE_KEY

快速入门指南

有关详细的故障排除，请参阅：

• START_HERE.md -快速开始诊断
• 诊断_NOW.md -逐步诊断
• 故障排除.md -全面的故障排除指南

🐛 故障排除

常见问题

1.缺少环境变量

错误: Missing required environment variables: COOLIFY_API_URL, COOLIFY_API_TOKEN

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

2.连接失败

错误: Failed to connect to Coolify API

解决方案:

• 验证Coolify实例是否正在运行
• 检查API URL是否正确（包括 http:// 或 https://)
• 确保API令牌具有正确的权限
• 检查网络连接

3.身份验证失败

错误: Unauthorized 或 401

解决方案:

• 验证API令牌是否正确
• 支票令牌尚未过期
• 确保令牌具有所需的权限

4.MCP服务器未出现

解决方案:

• 重新启动克劳德桌面
• 检查配置文件路径是否适合您的操作系统
• 验证配置中的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.部署边缘功能

deploy_edge_function({
  name: "send-email",
  code: `
    import { serve } from 'https://deno.land/std@0.168.0/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 })

🤝 贡献

欢迎投稿！请随时提交拉取请求。

📄 许可证

麻省理工学院

🔗 链接

• NPM包:
• GitHub存储库:
• 冷却: https://coolify.io -自助式Heroku/Netlify替代方案
• Supabase: https://supabase.com -开源Firebase替代品
• 模型上下文协议: https://modelcontextprotocol.io -MCP规范

📞 支持

对于问题和疑问：

• 检查 故障排除部分
• 审查 冷却 和 Supabase 文档

______________________________________________________________________

备注：此MCP服务器专为Coolify上的自托管Supabase实例而设计。它提供了全面的管理功能，同时通过环境变量和适当的令牌处理来维护安全性。