supabase-mcp客户端配置教程：JSON格式与服务器连接步骤

2026-01-29 13:26:15 栏目：最新资讯 3 阅读

supabase-mcp客户端配置教程：JSON格式与服务器连接步骤

【免费下载链接】supabase-mcp Connect Supabase to your AI assistants 项目地址: https://gitcode.com/GitHub_Trending/supab/supabase-mcp

配置文件基础结构

supabase-mcp客户端配置基于JSON格式的服务器描述文件，核心配置文件为server.json。该文件遵循MCP协议规范，定义了服务器元信息、包依赖和运行时参数。基础结构包含以下关键节点：

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "com.supabase/mcp",
  "description": "MCP server for interacting with the Supabase platform",
  "version": "0.5.5",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "@supabase/mcp-server-supabase",
      "transport": { "type": "stdio" },
      "runtime_arguments": [],
      "environment_variables": []
    }
  ]
}

核心配置项详解

服务器元信息

配置项	说明	示例值
`name`	服务器唯一标识	`com.supabase/mcp`
`version`	协议版本号	`0.5.5`
`status`	运行状态	`active`
`repository`	代码仓库信息	`{"url": "...", "source": "github"}`

运行时参数配置

runtime_arguments节点定义了启动参数，常用配置包括：

"runtime_arguments": [
  {
    "type": "named",
    "name": "--project-ref",
    "description": "Supabase项目引用ID",
    "format": "string",
    "is_required": false
  },
  {
    "type": "named",
    "name": "--read-only",
    "description": "启用只读模式",
    "format": "boolean",
    "is_required": false
  }
]

环境变量设置

关键环境变量在environment_variables中定义，其中必须配置的访问令牌：

"environment_variables": [
  {
    "name": "SUPABASE_ACCESS_TOKEN",
    "description": "Supabase API个人访问令牌",
    "is_required": true,
    "is_secret": true
  }
]

服务器连接步骤

1. 准备访问令牌

登录Supabase控制台，在账户设置中生成个人访问令牌。该令牌需要项目管理权限，对应配置文件中的SUPABASE_ACCESS_TOKEN环境变量。

2. 配置JSON文件

创建或修改server.json，添加项目特定参数：

{
  "packages": [
    {
      "runtime_arguments": [
        {
          "name": "--project-ref",
          "value": "your-project-ref"  // 添加实际项目ID
        },
        {
          "name": "--features",
          "value": "auth,storage"      // 启用所需功能模块
        }
      ]
    }
  ]
}

3. 启动连接测试

使用npm命令启动MCP服务器进行连接测试：

cd packages/mcp-server-supabase && npx @supabase/mcp-server-supabase

高级配置与故障排除

分支管理配置

在生产环境中，建议使用开发分支进行配置测试，参考生产环境文档中的分支管理流程：

创建开发分支：调用create_branch工具
应用配置变更：使用apply_migration工具
合并到生产：通过merge_branch工具部署

常见连接问题

错误类型	排查方向	解决方案
认证失败	检查访问令牌有效性	重新生成SUPABASE_ACCESS_TOKEN
连接超时	网络连通性测试	验证API URL和端口可访问性
参数错误	检查runtime_arguments格式	使用JSON校验工具验证配置文件

配置示例

完整配置示例可参考server.json文件，典型生产配置包含：

{
  "name": "com.supabase/mcp",
  "version": "0.5.5",
  "status": "active",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "@supabase/mcp-server-supabase",
      "runtime_arguments": [
        {"name": "--project-ref", "value": "abc123"},
        {"name": "--read-only", "value": false}
      ],
      "environment_variables": [
        {"name": "SUPABASE_ACCESS_TOKEN", "value": "your-token-here"}
      ]
    }
  ]
}

配置验证工具

可使用MCP提供的工具验证配置正确性：

# 检查配置文件格式
npx @supabase/mcp-utils validate-config server.json

# 测试服务器连接
npx @supabase/mcp-server-supabase test-connection

详细工具使用方法参见mcp-utils文档。

最新资讯