腾讯云 COS 技能

通过 cos-mcp MCP 工具 + Node.js SDK 脚本 + COSCMD 管理腾讯云对象存储和数据万象。

首次使用 — 自动设置

当用户首次要求操作 COS 时，按以下流程操作：

步骤 1：检查当前状态

{baseDir}/scripts/setup.sh --check-only

如果输出显示一切 OK（cos-mcp 已安装、凭证已配置），跳到「执行策略」。

步骤 2：如果未配置，引导用户提供凭证

告诉用户：

我需要你的腾讯云凭证来连接 COS 存储服务。请提供：

1. SecretId— 腾讯云 API 密钥 ID
2. SecretKey— 腾讯云 API 密钥 Key
3. Region— 存储桶区域（如 ap-guangzhou）
4. Bucket— 存储桶名称（格式 name-appid，如 mybucket-1250000000）
5. DatasetName（可选） — 数据万象数据集名称（仅智能搜索需要）
6. Domain（可选） — 自定义域名，用于替换默认的 COS 访问域名（如 cdn.example.com）
7. ServiceDomain（可选） — 自定义服务域名，用于自定义 COS API 请求域名
8. Protocol(Optional) — Protocol, such as https or http

You canTencent Cloud Console > Access Management > API Key Managementobtain the key, and in theCOS Consoleview bucket information.

Step 3: After the user provides credentials, run automatic setup

{baseDir}/scripts/setup.sh --secret-id "<SecretId>" --secret-key "<SecretKey>" --region "<Region>" --bucket "<Bucket>"

If there is a DatasetName:

{baseDir}/scripts/setup.sh --secret-id "<SecretId>" --secret-key "<SecretKey>" --region "<Region>" --bucket "<Bucket>" --dataset "<DatasetName>"

If a custom domain is needed (optional parameters can be added as required):

{baseDir}/scripts/setup.sh --secret-id "<SecretId>" --secret-key "<SecretKey>" --region "<Region>" --bucket "<Bucket>" --domain "<Domain>" --service-domain "<ServiceDomain>" --protocol "<Protocol>"

The script will automatically:

• Check and install mcporter (MCP command-line tool)
• Check and install cos-mcp and cos-nodejs-sdk-v5
• Create/update~/.mcporter/mcporter.json, write the cos-mcp server configuration
• Write credentials to the shell configuration file (~/.zshrcor~/.bashrc), so they remain available after restart
• Configure coscmd (if a Python environment exists)
• Verify COS connection

After setup is complete, you can start using it.

Execution Strategy

Three methods in descending order of priority ensure the operation can always be completed:

1. Option 1: cos-mcp MCP Tool(Priority) — Most comprehensive features, supports storage + image processing + intelligent search + document/media processing
2. Option 2: Node.js SDK Script— Perform storage operations viascripts/cos_node.mjs Option 3: COSCMD Command Line
3. — Perform storage operations via shell commandsCheck for Option 1 (mcporter)

mcporter + cos-mcp 可用？（which mcporter && 配置存在）
  ├─ 是 → 使用方式一 mcporter 调用（全部功能）
  └─ 否 → cos-mcp MCP 工具可直接调用？（getCosConfig 返回结果）
              ├─ 是 → 使用方式一直接调用（全部功能）
              └─ 否 → Node.js + cos-nodejs-sdk-v5 可用？
                        ├─ 是 → 使用方式二（存储操作）
                        └─ 否 → coscmd 可用？（which coscmd）
                                  ├─ 是 → 使用方式三（存储操作）
                                  └─ 否 → 运行 setup.sh 安装

:which mcporterandcat ~/.mcporter/mcporter.json | grep cos-mcpproduces output.Check for Option 1 (direct): Attempt to call thegetCosConfigMCP tool; if it returns a result, it's available.Check for Option 2:node -e "require('cos-nodejs-sdk-v5')"If successful, it's available.Check for Option 3:which coscmdIf there is output, it's available.有输出则可用。

方法一：cos-mcp MCP 工具（优先）

GitHub：https://github.com/Tencent/cos-mcp

MCP 配置模板见references/config_template.json。

调用方式

通过 mcporter 命令行调用 cos-mcp MCP 工具：

mcporter call cos-mcp.<tool_name> --config ~/.mcporter/mcporter.json --output json [--args '<JSON>']

列出所有可用工具：

mcporter list cos-mcp --config ~/.mcporter/mcporter.json --schema

检查 mcporter 是否可用：which mcporter并且~/.mcporter/mcporter.json包含 cos-mcp 配置。 如果 mcporter 不可用，可以回退到客户端直接调用 MCP 工具（例如getCosConfig等）。

工具总览

Common Operations

The following examples demonstrate two calling formats simultaneously. The mcporter format omits the common prefixmcporter call cos-mcp.and--config ~/.mcporter/mcporter.json --output json. Complete mcporter command:mcporter call cos-mcp.<tool> --config ~/.mcporter/mcporter.json --output json --args '<JSON>'

Storage

# 上传本地文件（mcporter 格式）
mcporter call cos-mcp.putObject --config ~/.mcporter/mcporter.json --output json --args '{"filePath":"/path/to/file.jpg","targetDir":"images"}'

# 上传本地文件（客户端直接调用格式）
putObject  filePath="/path/to/file.jpg"  targetDir="images"

