跳到主要内容

用 Claude Code 接入 CloudBase MCP,自然语言操作 CloudBase 资源

一句话定义:claude mcp add cloudbase -- npx -y @cloudbase/cloudbase-mcp@latest,Claude Code 拿到 36 个 CloudBase tool(建表 / 写云函数 / 部署托管 / 云托管 / 云存储 / 搜索),自然语言一句话从 prompt 到上线 CloudBase 应用。

预计耗时:15 分钟 | 难度:入门

适用场景​

  • 用 Claude Code 当 AI 助手做 CloudBase 项目,让它直接帮你建库 / 写函数 / 部署,不切控制台
  • 团队搞 vibe coding,从需求拆解到部署上线全程 Claude Code 跑
  • 已经用 Claude Code 的 /spec /no_spec 工作流,想叠加 CloudBase 域知识让 AI 生成的代码直接能落地

不适用:

  • Claude Code 不是生产 CI/CD 工具,生产部署还是走 git push + 流水线,本篇适合开发阶段快速迭代
  • Cursor / Windsurf / CodeBuddy 等其他 IDE 走各自的 MCP 集成路径(配置文件不同),本篇只覆盖 Claude Code(claude mcp add 命令)
  • 纯本地工具(操作本机文件、读进程列表)的 MCP server,与 CloudBase 无关,走 stdio transport 本地跑即可

环境要求​

依赖版本
Claude Code最新(npm i -g @anthropic-ai/claude-code 或 claude.ai/code)
@cloudbase/cloudbase-mcp@latest 标签自动取最新版本(撰写时是 2.19.5)
Node.js≥ 18.15.0(参 cloudbase-mcp 仓库 README)
CloudBase 环境已开通,记下 envId
腾讯云 API 密钥SecretId / SecretKey,从 腾讯云控制台 → 访问密钥 生成

第一步:Claude Code 装 cloudbase-mcp​

最小命令:

claude mcp add cloudbase -- npx -y @cloudbase/cloudbase-mcp@latest

这条命令做了:

  • 注册一个名为 cloudbase 的 MCP server
  • transport 走 stdio(本地 npx 启动子进程)
  • @latest 标签自动取仓库最新发布版本

注入凭证(避免每次对话都让 Claude 问你环境 ID / 密钥):

claude mcp add -e CLOUDBASE_ENV_ID=<your-env-id> \
  -e TENCENTCLOUD_SECRETID=<your-secret-id> \
  -e TENCENTCLOUD_SECRETKEY=<your-secret-key> \
  cloudbase -- npx -y @cloudbase/cloudbase-mcp@latest

跑 claude mcp list 验证:

cloudbase: npx -y @cloudbase/cloudbase-mcp@latest - ✓ Connected

✓ Connected 才算成功。✗ failed to connect 看下面常见错误段。

第二步:可选 — 装 cloudbase-skills 包​

cloudbase-mcp 只给 Claude 能力(36 个 tool 调用),装 cloudbase-skills 包再给它知识(CloudBase 域的 prompt 模板 + coding plan):

npx skills add tencentcloudbase/cloudbase-skills

装完后 Claude Code 会获得:

  • /spec — 完整工作流:需求 → 设计 → 任务拆解 → 实现,适合从 0 起做新项目
  • /no_spec — 直接干,跳过拆解,适合改 bug / 加单个 feature
  • 内置 coding plan skill — 写代码前自动按 plan 分步执行(默认开启)

不装也能用 cloudbase-mcp,只是 Claude 在选 tool / 决定调用顺序时全靠自己推理,装了之后会按 CloudBase 推荐路径走。

第三步:CloudBase MCP 的 36 个 tool 概览​

装好后 Claude Code 自动发现这些 tool(/tools 命令看完整列表)。

CloudBase MCP 的设计哲学是 按"领域 × 读/写"两维拆分——大部分领域成对设计为 query*(读)+ manage*(写),所以 36 个 tool 其实只需要记 ~18 对概念:

