TencentCloudBase/CloudBase-AI-Toolkit · 上手攻略

• 仓库：TencentCloudBase/CloudBase-AI-Toolkit
• 链接：https://github.com/TencentCloudBase/CloudBase-AI-Toolkit
• 分类：agent / MCP 后端接入层（TypeScript，MIT）
• 作者：spark
• 更新：2026-11-02

一、它是什么

一句话概括它的定位："AI 写代码，CloudBase 管后端。"

AI IDE（Cursor、Claude Code、Codex、CodeBuddy 等）擅长生成前端代码，真正卡住人的往往不是代码，而是后端那一堆东西：库表结构、权限规则、云函数、对象存储、环境隔离、发布流程。这个仓库就是腾讯云 CloudBase 与 AI 编程工具之间的接入层，交付三个东西：

组件	作用
Plugin	一次装好 MCP Server + Agent Skills + Hooks，省掉按 IDE 分别配置
Agent Skills	场景化技能包（Web / 小程序 / 数据库 / 认证 / 云函数等），约束"怎么写才落地"
MCP	在对话中登录环境、查改数据、管理函数与云托管、读日志排障

仓库同时发布 npm 包 @cloudbase/cloudbase-mcp、Skills 合集与 AI 插件。它不是 CloudBase 平台本身——你仍然需要自己开通云开发环境。

二、解决什么问题

• AI 只能写代码、碰不到后端：接上 MCP 后，模型可以在你的真实环境里建集合、写权限规则、部署云函数、读日志，而不是丢一段本地代码就收工。
• 每个 IDE 配一遍：Plugin 把 MCP + Skills + Hooks 打包，Cursor / Claude Code / Codex / OpenClaw / Gemini CLI / OpenCode / Qwen Code / Trae / RooCode / Copilot 等二十多个 IDE 都有官方指引。
• "AI 知道能干活，但不知道怎么做对"：Skills 就是那份岗位手册——README 用了一个很贴切的比喻：MCP 让 AI "能动手"，Skills 让 AI "懂规矩"。
• 安全边界模糊：v2.36.x 起，删除类操作、破坏性 SQL 与对应的 callCloudApi 删除动作会先停下来确认并点名目标；参数里出现疑似密钥时只核对长度与 sha256 指纹，不回显明文。

三、快速安装

前置条件

• Node.js v18.15.0+（node --version 校验）
• 一个已开通的 CloudBase 环境
• 一个支持 Plugin / Skills / MCP 的 AI 工具

路径 A：Plugin（推荐，一键装全套）

npx plugins add TencentCloudBase/cloudbase-plugin

marketplace 类 IDE（Claude Code / Codex 原生 marketplace）请用本仓库作 marketplace 源，不要再对同一工具重复跑 npx plugins add——README 明确点名了这个冲突。

路径 B：CloudBase CLI 一键配 MCP + Skills

npm i -g @cloudbase/cli
tcb ai

路径 C：只配 MCP（手动写 IDE 配置）

Cursor 的 .cursor/mcp.json / Windsurf 的 .windsurf/settings.json 通用格式：

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"]
    }
  }
}

Cursor 也可以带 env 标记来源 IDE：

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": { "INTEGRATION_IDE": "Cursor" }
    }
  }
}

路径 D：最快上手的"AI 提示词"

README 推荐的骚操作——把这段直接粘进你的 AI IDE，让 Agent 自己读 skill.md 完成接入：

帮我把 CloudBase 接好，按下面做：
1. 打开 https://docs.cloudbase.net/skill.md，按说明完成接入。
2. 接入完成后告诉我，并建议最相关的下一步。

MCP 连接模式（三选一）

① 远端模式（推荐，官方推荐）——IDE 通过 HTTP 连腾讯云上的 MCP，本机不需要 Node，浏览器里完成授权：

{
  "mcpServers": {
    "cloudbase": {
      "type": "http",
      "url": "https://tcb-api.cloud.tencent.com/mcp/v1"
    }
  }
}

