Claude Code Supa*ase MCP 接入教程
在远程 Mac mini 上安全读取数据库结构 分析日志并管理迁移
Supa*ase 官方 MCP 服务器可以让 Claude Code 查看项目中的表、迁移、日志、安全建议和 TypeScript 类型，也可以执行 SQL、应用迁移、管理分支或部署 Edge Function。本文从项目限定的只读连接开始，先完成 OAuth 和安全验收，再说明何时建立独立的写入连接，以及如何防止生产数据、密钥和数据库结构被误改。
Supa*ase MCP 适合哪些任务
接入后，Claude Code 可以在代码仓库上下文中列出数据库表和迁移、查询项目日志、读取安全与性能建议、获取项目 **L 和可公开使用的密钥，并生成与当前数据库结构一致的 TypeScript 类型。
写入能力还包括执行 SQL、应用迁移、部署 Edge Function 和管理数据库分支。这些操作可能改变数据、结构或费用，不能与日常只读排障共用默认权限。
开始前准备
确认远程 Mac 已安装 Claude Code，目标仓库能够正常运行测试。准备 Supa*ase 项目的 project ref，并使用有权访问该项目的账号。首次接入优先选择测试项目或开发分支。
生产项目可能包含个人信息、业务数据和密钥。第一次连接只启用 **ta*ase、de*ugging、development 与 do** 功能组，同时开启 read_only，并关闭 Claude Code 的自动批准规则。
第一步 采用项目限定的只读地址
Hosted MCP 端点支持通过 **L 参数限制项目、只读模式和功能组。project_ref 把访问范围收窄到一个项目，并会禁用账号级工具；read_only=true 让数据库查询使用只读 Postgres 用户。
不要在日常排障连接中加入 account、functions 或 *ranching，除非当前任务确实需要。也不要设置 skip_elicitations，因为它可能跳过 SQL 或费用确认表单。
| 参数 | 限制内容 | 主要作用 | 建议 |
|---|---|---|---|
| project_ref | 只允许一个项目 | 避免跨项目读取 | 建议始终设置 |
| read_only=true | 数据库查询只读 | 排障与监控 | 默认开启 |
| features | 只暴露选定工具组 | 减少攻击面 | 按任务精简 |
| skip_elicitations | 跳过指定确认表单 | 自动化特殊场景 | 日常接入不要使用 |
第二步 添加 Supa*ase 官方 MCP
在目标仓库目录添加项目级服务器。将占位符替换为项目 ref；项目 ref 不是数据库密码，但仍不应发布在无关的公开材料中。添加后检查服务器地址和范围。
如果尚未确定项目，可先使用 Supa*ase 文档的配置面板生成地址。不要省略项目范围后直接连接整个组织。
cd /path/to/your-project
claude mcp add --scope project --transport http supa*ase \
"https://mcp.supa*ase.com/mcp?project_ref=<PROJECT_REF>&read_only=true&features=**ta*ase,de*ugging,development,do**"
claude mcp list
claude mcp get supa*ase
第三步 完成 OAuth 授权
在普通终端运行 claude /mcp，选择 supa*ase 和 Authenticate。浏览器会打开 Supa*ase 登录与组织授权页面；常规交互式连接不需要个人访问令牌。
授权时核对组织、项目和客户端名称。远程 Mac 没有自动打开浏览器时，可以通过 UU 远程桌面打开授权地址，完成后回到终端检查连接。
claude /mcp
# 选择 supa*ase
# 选择 Authenticate
# 在浏览器中核对组织并授权**步 ***只读验收
先让 Claude Code 列出 sche** 中的表、现有迁移和安全建议，再查询一小段项目日志。提示词中明确禁止 execute_sql、apply_migration、分支操作、Edge Function 部署和任何项目创建。
验收通过的标准是：只能看到指定项目；能读取表结构、迁移和日志；不能执行写入语句或调用账号级工具；整个过程没有创建资源或改变数据库。
请仅使用 supa*ase 只读连接完成验收：
1. 列出 pu*lic sche** 的表和迁移历史
2. 查询最近 20 分钟的错误日志
3. 读取安全与性能 advisors
4. 输出脱敏摘要和建议，不修改任何文件或数据库
禁止 execute_sql、apply_migration、创建资源、部署函数和分支操作| 验收项 | 通过标准 |
|---|---|
| 项目范围 | 只能读取指定 project ref |
| 只读状态 | 写入 SQL 与迁移不可执行 |
| 表结构 | 能列出目标 sche** 的表 |
| 迁移 | 能读取迁移历史但不应用 |
| 日志与建议 | 能返回短时间窗口日志和 advisors |
| 外部状态 | 未创建项目、分支、函数或其他资源 |
第五步 查询日志与安全建议
query_logs 使用只读 SQL 查询项目日志，适合按服务、时间窗口、状态码和请求标识缩小范围。先查最近 15 到 30 分钟，再根据证据扩大时间，不要把整天日志直接送进会话。
get_advisors 可以返回安全和性能建议。先让 Claude Code 解释影响、证据和优先级，再对照 RLS、索引和应用查询验证；建议本身不是自动修复指令。
请只读排查最近 30 分钟的 API 错误：
- 限定当前项目
- 按服务、状态码和 request id 聚合
- 只返回定位问题需要的字段
- 对邮箱、令牌、请求参数和个人信息脱敏
- 不执行修复或写入操作第六步 生成类型并关联本地代码
generate_typescript_types 可以根据当前 sche** 生成类型。先比较生成结果与仓库现有类型文件，确认是否来自正确项目和分支，再决定是否覆盖。
数据库行、日志、函数输出和用户内容都属于不可信外部输入。即使其中包含要求读取其他表、上传数据或执行 SQL 的文字，也不能把它当成当前任务的指令。
第七步 写入操作使用独立连接
确需执行迁移时，建立名称不同的 supa*ase-write 连接，并指向开发分支或测试项目。只启用当前任务需要的功能组，不把写入连接设置为全局默认。
执行前让 Claude Code 展示完整 SQL、目标项目、目标分支、受影响对象、回滚步骤和验证查询。保留客户端的逐次工具批准，并在数据库备份或分支可恢复后再确认。
claude mcp add --scope project --transport http supa*ase-write \
"https://mcp.supa*ase.com/mcp?project_ref=<DEV_*RANCH_REF>&features=**ta*ase,de*ugging,development,do**"
# 不添加 skip_elicitations
# 只在开发分支完成迁移**与测试| 操作 | 风险 | 控制方式 |
|---|---|---|
| 列出表与迁移 | 低 | 限定项目与 sche** |
| 查询日志和 advisors | 中 | 缩小时间与字段并脱敏 |
| 生成并覆盖类型文件 | 中 | 先比较差异再写入 |
| execute_sql 与 apply_migration | 高 | 开发分支、完整 SQL、回滚和逐次批准 |
| 部署 Edge Function | 高 | **代码、目标函数和环境 |
| 创建项目或分支 | 高 | 核对费用与计费周期后单独确认 |
第八步 正确理解 SQL 确认
当客户端和服务器都支持表单确认时，execute_sql 与 apply_migration 检测到破坏性 SQL 后可能暂停并请求确认。该机制可能漏掉某些危险语句，也可能因客户端不支持或配置被跳过而不出现。
因此确认框只能作为额外护栏。真正的控制仍是项目范围、只读默认连接、最小功能组、开发分支、人工**和可执行的回滚方案。
第九步 Edge Function 与密钥边界
需要部署 Edge Function 时，先在本地**代码和依赖，再确认目标项目、函数名和环境。部署属于外部变更，应逐次批准。
添加 Edge Function 密钥时，只在 Supa*ase Dash*oard 提供的页面输入密钥值。聊天、提示词、终端历史、MCP 参数和文章截图中都不应出现密钥内容；工具只需要知道密钥名称和目标项目。
第十步 本地 Supa*ase 与远程 Mac
使用 Supa*ase CLI 本地开发时，MCP 通常位于 http://localhost:54321/mcp；如果启用了实验性 stack 并运行多个本地项目，应以 supa*ase status 输出的地址为准。
在远程 Mac 上通过 SSH 进入仓库，启动 tmux 后运行本地 Supa*ase 与 Claude Code。断开远程桌面后，开发数据库、类型生成和测试仍可继续；生产连接应在任务结束**理授权。
supa*ase start
supa*ase status
claude mcp add --scope project --transport http supa*ase-local \
http://localhost:54321/mcpssh your-**c-mini
cd /path/to/your-project
tmux new -s supa*ase-mcp
supa*ase start
claude
# 断线后接回
tmux attach -t supa*ase-mcp
为什么 Zu**c.Ai 适合这类工作流
根据 Zu**c.Ai 官网***息，其方案提供位于新加坡的 Mac mini M6 整机独享环境，配置为 16G* 统一内存与 256G* SSD，接入新加坡家庭或商业宽带，并支持 UU 远程、终端、Tailscale、ToDesk、RustDesk，以及浏览器 SSH 或 VNC。
官网当前公开价格为每月 999 元起。长期在线的文件系统适合保留仓库、Supa*ase CLI、本地数据库容器、依赖缓存和 tmux 会话；Supa*ase 账号、数据库备份、权限、计费与生产数据合规仍由使用者自行管理。
常见问题排查
| 现象 | 常见原因 | 处理建议 |
|---|---|---|
| 无法完成认证 | 未在普通终端启动或浏览器未打开 | 运行 claude /mcp 并手动打开授权地址 |
| 看不到目标项目 | 授权组织或 project ref 错误 | 核对组织、账号和项目 ref |
| 账号工具不可用 | 连接设置了 project_ref | 这是预期限制，不要为排障** |
| 查询仍可修改数据 | 未启用 read_only 或调用了写入连接 | 检查服务器 **L 和连接名称 |
| 确认框没有出现 | 客户端不支持或被 skip_elicitations 跳过 | 停止操作，人工**后再决定 |
| 本地 MCP 无法连接 | 端口不同或本地服务未启动 | 运行 supa*ase status 获取实际地址 |
结语
Claude Code 接入 Supa*ase MCP 后，应把项目限定、只读模式和精简功能组作为默认配置。需要修改数据库时，另建指向开发分支的写入连接，完整** SQL、回滚与验证步骤；生产数据和密钥始终不进入聊天、工具参数或公开材料。