# CloudBase AI Toolkit **AI 写代码，CloudBase 管后端。** 面向 AI 编程工具的 CloudBase 接入层：用 Plugin 装好工具，用 Skills 约束写法，用 MCP 在对话里操作数据库、云函数、存储与部署。 **简体中文** · [English](./README.md) · [文档][docs] · [更新日志][changelog] · [Issues][github-issues-link] [![][npm-version-shield]][npm-link] [![][npm-downloads-shield]][npm-link] [![][github-stars-shield]][github-stars-link] [![][github-forks-shield]][github-forks-link] [![][github-issues-shield]][github-issues-link] ![][github-license-shield] ![][github-contributors-shield] [![][cnb-shield]][cnb-link] [![][deepwiki-shield]][deepwiki-link]

## 最近更新 **v2.34.x**（2026-09） - 多语言 / IDE：工具文案全量国际化，新增实例级 `lang` 与 `auth` 的 `site` / `region` 参数，国际站登录与地域路由更准确 - 云 API：`callCloudApi` 服务白名单扩至 57 个并内置版本映射（`tke` / `mongodb` / `vod` 等多版本服务需显式传 `version`） - 部署 / 环境：新增 `appBuild` 工具与托管构建中和；`queryEnv` 如实回执 region 生效情况，`domains` 尊重传入的 envId - Skills / 文档：skill 兜底读取改指官方分发仓并返回 references 地址清单；cloudrun 增加 SDK-first 数据库访问决策闸门；官网文档链接改指站点当前 Markdown 寻址；专家包与部署 skill 在交付后可执行「部署分享」（脱敏、至多一次、可拒绝） - 部署 / 应用：云端上传通道可完整跑通（`deployApp` 接受 `getUploadUrl` 返回的时间戳，`getBuildLog` 接受部署返回的构建 ID）；网关路由创建前会校验上游资源是否存在 **v2.33.x**（2026-09） - 云函数 / 应用：支持自定义容器镜像部署与异步状态查询；云端上传通道（`getUploadUrl` + `deployApp` cosTimestamp） - 环境绑定：`cloudbaserc.json` 可作为 envId / region / site 的字段级回退（字面量与 `{{env.KEY}}`） - 错误引导 / Skills：按结构化 `Code` 集中引导；虚拟支付参考；CodeBuddy IDE MCP 升级 skill；WorkBuddy experts - 云 API / 部署：`callCloudApi` 开放 monitor / postgres 服务；声明式部署 `deployPlan` / `deployApply`；新增 `cloud-api-operations` skill [Releases][changelog] · [Star][github-stars-link] · Watch → Releases ## 它是什么 AI IDE（Cursor、Claude Code、Codex、CodeBuddy 等）擅长生成代码。真正卡住的往往是后端：库表、权限、函数、存储、环境与发布。 [CloudBase](https://docs.cloudbase.net/) 是腾讯云的 AI 原生后端一体化平台（数据库、存储、身份认证、云函数、云托管等）。本仓库提供把这套后端接到 AI 工具里的 Toolkit： | 组件 | 作用 | |------|------| | **Plugin** | 一次安装 MCP Server、Agent Skills 与 Hooks，减少按 IDE 分别配置 | | **Agent Skills** | 场景化技能（Web / 小程序 / 数据库 / 认证 / 云函数等），约束可落地的 CloudBase 实践 | | **MCP** | 在对话中登录环境、查改数据、管理函数与托管、读日志排障 | 本仓库同时发布 npm 包 `@cloudbase/cloudbase-mcp`、Skills 与 AI 插件。你仍需要：开通自己的云开发环境，并在 IDE 中确认 AI 发起的敏感操作。Toolkit 提供能力与路径，不替代判断。 ### 相关仓库发布与同步仓集中在 [TencentCloudBase](https://github.com/TencentCloudBase) 组织。与本 Toolkit 直接相关的如下： | 仓库 | 内容 | 常用入口 | |------|------|----------| | [CloudBase-AI-Toolkit](https://github.com/TencentCloudBase/CloudBase-AI-Toolkit)（本仓库） | MCP Server 源码；Claude Code / Codex 等原生 marketplace 来源 | `npx @cloudbase/cloudbase-mcp@latest` | | [cloudbase-plugin](https://github.com/TencentCloudBase/cloudbase-plugin) | Open Plugin Spec 发布仓（由本仓库 CI 同步）：MCP + Skills + Hooks | `npx plugins add TencentCloudBase/cloudbase-plugin` | | [cloudbase-sites-plugin](https://github.com/TencentCloudBase/cloudbase-sites-plugin) | Sites 插件：Vite Web 创建与部署 | `npx plugins add TencentCloudBase/cloudbase-sites-plugin` | | [cloudbase-skills](https://github.com/TencentCloudBase/cloudbase-skills) | Agent Skills 合集 | `npx skills add TencentCloudBase/cloudbase-skills` | | [skills](https://github.com/TencentCloudBase/skills) | 可按单个 skill 安装的目录（亦用于 [skills.sh](https://skills.sh)） | `npx skills add tencentcloudbase/skills --skill ` | | [awesome-cloudbase-examples](https://github.com/TencentCloudBase/awesome-cloudbase-examples) | 云开发案例与示例集合 | 浏览 / 克隆示例 | | [OpenVibeCoding](https://github.com/TencentCloudBase/OpenVibeCoding) | 基于 CloudBase 的 vibecoding 模板 | 作为项目起点使用 | 优先用 Plugin 拿齐全套；只需知识约束时可只装 Skills。marketplace 类 IDE 请用本仓库，不要与 `npx plugins add` 对同一工具重复安装。 ## 快速开始 ### 最快上手（推荐）复制下面的 AI Prompt，粘贴到你的 AI IDE。Agent 会读取 skill.md 完成接入： ``` 帮我把 CloudBase 接好，按下面做： 1. 打开 https://docs.cloudbase.net/skill.md，按说明完成接入。 2. 接入完成后告诉我，并建议最相关的下一步。 ```