站点	MCP 地址
国内站	https://tcb-api.cloud.tencent.com/mcp/v1
国际站	https://tcb-api.tencentcloud.com/mcp/v1

两套站点的账号、控制台、凭证互相独立，选错就看不到环境。 OAuth 模式下配置文件里不放密钥，也没东西需要轮换。

② 静态凭证（不支持 OAuth 的客户端、CI/CD）：

{
  "mcpServers": {
    "cloudbase": {
      "type": "http",
      "url": "https://tcb-api.cloud.tencent.com/mcp/v1?env_id=<env_id>",
      "headers": {
        "X-TencentCloud-SecretId": "<腾讯云 Secret ID>",
        "X-TencentCloud-SecretKey": "<腾讯云 Secret Key>"
      }
    }
  }
}

⚠️ 静态密钥不轮换、不删除就一直有效，OAuth 会话则可以靠退出登录结束。只在浏览器授权走不通时才用，且绝不要提交进仓库。

③ 本地模式——本机 npx @cloudbase/cloudbase-mcp@latest 启动，功能最全（含依赖本地文件系统的上传、模板下载）。

远端 URL 支持 env_id、enable_plugins、disable_plugins、use_internal_endpoint 四个参数；没有 site 参数——站点由域名决定，国内站环境落在 ap-singapore 也照样是国内站。

四、核心用法

4.1 首次对话

登录云开发

AI 会引导完成登录与环境选择。之后就能用自然语言描述需求。

4.2 完整后端活儿

使用 CloudBase Skills 开发一个带登录的待办应用，包含数据库与权限，并部署

这套流程能覆盖的能力面：

• 数据库：PostgreSQL 与文档型库、数据模型、CRUD、权限与安全规则
• 计算：云函数与云托管的编写、部署、调用与日志
• 身份与存储：登录方式、对象存储、与业务数据的权限联动
• 发布与排障：静态托管 / 小程序发布、读日志定位问题并再部署

README 强调了一句很实在的话："完成后应能在自己的环境中验证数据与接口，而不只是得到一段本地代码。"

4.3 单独装 Skills

只要知识约束、不要动环境时：

npx skills add TencentCloudBase/cloudbase-skills
# 或按单个 skill 安装
npx skills add tencentcloudbase/skills --skill <name>

4.4 工具面规模（重要设计细节）

v2.34.x 起，searchKnowledgeBase 内联的 skill / OpenAPI 清单改为按需返回，官方给的数字是：43 个工具的常驻面在每次 tools/list 时缩小 9.1%。工具总数是可增长的，callCloudApi 的服务白名单已扩到 57 个并内置版本映射。

4.5 国际站用户

必须在 MCP env 里声明站点，否则登录会走国内站链路、看不到国际站环境：

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": { "TCB_SITE": "intl" }
    }
  }
}

也可用启动参数 --site、对话中指定或 CLI 配置。

五、典型适用场景

1. Vibe Coding 的后端闭环：一句话生成带登录、数据库、权限的前后端，并直接部署上线，不用手动建表配规则。
2. 微信小程序 / Web 应用后端：CloudBase 原生支持小程序静态托管与云函数，AI 直接对接。
3. 存量项目接 AI 工具：团队里已有 Cursor/Claude Code 混用，希望统一 MCP 配置与 Skills 约束。
4. CI/CD 场景：用静态凭证 + 远端 HTTP 模式，让流水线里的 agent 也能查库、读日志。
5. 教学与规范落地：把"数据库怎么建索引、RLS 怎么门禁"写进 Skills，新人/新模型产出的代码直接合规——v2.34.x 新增了 PostgreSQL 访问模式最佳实践 skill（批量读写、索引、RLS 角色门禁、上线容量）。

六、坑与注意