# 上传字符串内容
putString  content="hello world"  fileName="test.txt"  targetDir="docs"

# 通过 URL 上传
putObjectSourceUrl  sourceUrl="https://example.com/image.png"  targetDir="images"

# 列出文件
getBucket  Prefix="images/"

# 下载文件
getObject  objectKey="images/photo.jpg"

# 获取签名下载链接
getObjectUrl  objectKey="images/photo.jpg"

Image Processing

# 图片质量评估
assessQuality  objectKey="images/photo.jpg"

# AI 超分辨率
aiSuperResolution  objectKey="images/photo.jpg"

# AI 智能抠图
aiPicMatting  objectKey="images/photo.jpg"

# 二维码识别
aiQrcode  objectKey="images/qrcode.jpg"

# 添加文字水印
waterMarkFont  objectKey="images/photo.jpg"  text="版权所有"

# 获取图片元信息
imageInfo  objectKey="images/photo.jpg"

Intelligent Search (Requires Pre-built Dataset)

# 以图搜图
imageSearchPic  uri="https://example.com/query.jpg"

# 文本搜图
imageSearchText  text="蓝天白云"

Document and Media Processing (Asynchronous Tasks)

# 文档转 PDF
createDocToPdfJob  objectKey="docs/report.docx"
# 查询任务结果
describeDocProcessJob  jobId="<jobId>"

# 视频智能封面
createMediaSmartCoverJob  objectKey="videos/demo.mp4"
# 查询任务结果
describeMediaJob  jobId="<jobId>"

For detailed parameter definitions of tools, seereferences/api_reference.md.

Method Two: Node.js SDK Script

Official Documentation:https://www.tencentcloud.com/zh/document/product/436/8629

When cos-mcp is unavailable, storage operations can be performed viascripts/cos_node.mjs. Credentials are read from environment variables.

Supported environment variables:

• TENCENT_COS_SECRET_ID/TENCENT_COS_SECRET_KEY/TENCENT_COS_REGION/TENCENT_COS_BUCKET（必需）
• TENCENT_COS_DOMAIN/TENCENT_COS_SERVICE_DOMAIN/TENCENT_COS_PROTOCOL（可选，自定义域名）

常用命令

以下省略node {baseDir}/scripts/cos_node.mjs前缀。完整格式：node {baseDir}/scripts/cos_node.mjs <action> [options]

# 上传文件
upload --file /path/to/file.jpg --key remote/path/file.jpg

# 上传字符串
put-string --content "文本内容" --key remote/file.txt --content-type "text/plain"

# 下载文件
download --key remote/path/file.jpg --output /path/to/save/file.jpg

# 列出文件
list --prefix "images/"

# 获取签名 URL
sign-url --key remote/path/file.jpg --expires 3600

# 查看文件信息
head --key remote/path/file.jpg

# 删除文件
delete --key remote/path/file.jpg

所有命令输出 JSON 格式，success: true表示成功，退出码 0。

限制

仅支持存储操作，不支持图片处理、智能搜索、文档转换。

方式三：COSCMD 命令行

官方文档:https://www.tencentcloud.com/zh/document/product/436/10976

当方式一和方式二均不可用时使用。配置持久化在~/.cos.conf。

自定义域名支持（有限）：

• ServiceDomain— 对应 coscmd 的-e ENDPOINT参数，设置后 Region 失效
• Protocol— 若为http，对应 coscmd 的--do-not-use-ssl参数
• Domain— COSCMD 不支持 CDN 自定义域名

常用命令

# 上传
coscmd upload /path/to/file.jpg remote/path/file.jpg
coscmd upload -r /path/to/folder/ remote/folder/

# 下载
coscmd download remote/path/file.jpg /path/to/save/file.jpg
coscmd download -r remote/folder/ /path/to/save/

# 列出文件
coscmd list images/

# 删除
coscmd delete remote/path/file.jpg
coscmd delete -r remote/folder/ -f

# 签名 URL
coscmd signurl remote/path/file.jpg -t 3600

# 文件信息
coscmd info remote/path/file.jpg

# 复制/移动
coscmd copy <BucketName-APPID>.cos.<Region>.myqcloud.com/source.jpg dest.jpg
coscmd move <BucketName-APPID>.cos.<Region>.myqcloud.com/source.jpg dest.jpg

限制

仅支持存储操作，不支持图片处理、智能搜索、文档转换。

功能对照表

使用规范

1. 首次使用先运行 {baseDir}/scripts/setup.sh --check-only检查环境
2. mcporter 调用必须带 --config ~/.mcporter/mcporter.json和--output json
3. 凭证不明文展示：引导用户自行通过 setup.sh 或编辑配置文件设置
4. 所有文件路径（objectKey/cospath/--key）为存储桶内的相对路径，如images/photo.jpg
5. 图片处理/智能搜索/文档转换仅方式一可用，不可用时明确告知用户
6. 异步任务（文档转换、视频封面）需通过jobId轮询结果
7. 上传后主动获取链接：上传完成后调用getObjectUrl或sign-url返回访问链接
8. 错误处理：调用失败时先用setup.sh --check-only诊断环境问题
9. 方式二脚本源码见scripts/cos_node.mjs
10. MCP 工具详细参数见references/api_reference.md
11. MCP 配置模板见references/config_template.json