类别tool 数主要 tool
认证 + 环境3auth 登录、envQuery 查环境/配额、envDomainManagement 安全域名
数据库(NoSQL / MySQL / 数据模型)8NoSQL 4 个:readNoSqlDatabaseStructure / writeNoSqlDatabaseStructure(集合 + 索引)、readNoSqlDatabaseContent / writeNoSqlDatabaseContent(数据增删改查);MySQL 2 个:querySqlDatabase / manageSqlDatabase;数据模型 2 个:manageDataModel / modifyDataModel
云函数2queryFunctions 查列表/详情/日志/触发器、manageFunctions 创建/更新/调用/删除/管理触发器
部署(静态托管 + 云托管 + 云存储 + 网关)8queryHosting / manageHosting、queryCloudRun / manageCloudRun、queryStorage / manageStorage、queryGateway / manageGateway
应用控制(应用认证 + 权限 + 应用 + AI Agent)8queryAppAuth / manageAppAuth、queryPermissions / managePermissions、queryApps / manageApps、queryAgents / manageAgents
通用(搜索 + 模板 + 日志 + 云 API + 激励)7searchWeb、searchKnowledgeBase、downloadTemplate、downloadRemoteFile、queryLogs、callCloudApi、activateInviteCode

完整 spec 见 cloudbase-mcp tools 文档。

第四步:实战 — "帮我做一个待办应用"​

打开 Claude Code,输入:

帮我做一个待办应用,数据存在 CloudBase 数据库,
前端用 React + Vite,部署到 CloudBase 静态托管。

(可选:先打 /spec 让 Claude Code 按 plan 拆步再开干)

Claude Code 自动调用一系列 tool,日志大概长这样:

✓ writeNoSqlDatabaseStructure   # 创建 todos 集合 + createdAt 索引
✓ 本地起 React + Vite 项目(npm create vite@latest todos-app)
✓ 写 src/api.ts 调 CloudBase Web SDK,init + signIn(自动用 envId)
✓ 写 src/App.tsx,列表 / 输入框 / 删除按钮
✓ npm install
✓ npm run build
✓ manageHosting                  # 上传 ./dist 到 /todos
✓ 返回 hosting URL: https://<envId>-xxx.tcloudbaseapp.com/todos

整套 5-15 分钟。期间 Claude 偶尔会在决策点(比如"要不要加匿名登录""列表要不要分页")暂停问你,你回答后它继续往下走。

第五步:运行验证​

  1. claude mcp list 显示 cloudbase: ✓ Connected
  2. 在 Claude Code 里打 /tools,能看到 36 个 cloudbase.xxx tool 在列表中
  3. 第四步部署后浏览器打开返回的 hosting URL,能看到待办应用页面
  4. CloudBase 控制台 → 数据库,能看到 todos 集合 + Claude 测试时写入的几条记录
  5. 控制台 → 概览,API 调用次数应该有几十次的增长(每个 tool 调用都计一次)

常见错误​

错误信息 / 现象原因修复
claude mcp list 显示 cloudbase ✗ failed to connect凭证没注入,或本地 npm registry 拉不到包先手动跑 npx -y @cloudbase/cloudbase-mcp@latest --version 看是否能拉包;通了再用 claude mcp remove cloudbase 后用带 -e 的命令重新 add
Claude 调 tool 报 getCredential failed / signature mismatchSecretId / SecretKey 错或权限不够去 访问密钥 重新生成一组;生产环境用子账号密钥并通过 CAM 策略锁定到当前 env
environment not found / env id invalidCLOUDBASE_ENV_ID 拼错或环境被删控制台 → 概览,复制当前环境的 envId(不是别名),重新 claude mcp remove cloudbase + claude mcp add -e CLOUDBASE_ENV_ID=...
Tool 返回 quota exceeded / rate limit当前套餐的 API 调用配额到上限控制台 → 计费,看 API 调用余量;免费版有调用次数限制,升级套餐或等下个月重置
Claude 反复用 signInAnonymously() 生成代码旧 prompt 模板残留装第二步的 cloudbase-skills 包后,Claude 会按当前推荐用 @cloudbase/node-sdk 服务端凭证模式,详见 add-ai-nextjs

错误码完整定义参考 https://docs.cloudbase.net/error-code/。

计费提示​

  • @cloudbase/cloudbase-mcp 包本身免费,装 + 调用 MCP 不收费
  • 实际计费的是被 tool 操作的 CloudBase 资源(数据库读写、云函数调用、静态托管流量),按 CloudBase 标准计费走
  • Claude Code 本身按 Anthropic 订阅(Sonnet / Opus)计费,与 CloudBase 无关
  • .gitignore 加 .claude/(防止 claude mcp add -e 注入的密钥被提交);生产环境密钥放公司密钥管理服务,别用个人电脑 CAM 主账号密钥

相关文档​