1. 版本核验：本文核验时 GitHub 最新 release 为 v2.36.2（2026-10-28 发布），npm @cloudbase/cloudbase-mcp 的 latest 标签同样是 2.36.2（历史版本累计 191 个）。用 @latest 拉等于跟着浮动版本走，建议生产环境钉死具体版本号（如 @cloudbase/cloudbase-mcp@2.36.2）。
2. 别重复安装：marketplace 类 IDE 用了本仓库作为 marketplace 源，就不要再 npx plugins add 同一个工具；两套并存时插件集可能冲突。
3. 国际站一定要声明 TCB_SITE=intl：不声明会静默走国内站链路，症状是"看不到我的环境"，很容易误判成权限问题。
4. 国内站 vs 国际站凭证完全独立：控制台、账号、密钥三套，不要混用；远端 URL 的域名就是站点开关（无 site 参数）。
5. 远端模式的取舍：依赖本地文件系统的能力（上传、模板下载）不可用；国际站暂未提供 NoSQL（文档数据库）工具。要用文档库就得走本地模式。
6. 静态密钥不会自动过期：SecretId/SecretKey 一旦泄露长期有效，务必走 IAM 最小权限并定期轮换，且别提交进仓库。
7. 云托管 Function 模式不得监听 PORT：端口由函数框架绑定，自己 listen 会启动失败——v2.34.x 专门补了这条闸门。
8. 云托管的凭证决策闸门以 CLOUDBASE_APIKEY 为准，别指望别的环境变量名。
9. MySQL 开通能力已被移除（v2.35.x / v2.36.x 两次提及），工具面里找不到了；需要 MySQL 走其他路径。
10. callCloudApi 的多版本服务需显式传 version：tke / mongodb / vod 这类不传会报错。
11. 静态托管路径归一化：v2.34.x 修掉了"前导斜杠被误读成目录为空"的问题，但如果你的老代码依赖旧行为，值得回归测一次。
12. MCP Apps 三面板默认关闭：起步 / 环境用量 / 部署产物三张面板是实验性的，要设 CLOUDBASE_MCP_UI=on 才出现。
13. ⚠️ 待补：本次未逐条核验 mcp/src/server.ts 里的完整工具清单与 schema（README 明确"插件名称以 mcp/src/server.ts 为准"），也没拉取 docs.cloudbase.net 的逐 IDE 配置页；实际工具名与参数请以本地 npx 启动后 tools/list 的返回为准。
14. ⚠️ 评测数据的边界：README 的"云主机 vs CloudBase 同任务评测"结论是有条件的——原文明确"在给定模型与任务设定下……上述结果受模型、Agent 框架与任务定义约束，不宜外推为一般性结论"。仅用了一个 Todo 应用需求 + 同一前端脚手架，属于单任务对照，不能当成通用性能优势。

七、与同类对比

方案	形态	覆盖能力	上手成本	适合谁
CloudBase-AI-Toolkit	MCP + Skills + Plugin	数据库/函数/存储/认证/托管/发布全套托管后端	低（npx 一条命令）	要在 AI IDE 里直接操作云开发环境
Supabase MCP	MCP Server	Postgres + Auth + Storage + Edge Functions	低	已用 Supabase 的团队
Firebase MCP / 官方工具	插件 / CLI	Firestore + Auth + Functions + Hosting	中	GCP 体系内的团队
Cloudflare MCP	MCP Server	D1 + Workers + R2 + KV	低	Cloudflare 体系内的团队
自建 MCP Server	自己写	只覆盖你想暴露的部分	高	需要完全可控语义与内部系统对接
传统 CLI（cloudbase hosting deploy）	命令行	全但要手写命令	中	不依赖 AI 的批处理/流水线

差异化优势：Skills 与 MCP 同仓交付是它最独特的地方——多数同类只给工具不给"怎么做对"，而 CloudBase 把数据库安全规则、PG 访问模式、部署流程等直接写成 skill 交给模型，AI 产出的代码更符合平台规范。代价是强绑定腾讯云生态，换平台这套投入基本作废。

八、一句话推荐

想在 Cursor / Claude Code / Codex 里让 AI 直接建库、配权限、部署上线，CloudBase-AI-Toolkit 是目前国内最完整的一套现成方案；但它深度绑定 CloudBase 生态、用 @latest 会跟着版本漂，团队接入前务必钉版本 + 声明站点（国际站尤其）。