# @cloudbase/cloudbase-mcp 中文文档

规范地址：https://npmcn.com/package/%40cloudbase/cloudbase-mcp/

版本：2\.37\.5
npm 元数据更新时间：2026-11-06T07:38:25.491Z
中文译文更新时间：2026-11-10T02:36:06.190Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudbase/cloudbase-mcp
原文对照：https://npmcn.com/package/%40cloudbase/cloudbase-mcp/?lang=original
项目主页：https://github.com/TencentCloudBase/CloudBase-AI-Toolkit
源码仓库：https://github.com/TencentCloudBase/CloudBase-AI-Toolkit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：21.9 MB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-04-17T11:49:12.575Z
- 最新版本发布：2026-11-06T07:38:25.117Z
- 近 30 天下载量：187743（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：198（近 12 个月 123 个）

## 中文简介

CloudBase MCP服务器——通过"模型上下文协议"从AI编码工具运行Tencent CloudBase(数据库,认证,函数,存储,托管). CloudBase AI工具箱的一部分.

## 安装

```sh
npm install @cloudbase/cloudbase-mcp
```

也可以使用：`pnpm add @cloudbase/cloudbase-mcp`、`yarn add @cloudbase/cloudbase-mcp`、`bun add @cloudbase/cloudbase-mcp`

## README