按你的工具选一条默认路径（Plugin / CLI / MCP）

| 你的工具 | 建议做法 | |----------|----------| | Claude Code / Codex（原生 marketplace） | 添加本仓库为 marketplace，再安装 `cloudbase` 插件（见[插件文档](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ai-agent-plugins)） | | 支持 Open Plugin Spec 的工具 | `npx plugins add TencentCloudBase/cloudbase-plugin` | | 希望 CLI 统一配置多种工具 | [CloudBase AI CLI](https://docs.cloudbase.net/cli-v1/ai/introduce)：`npm i -g @cloudbase/cli && tcb ai` | | CodeBuddy / WorkBuddy / ZCode / Kimi（已内置） | 使用 IDE 内置的 CloudBase 插件或连接器；CodeBuddy 也可通过[插件市场安装](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/codebuddy) | | 其他支持 MCP 的 IDE | 仅配置 MCP（见下方） | #### Plugin ```bash npx plugins add TencentCloudBase/cloudbase-plugin ``` 说明与各 IDE 差异见 [AI 插件文档](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ai-agent-plugins)。 #### 仅配置 MCP ```json { "mcpServers": { "cloudbase": { "command": "npx", "args": ["@cloudbase/cloudbase-mcp@latest"] } } } ``` 托管 HTTP、自建 Cloud Mode、按插件裁剪工具集见 [安装与连接](#安装与连接)。

### 首次对话 ``` 登录云开发 ``` ``` 使用 CloudBase Skills 开发一个带登录的待办应用，包含数据库与权限，并部署 ``` Skills 负责写法与结构；MCP 负责环境与资源操作。完成后应能在自己的环境中验证数据与接口，而不只是得到一段本地代码。 ### 支持的 AI IDE Supported AI IDEs

| 工具 | 平台 | 指引 | |------|------|------| | [CloudBase AI CLI](https://docs.cloudbase.net/cli-v1/ai/introduce) | CLI | [指引](https://docs.cloudbase.net/cli-v1/ai/introduce) | | [OpenClaw](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/openclaw) | CLI | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/openclaw) | | [WorkBuddy](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/workbuddy) | 独立 IDE | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/workbuddy) | | [ZCode](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/zcode) | 独立 IDE（≥ 3.4.1 内置插件） | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/zcode) | | [Kimi Code](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/kimi-code) | CLI（插件市场） | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/kimi-code) | | [Kimi Work](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/kimi-code) | 桌面应用（插件面板） | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/kimi-code) | | [Codex App](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/codex) | 独立应用 | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/codex) | | [Cursor](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/cursor) | 独立 IDE | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/cursor) | | [WindSurf](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/windsurf) | 独立 IDE / 插件 | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/windsurf) | | [CodeBuddy](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/codebuddy) | 独立 IDE（已内置） | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/codebuddy) | | [CLINE](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/cline) | VS Code 插件 | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/cline) | | [GitHub Copilot](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/github-copilot) | VS Code 插件 | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/github-copilot) | | [Trae](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/trae) | 独立 IDE | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/trae) | | [通义灵码](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/tongyi-lingma) | IDE / 插件 | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/tongyi-lingma) | | [RooCode](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/roocode) | VS Code 插件 | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/roocode) | | [文心快码](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/baidu-comate) | 插件 | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/baidu-comate) | | [Augment Code](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/augment-code) | 插件 | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/augment-code) | | [Claude Code](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/claude-code) | CLI | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/claude-code) | | [Gemini CLI](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/gemini-cli) | CLI | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/gemini-cli) | | [Codex CLI](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/openai-codex-cli) | CLI | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/openai-codex-cli) | | [OpenCode](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/opencode) | CLI | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/opencode) | | [Qwen Code](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/qwen-code) | CLI | [指引](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/qwen-code) | 完整配置见 [IDE 配置指南](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/)。 ## 能力接入后，AI 可以在你的环境中完成典型后端工作（需你确认关键步骤）： - **数据库**：PostgreSQL 与文档型库、数据模型、CRUD、权限与安全规则 - **计算**：云函数与云托管的编写、部署、调用与日志 - **身份与存储**：登录方式、对象存储、与业务数据的权限联动 - **发布与排障**：静态托管 / 小程序发布；根据日志定位问题并再部署适用形态包括 Web、微信小程序与后端服务。平台能力总览见 [CloudBase 文档](https://docs.cloudbase.net/)。 ### 评测说明在受控条件下，以同一待办（Todo）应用需求与同一前端脚手架为输入，比较两类后端实现路径：传统云主机（自行搭建运行时、进程与网络暴露）与 CloudBase（托管数据库、匿名登录等后端能力）。评测由 AI Agent 端到端完成开发与验证；在给定模型与任务设定下，CloudBase 路径在完成时延、Token 用量与工具调用次数上更优。上述结果受模型、Agent 框架与任务定义约束，不宜外推为一般性结论。方法、数据与边界条件见：[传统云主机与 CloudBase 同任务评测报告](https://docs.cloudbase.net/solutions/vibe-coding-platform/vm-vs-cloudbase-comparison) ## 安装与连接 ### 前置条件 - Node.js v18.15.0+ - 已开通 [云开发环境](https://tcb.cloud.tencent.com/dev) - 已安装支持 Plugin / Skills / MCP 的 AI 工具 ### 配置方式 1. **Plugin**（推荐，能装插件时） `npx plugins add TencentCloudBase/cloudbase-plugin` 2. **CloudBase AI CLI** `npm i -g @cloudbase/cli && tcb ai` 3. **手动 MCP**（按 IDE 写入配置文件）

Cursor（.cursor/mcp.json）

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

WindSurf（.windsurf/settings.json）

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

CodeBuddy

已内置 CloudBase（含 MCP / Skills），一般无需再手写配置。也可通过插件市场安装：见 [CodeBuddy 配置指南](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/codebuddy)。

其他 IDE：[完整配置指南](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/)。 ### MCP 连接模式 **本地模式**（默认）：本机 `npx` 启动，功能最全（含依赖本地文件系统的上传、模板等）。 **托管模式**：IDE 通过 HTTP 连接腾讯云上的 MCP，无需本机 Node；部分本地文件能力不可用。 ```json { "mcpServers": { "cloudbase": { "type": "http", "url": "https://tcb-api.cloud.tencent.com/mcp/v1?env_id=", "headers": { "X-TencentCloud-SecretId": "<腾讯云 Secret ID>", "X-TencentCloud-SecretKey": "<腾讯云 Secret Key>" } } } } ``` 托管 URL 可用 `site`（`domestic` / `intl`）指定登录站点（国内站新加坡需 `site=domestic`），也可用 `enable_plugins` / `disable_plugins` 裁剪工具集。名称以 `mcp/src/server.ts` 为准。 **云端 Hosted MCP E2E**（官方 SDK 客户端）：`npm run test:hosted-mcp:e2e`，环境变量与双模式说明见 [`tests/hosted-mcp-e2e/README.md`](tests/hosted-mcp-e2e/README.md)。缺凭证时相关用例 skip（退出码 0）。 **自建 Cloud Mode**：在自有服务器部署时设置 `CLOUDBASE_MCP_CLOUD_MODE=true`（或 `MCP_CLOUD_MODE=true`），禁用本地文件与本地进程类工具，避免远程调用方操作宿主机。 | 场景 | 建议 | |------|------| | 个人开发 | 本地 `npx` | | 团队 / 免运维 | 腾讯云托管 HTTP | | 自建 MCP 服务 | 必须开启 Cloud Mode | ## 案例 **双人在线五子棋**：需求描述后生成 Web + 云数据库与实时能力并部署。体验：[五子棋](https://cloud1-5g39elugeec5ba0f-1300855855.tcloudbaseapp.com/gobang/#/) · 更多：[教程与案例](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/tutorials) ## 文档 - [MCP 工具说明](doc/mcp-tools.md)（[tools.json](scripts/tools.json)） - [快速开始](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/getting-started) - [IDE 配置](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/) - [AI 插件](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ai-agent-plugins) - [模板](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/templates) - [FAQ](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/faq) ## 常见问题

和 Vercel / Netlify 这类部署平台有何不同？

它们侧重把前端或容器发布出去。CloudBase 提供数据库、认证、函数等后端能力；Toolkit 让 AI 工具在对话里使用这些能力。部署只是链路的一部分。

没有图形界面 IDE 也能用吗？

可以。凡能配置 MCP Server 或安装对应 Plugin / Skills 的工具均可，包括 Claude Code、Gemini CLI、OpenCode 等。[支持列表](#支持的-ai-ide)

代码会到哪里？

部署目标是你自己的云开发环境。本地模式下 MCP 跑在本机；主动部署前代码不必离开本机。云端通信使用 HTTPS。

自建 MCP 服务是否安全？

本地 `npx` 等同于你在本机执行工具。远程部署务必设置 `CLOUDBASE_MCP_CLOUD_MODE=true`，以禁用本地文件与进程类工具。腾讯云托管 HTTP 模式已带该保护。

费用？

Toolkit（含 MCP）开源，MIT。云开发环境有免费额度；超出后按量计费，见 [计费说明](https://cloud.tencent.com/document/product/876/39095)。

登录提示环境不存在？

确认已在 [控制台](https://tcb.cloud.tencent.com/) 开通且环境状态正常，然后再次「登录云开发」选择正确环境。

## 社区

_{微信技术交流群}

| | | |--|--| | 文档 | [docs.cloudbase.net](https://docs.cloudbase.net/) | | Issues | [GitHub Issues](https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/issues) | | Releases | [更新日志][changelog] | ## 项目活跃度 ![Repo Activity](https://repobeats.axiom.co/api/embed/6cd6ed00da4384e43b24805c197f584626946dda.svg "Repobeats analytics image") ## Contributors [![Contributors](https://contrib.rocks/image?repo=TencentCloudBase/CloudBase-AI-Toolkit)](https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/graphs/contributors) --- [MIT](LICENSE) · [TencentCloudBase](https://github.com/TencentCloudBase) [docs]: https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ [changelog]: https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/releases [github-issues-link]: https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/issues [github-stars-link]: https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/stargazers [github-forks-link]: https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/network/members [npm-link]: https://www.npmjs.com/package/@cloudbase/cloudbase-mcp [cnb-link]: https://cnb.cool/tencent/cloud/cloudbase/CloudBase-AI-Toolkit [deepwiki-link]: https://deepwiki.com/TencentCloudBase/CloudBase-AI-Toolkit [npm-version-shield]: https://img.shields.io/npm/v/@cloudbase/cloudbase-mcp?color=3B82F6&label=npm&logo=npm&style=flat-square [npm-downloads-shield]: https://img.shields.io/npm/dw/@cloudbase/cloudbase-mcp?color=10B981&label=downloads&logo=npm&style=flat-square [github-stars-shield]: https://img.shields.io/github/stars/TencentCloudBase/CloudBase-AI-Toolkit?color=F59E0B&label=stars&logo=github&style=flat-square [github-forks-shield]: https://img.shields.io/github/forks/TencentCloudBase/CloudBase-AI-Toolkit?color=8B5CF6&label=forks&logo=github&style=flat-square [github-issues-shield]: https://img.shields.io/github/issues/TencentCloudBase/CloudBase-AI-Toolkit?color=EC4899&label=issues&logo=github&style=flat-square [github-license-shield]: https://img.shields.io/badge/license-MIT-6366F1?logo=github&style=flat-square [github-contributors-shield]: https://img.shields.io/github/contributors/TencentCloudBase/CloudBase-AI-Toolkit?color=06B6D4&label=contributors&logo=github&style=flat-square [cnb-shield]: https://img.shields.io/badge/CNB-CloudBase--AI--Toolkit-3B82F6?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTIiIHZpZXdCb3g9IjAgMCAxMiAxMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB3aWR0aD0iMTIiIGhlaWdodD0iMTIiIHJ4PSIyIiBmaWxsPSIjM0I4MkY2Ii8+PHBhdGggZD0iTTUgM0g3VjVINSIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIxLjUiLz48cGF0aCBkPSJNNSA3SDdWOUg1IiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjEuNSIvPjwvc3ZnPg==&style=flat-square [deepwiki-shield]: https://deepwiki.com/badge.svg