![CloudBase AI Toolkit](https://raw.githubusercontent.com/TencentCloudBase/CloudBase-AI-Toolkit/main/mcp/icon.png)

# @cloudbase/cloudbase-mcp

**腾讯云开发 CloudBase 的 MCP Server。** 属于 [CloudBase AI Toolkit](https://github.com/TencentCloudBase/CloudBase-AI-Toolkit)。

在 AI 编程工具里通过 Model Context Protocol 操作 CloudBase：登录、数据库、云函数、存储、托管与日志。

**简体中文** · [English](https://npmcn.com/package/%40cloudbase/cloudbase-mcp/README.md) · [Toolkit 总览](https://npmcn.com/package/%40cloudbase/README.zh-CN.md) · [文档](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/) · [更新日志](https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/releases) · [Issues](https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/issues)

[![](https://img.shields.io/npm/v/@cloudbase/cloudbase-mcp?color=3B82F6&label=npm&logo=npm&style=flat-square)](https://www.npmjs.com/package/@cloudbase/cloudbase-mcp) [![](https://img.shields.io/npm/dw/@cloudbase/cloudbase-mcp?color=10B981&label=downloads&logo=npm&style=flat-square)](https://www.npmjs.com/package/@cloudbase/cloudbase-mcp) [![](https://img.shields.io/github/stars/TencentCloudBase/CloudBase-AI-Toolkit?color=F59E0B&label=stars&logo=github&style=flat-square)](https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/stargazers) ![](https://img.shields.io/badge/license-MIT-6366F1?logo=github&style=flat-square)

## 这个包是什么

`@cloudbase/cloudbase-mcp` 是 CloudBase MCP Server 的 npm 发行包，是 Toolkit 中的一块：

| 组件 | 作用 |
| --- | --- |
| **Plugin** | 一次安装 MCP + Skills + Hooks |
| **Agent Skills** | 场景化技能，约束可落地的 CloudBase 实践 |
| **MCP**（本包） | Agent 调用的工具，作用于你的云开发环境 |

IDE 支持时优先用 Plugin；只需 MCP 配置时用本包即可。

完整 Toolkit 叙事、相关仓库与 IDE 列表见 [仓库 README](https://npmcn.com/package/%40cloudbase/README.zh-CN.md)。

## 快速开始

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

首次提示：

```
登录云开发
```

```
用 CloudBase Skills 做一个带登录、数据库和权限的待办应用，然后部署
```

需要已开通 [云开发环境](https://tcb.cloud.tencent.com/dev)，并对 AI 发起的敏感操作自行确认。

### 其他安装路径

| 路径 | 适用 |
| --- | --- |
| Official MCP Registry `io.github.TencentCloudBase/cloudbase-mcp` | [registry search=cloudbase](https://registry.modelcontextprotocol.io/v0/servers?search=cloudbase) 发现 |
| `npx plugins add TencentCloudBase/cloudbase-plugin` | 支持 Open Plugin Spec 的工具 |
| Marketplace / 内置插件 | Claude Code、Codex、CodeBuddy、WorkBuddy、豆包、MiniMax Code、DeepSeek Harness、Kimi Code、Kimi Work、ZCode 等 |

> 已经在用 CloudBase CLI 的话，`tcb ai` 同样能配好 MCP 和 Skills（[说明](https://docs.cloudbase.net/cli-v1/ai/introduce)）。

## 连接方式

**远端**（推荐）：IDE 通过 HTTP 连接腾讯云 MCP，无需本机 Node，交互式客户端在浏览器里完成授权。

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

按环境所在站点选择地址——两个站点账号与凭证相互独立。

**本地**：在本机运行 `npx @cloudbase/cloudbase-mcp@latest`，功能最全（含本地文件上传、模板下载）。需 Node.js v18.15.0+。

```json
{
  "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（交互式，推荐）**：只填 URL，IDE 会打开浏览器完成登录与授权，密钥不落配置文件。
-   **静态凭证（CI/CD）**：补上 `env_id` 与上面的 `X-TencentCloud-*` 请求头。

远端的取舍：依赖本地文件系统的能力（上传、模板下载）不可用；国际站暂未提供 NoSQL 相关工具。

远端 URL 可用 `site`，仅用于国内站账号的 `ap-singapore` 环境（该地域两站都有、服务端无法归属），另可用 `enable_plugins` / `disable_plugins`（逗号分隔）裁剪工具集。插件名见本包 `src/server.ts`（如 `env`、`database`、`functions`、`hosting`、`storage`、`pg_database`、`cloudrun`、`logs`）。

**自建 Cloud Mode**：设置 `CLOUDBASE_MCP_CLOUD_MODE=true`（或 `MCP_CLOUD_MODE=true`），禁用面向远程调用方的本地文件/进程类工具。

| 场景 | 建议 |
| --- | --- |
| 个人开发 / 最快上手 | 远端 URL（OAuth） |
| 需要本地文件能力 | 本地 `npx` |
| CI / 自动化 | 远端 + 静态凭证 |
| 自建 MCP | 必须开 Cloud Mode |

### 站点与地域

用 `TCB_SITE`（`domestic` / `intl`）选择登录与凭证站点，`TCB_REGION` 控制 API 走哪个地域。国内站与国际站是两套独立账号体系。`ap-singapore` 在两个站点都存在，所以**国内站新加坡的用户必须显式设置 `TCB_SITE=domestic`**，否则会默认走国际站。也支持项目级 `.cloudbase/project.json`（`{ site, region, envId }`）。

**远端模式下，站点由地址本身决定**——`tcb-api.cloud.tencent.com` 是国内站，`tcb-api.tencentcloud.com` 是国际站，不需要也不应该再选。国内站环境落在 `ap-singapore` 也照样用国内站地址——远端没有 `site` 参数，站点只由域名决定。自建 Cloud Mode 部署仍可用 `TCB_SITE` 环境变量。

## 能力

在你的环境中完成常见后端工作（关键步骤请确认）：

-   **数据库**：PostgreSQL 与文档型数据库、数据模型、CRUD、权限
-   **计算**：云函数 / 云托管——编写、部署、调用、排障
-   **认证与存储**：登录方式、对象存储、与数据权限联动
-   **发布与运维**：静态托管 / 小程序发布；日志与重新部署

工具目录：[MCP 工具](https://npmcn.com/package/%40cloudbase/doc/mcp-tools.md) · [tools.json](https://npmcn.com/package/%40cloudbase/scripts/tools.json)

## 破坏性操作的执行前确认

删除云函数、集合、集合内的文档、云存储文件、云托管服务或 MySQL 实例时，调用会在执行前暂停，等你在确认框里选一次——框里写清**这次要动什么**（例如「即将删除云函数 `hello`（环境 `env-abc`）」），而不是只问一句"确定吗"。同一批删除如果改走 `callCloudApi`，也按写死的 `service` + `Action` 停下来确认：`tcb`/`scf` 的 `DeleteFunction`、`tcb.DeleteTable`、`tcb.DeleteItem`、`tcb.DestroyEnv`、`tcb.DestroyPlatformEnv`、`tcb.DestroyMySQL`、`tcbr.DeleteCloudRunServer`，以及 `tcbr.DeleteCloudRunVersions` 且 `IsDeleteServer` 为 true。不会按 `Delete` 前缀去拦其它云 API。云存储删除不走 `callCloudApi`。PostgreSQL 的 `execute` / `applyMigration` 只在语句本身是 `DELETE`、`DROP`、`TRUNCATE` 或 `ALTER … DROP` 时才停下来；`INSERT` / `UPDATE` / `CREATE TABLE` 不拦。它基于 MCP 的表单式 elicitation，所以只在**声明了该能力、并且真的会问用户**的客户端里出现。

| 情况 | 行为 |
| --- | --- |
| 客户端会问你 | 出现确认框；只有你选了"确认删除"才执行 |
| 客户端处于完全访问 / 不询问模式 | 它会在几毫秒内自己应答。这被当作"你没被问到"处理，调用照常执行 |
| 客户端渲染不了表单 | 不弹窗，照常执行——与本次改动前完全一致 |
| 你点了取消、关掉，或 45 秒没作答 | 什么都不执行，返回里写明"未执行"，且**不会被标记成错误**（避免模型把"被拒绝"当成出错然后重试同一个删除） |

被拒绝不等于失败：工具返回"未执行"以及可以改用别的做法。两个环境变量可以调整这套行为，它们都**不绕过**认证、权限或只读限制，只决定"问不问"：

| 变量 | 作用 |
| --- | --- |
| `CLOUDBASE_MCP_SKIP_ELICITATIONS` | 逗号分隔。可写工具名（`manageFunctions`、`callCloudApi`）或单个动作（`manageFunctions.deleteFunction`、`callCloudApi.tcb.DeleteFunction`）；区分大小写、无通配。无法识别的条目会记日志并忽略，不会让服务起不来 |
| `CLOUDBASE_MCP_ELICIT_AUTO_APPROVE` | `allow`（默认）：客户端自己应答时放行；`block`：这种情况也按"未确认"处理 |

客户端自己的"工具审批"框**不是**这个确认：它问的是"允不允许这个工具运行"，不是"你要删的就是这个资源吗"。

### 参数里出现凭证：写入前先做一次真实核对

当一次调用的参数里出现凭证形态的字符串——三段式 JWT，或 `cb_secret_…` / `cb_publishable_…` 开头的密钥——服务端会在写入前向客户端要一次核对：把这串与你手上的**原始来源**逐字比对，一致再确认。消息里**刻意不放明文**，只给总长度、分段长度（JWT）与指纹（sha256 的前 12 位十六进制）：这几样足够看出"复制或转写时被改过"，又不会把密钥带进对话或日志。

**这不是什么。** 我们**不判断凭证是否有效**：没有验签，不查 `certs`/JWKS，**不发任何网络请求**，服务端也不做比对——用户最初粘进来的那份服务端永远拿不到，能做比对的只有客户端。它只是"写入前要一次真实的确认"，不是有效性校验。

**边界。** 只有参数里**真的**出现凭证形态字符串时才会走到这一步（否则调用零变化：一次浅扫描、无网络）；只有客户端支持交互式表单 elicitation 时才生效，不支持干预式确认的客户端照常执行（不会把无人值守的客户端整个封死）；另外，**几百毫秒内返回的核对一律按"没人看过"处理**——与删除确认相反（那边客户端自己应答会被当作"你没被问到"而放行），凭证写入**不执行**，因为"没人比对过"正是它要挡的情况。被拦下时返回"未执行"，且**不会被标记成错误**，避免模型盲目重试。

| 变量 | 作用 |
| --- | --- |
| `CLOUDBASE_MCP_SKIP_CREDENTIAL_GUARD` | 逗号分隔。可写工具名（`manageCloudRun`）或单个动作（`manageCloudRun.updateConfig`）；区分大小写、无通配。无法识别的条目会记日志并忽略，不会让服务起不来 |

## 环境面板（MCP Apps）

当客户端声明了 `io.modelcontextprotocol/ui` 扩展时，`auth` 会额外打开一个面板 （`ui://cloudbase/get-started`）。面板默认开启，`CLOUDBASE_MCP_UI=off` 可以关掉。 它直接消费这次 `auth` 调用已经送回来的结构化结果，展示连接状态 ——地域、范围与环境 ID。未登录时给出登录；已登录未绑定环境时，点列表中的一行即可绑定。

面板不会改动云端资源，**但它不是只读的**。它会发两类调用：

-   `auth(status)` —— 只读，点「重新检查」触发。
-   `auth(set_env)` —— 点环境那一行时触发。它只改**本地**会话绑定的环境（环境级 API Key 仍然切不到别的环境）， 但改完之后所有后续工具都按新环境走，所以那一行要有意识地选。

其余操作只是把一句话交给会话。带 `credentials` 的结果（例如 `auth(get_temp_credentials)` 开了 `reveal`） 不会打开「查看原始返回」，折叠区里不会出现密钥。

不渲染 MCP Apps 的客户端不受影响：`auth` 的标题、描述、参数与输出保持不变，`resources/list` 仍为空数组， 资源面板里不会多出任何新条目。

## 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。

其他：[IDE 配置指南](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ide-setup/)。

## 文档

-   [Toolkit 总览](https://npmcn.com/package/%40cloudbase/README.zh-CN.md)
-   [快速开始](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/getting-started)
-   [AI 插件](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ai-agent-plugins)
-   [常见问题](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/faq)
-   [更新日志](https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/releases)

## 许可证

[MIT](https://npmcn.com/package/%40cloudbase/LICENSE) · [TencentCloudBase](https://github.com/TencentCloudBase)

## 常见问题

### @cloudbase/cloudbase-mcp 是什么？

CloudBase MCP服务器——通过"模型上下文协议"从AI编码工具运行Tencent CloudBase\(数据库,认证,函数,存储,托管\)\. CloudBase AI工具箱的一部分\.

### 如何安装 @cloudbase/cloudbase-mcp？

在项目目录运行 npm install @cloudbase/cloudbase-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cloudbase-mcp，可以用 npx cloudbase-mcp 直接运行。

### @cloudbase/cloudbase-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cloudbase/cloudbase-mcp 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cloudbase/cloudbase-mcp 可以商用吗？

@cloudbase/cloudbase-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudbase/cloudbase-mcp 的下载量有多少？

根据 npm 官方下载统计，@cloudbase/cloudbase-mcp 在 2026/10/10 – 2026/11/08 这 30 天内被下载 187,743 次，日均约 6,258 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloudbase/cloudbase-mcp 还在维护吗？

最新版本 2\.37\.5 发布于 2026/11/06（3 天前）；至今共发布 198 个版本，其中过去 12 个月发布了 123 个；首次发布于 2025/04/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。