Skill: Tencent Cloud COS

Owner: ShawnMinh

Summary: 腾讯云对象存储(COS)和数据万象(CI)集成技能。当用户需要上传、下载、管理云存储文件， 或需要进行图片处理（质量评估、超分辨率、抠图、二维码识别、水印）、智能图片搜索、 文档转PDF、视频智能封面生成等操作时使用此技能。

Tags: latest:1.0.5

Version history:

v1.0.5 | 2026-02-28T11:25:17.074Z | auto

Version 1.0.5

• Added scripts/setup.sh for automated environment and credential setup, including installation checks and credential configuration.
• Updated documentation in SKILL.md to describe the new setup script, automatic installation/checking, and how to initialize credentials for first-time users.
• Enhanced usage workflow: now recommends running setup.sh for environment verification and credential setup, streamlining the onboarding and troubleshooting process.
• Updated metadata in SKILL.md to specify dependency install steps for related CLI tools and SDKs.
• Revised instructions for multi-backend fallback (mcporter/cos-mcp, Node.js SDK, coscmd) to account for the setup script and new configuration standards.
• Minor clarifications and consistency improvements across usage and best practice sections.

v1.0.1 | 2026-02-28T09:52:52.435Z | user

v1.0.1 Changelog

• Major cleanup: removed 12 files including README, docs, examples, and legacy config/scripts; now only core references and primary script are kept.
• Added concise config template (references/config_template.json), streamlined API reference, and new executable Node.js script (scripts/cos_node.mjs).
• Refactored documentation: new SKILL.md focuses on three-tier fallback execution (cos-mcp, Node.js SDK, COSCMD) with clear usage and capability mapping.
• Reduced duplication and deprecated legacy Python scripts, shell helpers, and test assets.
• All environment and tool instructions centralized in a single reference for easier maintenance.

v1.0.0 | 2026-02-05T04:25:34.805Z | user

• Initial release of the tencentcloud-cos-skill (version 1.0.0)
• Integrates Tencent Cloud Object Storage (COS) and CI features via official MCP server for Clawdbot
• Supports file operations (upload, download, list, delete), image processing (super resolution, background removal, watermark, QR code, etc.), intelligent search (by text and image), and document/video processing
• Provides clear installation, configuration, and usage instructions
• Includes troubleshooting, best security practices, and customization options

Archive index:

Archive v1.0.5: 6 files, 13791 bytes

Files: references/api_reference.md (6778b), references/config_template.json (2403b), scripts/cos_node.mjs (6526b), scripts/setup.sh (9963b), SKILL.md (10981b), _meta.json (142b)

File v1.0.5:SKILL.md

---

name: tencent-cloud-cos description: > 腾讯云对象存储(COS)和数据万象(CI)集成技能。当用户需要上传、下载、管理云存储文件， 或需要进行图片处理（质量评估、超分辨率、抠图、二维码识别、水印）、智能图片搜索、 文档转PDF、视频智能封面生成等操作时使用此技能。 metadata: { "openclaw": { "emoji": "☁️", "requires": {}, "install": [ { "id": "node-mcporter", "kind": "node", "package": "mcporter", "bins": ["mcporter"], "label": "Install mcporter (MCP CLI)", }, { "id": "node-cos-mcp", "kind": "node", "package": "cos-mcp", "bins": ["cos-mcp"], "label": "Install cos-mcp (COS MCP Server)", }, { "id": "node-cos-sdk", "kind": "node", "package": "cos-nodejs-sdk-v5", "label": "Install COS Node.js SDK", }, ], }, }

腾讯云 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（可选） — 数据万象数据集名称（仅智能搜索需要）

你可以在 腾讯云控制台 > 访问管理 > API密钥管理 获取密钥， 在 COS 控制台 查看存储桶信息。

步骤 3：用户提供凭证后，运行自动设置

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

如有 DatasetName：

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

脚本会自动：

• 检查并安装 mcporter（MCP 命令行工具）
• 检查并安装 cos-mcp 和 cos-nodejs-sdk-v5
• 创建/更新 ~/.mcporter/mcporter.json，写入 cos-mcp 服务器配置
• 将凭证写入 shell 配置文件（~/.zshrc 或 ~/.bashrc），重启后仍可用
• 配置 coscmd（如有 Python 环境）
• 验证 COS 连接

设置完成后即可开始使用。

执行策略

三种方式按优先级降级，确保操作始终可完成：

1. 方式一：cos-mcp MCP 工具（优先） — 功能最全，支持存储 + 图片处理 + 智能搜索 + 文档媒体处理
2. 方式二：Node.js SDK 脚本 — 通过 scripts/cos_node.mjs 执行存储操作
3. 方式三：COSCMD 命令行 — 通过 shell 命令执行存储操作

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

判断方式一(mcporter)：which mcporter 且 cat ~/.mcporter/mcporter.json | grep cos-mcp 有输出。 判断方式一(直接)：尝试调用 getCosConfig MCP 工具，若返回结果则可用。 判断方式二：node -e "require('cos-nodejs-sdk-v5')" 成功则可用。 判断方式三：which coscmd 有输出则可用。

---

方式一：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 等）。

工具总览

| 类别 | 说明 | |------|------| | 存储操作 | 上传、下载、列出、获取签名URL | | 图片处理 | 质量评估、超分辨率、抠图、二维码识别、水印 | | 智能搜索 | 以图搜图、文本搜图（需预建数据集） | | 文档媒体 | 文档转PDF、视频智能封面（异步任务） |

常用操作

以下示例同时展示两种调用格式。mcporter 格式省略公共前缀 mcporter call cos-mcp. 和 --config ~/.mcporter/mcporter.json --output json。 完整 mcporter 命令：mcporter call cos-mcp.<tool> --config ~/.mcporter/mcporter.json --output json --args '<JSON>'

存储

# 上传本地文件（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"

图片处理

# 图片质量评估
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"

智能搜索（需预建数据集）

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

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

文档与媒体处理（异步任务）

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

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

工具详细参数定义见 references/api_reference.md。

---

方式二：Node.js SDK 脚本

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

当 cos-mcp 不可用时，通过 scripts/cos_node.mjs 执行存储操作。凭证从环境变量读取。

常用命令

以下省略 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。

常用命令

# 上传
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

限制

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

---

功能对照表

| 功能 | 方式一 cos-mcp | 方式二 Node SDK | 方式三 COSCMD | |------|:-:|:-:|:-:| | 上传文件 | ✅ | ✅ | ✅ | | 上传字符串/Base64 | ✅ | ✅ | ❌ | | 通过 URL 上传 | ✅ | ❌ | ❌ | | 下载文件 | ✅ | ✅ | ✅ | | 列出文件 | ✅ | ✅ | ✅ | | 获取签名 URL | ✅ | ✅ | ✅ | | 删除文件 | ❌ | ✅ | ✅ | | 查看文件信息 | ❌ | ✅ | ✅ | | 递归上传/下载目录 | ❌ | ❌ | ✅ | | 图片处理（CI） | ✅ | ❌ | ❌ | | 智能搜索 | ✅ | ❌ | ❌ | | 文档转 PDF | ✅ | ❌ | ❌ | | 视频智能封面 | ✅ | ❌ | ❌ |

使用规范

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

File v1.0.5:_meta.json

{ "ownerId": "kn75r0rammt45k8qe5we0sh63580c5y0", "slug": "tencentcloud-cos-skills", "version": "1.0.5", "publishedAt": 1772277917074 }

File v1.0.5:references/api_reference.md

腾讯云 COS 操作参考

本文档记录三种操作方式的详细参数定义，供执行操作时查阅。

环境设置：首次使用请运行 scripts/setup.sh，详见 SKILL.md 首次使用章节。

官方文档链接：

• cos-mcp GitHub: https://github.com/Tencent/cos-mcp
• COS Node.js SDK: https://www.tencentcloud.com/zh/document/product/436/8629
• COSCMD 工具: https://www.tencentcloud.com/zh/document/product/436/10976

---

方式一：cos-mcp MCP 工具参数参考

存储操作工具

getCosConfig

获取当前 COS 配置信息。

• 参数：无

putObject

上传本地文件到存储桶。

• filePath (string, 必需): 本地文件路径（包含文件名）
• fileName (string, 可选): 存储桶中的文件名
• targetDir (string, 可选): 存储桶中的目标目录

putString

上传字符串内容到存储桶。

• content (string, 必需): 要上传的字符串内容
• fileName (string, 必需): 存储桶中的文件名
• targetDir (string, 可选): 目标目录
• contentType (string, 可选): MIME 类型，默认 text/plain

putBase64

上传 base64 编码内容到存储桶。

• base64Content (string, 必需): base64 编码的内容
• fileName (string, 必需): 存储桶中的文件名
• targetDir (string, 可选): 目标目录
• contentType (string, 可选): MIME 类型，如 image/png、application/pdf

putBuffer

上传 buffer 内容到存储桶。

• content (string, 必需): buffer 内容字符串
• fileName (string, 必需): 存储桶中的文件名
• targetDir (string, 可选): 目标目录
• contentType (string, 可选): MIME 类型，默认 application/octet-stream
• encoding (string, 可选): 编码格式，枚举值: hex | base64 | utf8 | ascii | binary，默认 utf8

putObjectSourceUrl

通过 URL 下载文件并上传到存储桶。

• sourceUrl (string, 必需): 可下载的文件 URL
• fileName (string, 可选): 存储桶中的文件名
• targetDir (string, 可选): 目标目录

getObject

下载存储桶内的文件。

• objectKey (string, 必需): 文件在存储桶中的路径

getBucket

查询存储桶内的文件列表。

• Prefix (string, 可选): 路径前缀过滤，默认根路径

getObjectUrl

获取文件的带签名下载链接。

• objectKey (string, 必需): 文件在存储桶中的路径

图片处理工具

imageInfo

获取图片元数据信息。

• objectKey (string, 必需): 图片在存储桶中的路径

assessQuality

评估图片质量分数。

• objectKey (string, 必需): 图片在存储桶中的路径

aiSuperResolution

AI 超分辨率，提升图片分辨率。

• objectKey (string, 必需): 图片在存储桶中的路径

aiPicMatting

AI 智能抠图，去除图片背景。

• objectKey (string, 必需): 图片在存储桶中的路径
• width (string, 可选): 输出宽度
• height (string, 可选): 输出高度

aiQrcode

识别存储桶内图片中的二维码内容。

• objectKey (string, 必需): COS 对象键完整路径，如 images/qrcode.jpg

waterMarkFont

生成带文字水印的图片。

• objectKey (string, 必需): COS 对象键完整路径，如 images/photo.jpg
• text (string, 可选): 水印文字内容（支持中文），默认 test

智能搜索工具

imageSearchPic

以图搜图，从数据集中检索相似图片。

• uri (string, 必需): 图片地址

imageSearchText

文本搜图，根据文字描述检索匹配图片。

• text (string, 必需): 检索文本

文档与媒体处理工具

createDocToPdfJob

创建文档转 PDF 处理任务。

• objectKey (string, 必需): 文档在存储桶中的路径

describeDocProcessJob

查询文档转码任务结果。

• jobId (string, 必需): 任务 ID（通过提交文档任务的响应获取）

createMediaSmartCoverJob

创建视频智能封面任务。

• objectKey (string, 必需): 视频在存储桶中的路径

describeMediaJob

查询智能封面任务结果。

• jobId (string, 必需): 任务 ID（通过提交智能封面任务的响应获取）

---

方式二：scripts/cos_node.mjs 命令参考

脚本位于 scripts/cos_node.mjs，依赖 cos-nodejs-sdk-v5（npm install cos-nodejs-sdk-v5）。 所有凭证通过环境变量读取。输出 JSON 格式。

可用操作

| 操作 | 命令 | 说明 | |------|------|------| | upload | node scripts/cos_node.mjs upload --file <path> --key <key> | 上传本地文件 | | put-string | node scripts/cos_node.mjs put-string --content <text> --key <key> [--content-type <mime>] | 上传字符串内容 | | download | node scripts/cos_node.mjs download --key <key> --output <path> | 下载文件到本地 | | list | node scripts/cos_node.mjs list [--prefix <prefix>] [--max-keys <n>] | 列出文件 | | sign-url | node scripts/cos_node.mjs sign-url --key <key> [--expires <seconds>] | 获取签名下载链接 | | delete | node scripts/cos_node.mjs delete --key <key> | 删除文件 | | head | node scripts/cos_node.mjs head --key <key> | 查看文件元信息 |

返回格式

成功时 success: true，退出码 0；失败时 success: false，退出码 1。

---

方式三：COSCMD 命令参考

依赖 Python，通过 pip install coscmd 安装。首次使用需配置（写入 ~/.cos.conf，后续无需重复）：

coscmd config -a $TENCENT_COS_SECRET_ID -s $TENCENT_COS_SECRET_KEY -b $TENCENT_COS_BUCKET -r $TENCENT_COS_REGION

常用命令

| 操作 | 命令 | 说明 | |------|------|------| | 上传文件 | coscmd upload <localpath> <cospath> | 上传单个文件 | | 递归上传目录 | coscmd upload -r <localdir> <cosdir> | 上传整个目录 | | 下载文件 | coscmd download <cospath> <localpath> | 下载单个文件 | | 递归下载目录 | coscmd download -r <cosdir> <localdir> | 下载整个目录 | | 列出文件 | coscmd list [cospath] | 列出文件，加 -r 递归 | | 删除文件 | coscmd delete <cospath> | 删除单个文件 | | 递归删除 | coscmd delete -r <cosdir> -f | 强制递归删除 | | 签名 URL | coscmd signurl <cospath> [-t <seconds>] | 获取带签名的下载链接 | | 文件信息 | coscmd info <cospath> | 查看文件元信息 | | 复制 | coscmd copy <source> <dest> | 桶内/跨桶复制 | | 移动 | coscmd move <source> <dest> | 移动文件（复制+删除源） |

全局参数

• -c <CONFIG_PATH>：指定配置文件路径（默认 ~/.cos.conf）
• -b <BucketName-APPID>：指定存储桶（覆盖配置文件）
• -r <Region>：指定区域
• -d：调试模式，输出详细日志

File v1.0.5:references/config_template.json

{ "_description": "cos-mcp MCP 服务器配置模板，添加到客户端的 MCP 配置文件中",

"mcpServers": { "cos-mcp": { "_comment": "方式一：参数直接传入 args", "command": "npx", "args": [ "cos-mcp", "--Region=<替换为存储桶区域，如 ap-guangzhou>", "--Bucket=<替换为存储桶名称，格式 name-appid>", "--SecretId=<替换为腾讯云 API 密钥 ID>", "--SecretKey=<替换为腾讯云 API 密钥 Key>", "--DatasetName=<替换为数据万象数据集名称，无则删除此行>", "--connectType=stdio" ] },

"cos-mcp-env": {
  "_comment": "方式二：通过 env 传递敏感参数（推荐）",
  "command": "npx",
  "args": [
    "cos-mcp",
    "--connectType=stdio"
  ],
  "env": {
    "TENCENT_COS_SECRET_ID": "<替换为腾讯云 API 密钥 ID>",
    "TENCENT_COS_SECRET_KEY": "<替换为腾讯云 API 密钥 Key>",
    "TENCENT_COS_REGION": "<替换为存储桶区域，如 ap-guangzhou>",
    "TENCENT_COS_BUCKET": "<替换为存储桶名称，格式 name-appid>",
    "TENCENT_COS_DATASET_NAME": "<替换为数据万象数据集名称，无则删除此行>"
  }
},

"cos-mcp-sse": {
  "_comment": "方式三：SSE 模式（适合高频调用场景）",
  "command": "npx",
  "args": [
    "cos-mcp",
    "--connectType=sse",
    "--port=3001"
  ],
  "env": {
    "TENCENT_COS_SECRET_ID": "<替换为腾讯云 API 密钥 ID>",
    "TENCENT_COS_SECRET_KEY": "<替换为腾讯云 API 密钥 Key>",
    "TENCENT_COS_REGION": "<替换为存储桶区域，如 ap-guangzhou>",
    "TENCENT_COS_BUCKET": "<替换为存储桶名称，格式 name-appid>"
  }
}

},

"_参数说明": { "Region": "存储桶区域，如 ap-guangzhou、ap-shanghai、ap-beijing 等", "Bucket": "存储桶名称，格式为 name-appid，如 mybucket-1250000000", "SecretId": "腾讯云 API 密钥 ID，在 访问管理 > API密钥管理 中创建", "SecretKey": "腾讯云 API 密钥 Key，与 SecretId 配对使用", "DatasetName": "数据万象数据集名称（仅图片搜索等智能功能需要，无则不填）", "connectType": "连接模式：stdio（默认，推荐）或 sse", "port": "SSE 模式下的监听端口（默认 3001）" } }

Archive v1.0.1: 5 files, 10635 bytes

Files: references/api_reference.md (6675b), references/config_template.json (2403b), scripts/cos_node.mjs (6526b), SKILL.md (12045b), _meta.json (142b)

File v1.0.1:SKILL.md

---

name: tencent-cloud-cos description: > 腾讯云对象存储(COS)和数据万象(CI)集成技能。当用户需要上传、下载、管理云存储文件， 或需要进行图片处理（质量评估、超分辨率、抠图、二维码识别、水印）、智能图片搜索、 文档转PDF、视频智能封面生成等操作时使用此技能。

腾讯云 COS 技能

集成腾讯云对象存储(COS)和数据万象(CI)的完整能力。提供三种执行方式按优先级降级，确保操作始终可完成：

1. 方式一：cos-mcp MCP 工具（优先） — 功能最全，支持存储操作 + 图片处理 + 智能搜索 + 文档媒体处理
2. 方式二：COS Node.js SDK 脚本 — 通过 scripts/cos_node.mjs 执行存储操作
3. 方式三：COSCMD 命令行工具 — 通过 shell 命令执行存储操作

执行策略

按以下顺序尝试，遇到失败自动降级到下一种方式：

cos-mcp MCP 工具可用？（先安装再检测）
  ├─ 是 → 使用方式一（全部功能）
  └─ 否 → Node.js 可用？（node --version）
              ├─ 是 → 安装 cos-nodejs-sdk-v5（若未安装）→ 使用方式二（存储操作）
              └─ 否 → coscmd 命令可用？（which coscmd）
                        ├─ 是 → 使用方式三（存储操作）
                        └─ 否 → 提示用户安装任一工具

判断方式一是否可用：

1. 先在当前项目安装 cos-mcp：npm install cos-mcp（若无 package.json 先 npm init -y）
2. 尝试调用 getCosConfig MCP 工具，若工具存在且返回结果则可用
3. 若 MCP 工具仍不可用（客户端未配置 MCP 服务器），则降级到方式二

判断方式二是否可用：执行 node --version 确认 Node.js 可用，然后检查 cos-nodejs-sdk-v5 是否已安装（node -e "require('cos-nodejs-sdk-v5')"），若未安装则先执行 npm install cos-nodejs-sdk-v5 安装后再使用。 判断方式三是否可用：执行 which coscmd 或 coscmd --version 有输出则可用。

环境配置

三种方式均需要以下腾讯云凭证：

| 参数 | 说明 | 示例 | |------|------|------| | SecretId | API 密钥 ID | AKIDxxxxxxxx | | SecretKey | API 密钥 Key | xxxxxxxx | | Region | 存储桶区域 | ap-guangzhou | | Bucket | 存储桶名称 | mybucket-1250000000 | | DatasetName | 数据万象数据集名称（仅智能搜索需要） | my-dataset |

凭证持久化

各方式的凭证存储位置不同，配置一次后重启会话无需重新设置：

| 方式 | 持久化位置 | 说明 | |------|-----------|------| | 方式一 cos-mcp | 客户端 MCP 配置文件 | 写入后由客户端自动加载，无需重复配置 | | 方式二 Node SDK | shell 配置文件（~/.zshrc 或 ~/.bashrc） | 需将环境变量写入 shell 配置文件 | | 方式三 COSCMD | ~/.cos.conf | coscmd config 自动写入，后续直接可用 |

方式二环境变量持久化：首次配置时将凭证写入 shell 配置文件：

cat >> ~/.zshrc << 'EOF'
export TENCENT_COS_SECRET_ID="<替换为 API 密钥 ID>"
export TENCENT_COS_SECRET_KEY="<替换为 API 密钥 Key>"
export TENCENT_COS_REGION="<替换为存储桶区域>"
export TENCENT_COS_BUCKET="<替换为存储桶名称>"
EOF
source ~/.zshrc

若使用 bash，将 ~/.zshrc 替换为 ~/.bashrc。

密钥信息不要在对话中明文展示，引导用户自行编辑配置文件设置。

---

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

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

安装配置

1. 安装 cos-mcp 到当前项目

npm install cos-mcp

若当前目录无 package.json，先执行 npm init -y。

2. 在客户端 MCP 配置中注册

在客户端（Claude Desktop、CodeBuddy 等）的 MCP 配置文件中注册：

{
  "mcpServers": {
    "cos-mcp": {
      "command": "npx",
      "args": ["cos-mcp", "--connectType=stdio"],
      "env": {
        "TENCENT_COS_SECRET_ID": "<SecretId>",
        "TENCENT_COS_SECRET_KEY": "<SecretKey>",
        "TENCENT_COS_REGION": "<Region>",
        "TENCENT_COS_BUCKET": "<Bucket>"
      }
    }
  }
}

完整配置模板见 references/config_template.json。

存储操作工具

| 工具 | 用途 | 必需参数 | 可选参数 | |------|------|----------|----------| | getCosConfig | 获取当前配置信息 | 无 | 无 | | putObject | 上传本地文件 | filePath | fileName, targetDir | | putString | 上传字符串内容 | content, fileName | targetDir, contentType | | putBase64 | 上传 base64 内容 | base64Content, fileName | targetDir, contentType | | putBuffer | 上传 buffer 内容 | content, fileName | targetDir, contentType, encoding | | putObjectSourceUrl | 通过 URL 上传 | sourceUrl | fileName, targetDir | | getObject | 下载文件 | objectKey | 无 | | getBucket | 列出文件 | 无 | Prefix | | getObjectUrl | 获取签名下载链接 | objectKey | 无 |

图片处理工具（数据万象 CI）

| 工具 | 用途 | 必需参数 | 可选参数 | |------|------|----------|----------| | imageInfo | 获取图片元信息 | objectKey | 无 | | assessQuality | 图片质量评估 | objectKey | 无 | | aiSuperResolution | AI 超分辨率 | objectKey | 无 | | aiPicMatting | AI 智能抠图 | objectKey | width, height | | aiQrcode | 二维码识别 | objectKey | 无 | | waterMarkFont | 添加文字水印 | objectKey | text |

智能搜索工具

需要预先在数据万象控制台创建数据集。

| 工具 | 用途 | 必需参数 | |------|------|----------| | imageSearchPic | 以图搜图 | uri | | imageSearchText | 文本搜图 | text |

文档与媒体处理工具

| 工具 | 用途 | 必需参数 | |------|------|----------| | createDocToPdfJob | 文档转 PDF | objectKey | | describeDocProcessJob | 查询文档任务结果 | jobId | | createMediaSmartCoverJob | 视频智能封面 | objectKey | | describeMediaJob | 查询媒体任务结果 | jobId |

---

方式二：COS Node.js SDK 脚本

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

当 cos-mcp MCP 工具不可用时，使用 scripts/cos_node.mjs 脚本通过 cos-nodejs-sdk-v5 SDK 执行存储操作。

安装依赖

使用方式二前需确保 cos-nodejs-sdk-v5 已安装。执行检查和安装：

# 检查是否已安装
node -e "require('cos-nodejs-sdk-v5')" 2>/dev/null || npm install cos-nodejs-sdk-v5

若在用户项目中操作，建议安装到项目目录；若无 package.json，先 npm init -y 再安装。

使用方式

通过 node scripts/cos_node.mjs <action> [参数] 执行，脚本从环境变量读取凭证。

上传文件

node scripts/cos_node.mjs upload --file /path/to/local/file.jpg --key remote/path/file.jpg

上传字符串内容

node scripts/cos_node.mjs put-string --content "文本内容" --key remote/path/file.txt --content-type "text/plain"

下载文件

node scripts/cos_node.mjs download --key remote/path/file.jpg --output /path/to/save/file.jpg

列出文件

node scripts/cos_node.mjs list --prefix "images/"

获取签名 URL

node scripts/cos_node.mjs sign-url --key remote/path/file.jpg --expires 3600

删除文件

node scripts/cos_node.mjs delete --key remote/path/file.jpg

查看文件信息

node scripts/cos_node.mjs head --key remote/path/file.jpg

所有命令输出 JSON 格式结果，可通过 $? 判断成功（0）或失败（非0）。

限制

方式二仅支持存储操作（上传、下载、列表、删除、签名URL），不支持图片处理、智能搜索、文档转换等数据万象功能。

---

方式三：COSCMD 命令行工具

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

当方式一和方式二均不可用时，使用 COSCMD Python 命令行工具。

安装配置

pip install coscmd
coscmd config -a $TENCENT_COS_SECRET_ID -s $TENCENT_COS_SECRET_KEY -b $TENCENT_COS_BUCKET -r $TENCENT_COS_REGION

配置写入 ~/.cos.conf，后续使用无需重复配置。

常用命令

上传

# 上传单个文件
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 list -r images/

删除

# 删除单个文件
coscmd delete remote/path/file.jpg

# 递归删除目录
coscmd delete -r remote/folder/ -f

获取签名 URL

# 获取有效期 3600 秒的下载链接
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

限制

方式三仅支持存储操作，不支持图片处理、智能搜索、文档转换等数据万象功能。

---

功能对照表

| 功能 | 方式一 cos-mcp | 方式二 Node SDK | 方式三 COSCMD | |------|:-:|:-:|:-:| | 上传文件 | ✅ | ✅ | ✅ | | 上传字符串/Base64 | ✅ | ✅ | ❌ | | 通过 URL 上传 | ✅ | ❌ | ❌ | | 下载文件 | ✅ | ✅ | ✅ | | 列出文件 | ✅ | ✅ | ✅ | | 获取签名 URL | ✅ | ✅ | ✅ | | 删除文件 | ❌ | ✅ | ✅ | | 查看文件信息 | ❌ | ✅ | ✅ | | 递归上传/下载目录 | ❌ | ❌ | ✅ | | 图片处理（CI） | ✅ | ❌ | ❌ | | 智能搜索 | ✅ | ❌ | ❌ | | 文档转 PDF | ✅ | ❌ | ❌ | | 视频智能封面 | ✅ | ❌ | ❌ |

工作流程

文件上传

1. 按执行策略确定可用方式
2. 确认本地文件路径存在
3. 执行上传：
   • 方式一：调用 putObject，上传后调用 getObjectUrl 获取链接
   • 方式二：node scripts/cos_node.mjs upload --file <path> --key <key>，再 sign-url 获取链接
   • 方式三：coscmd upload <localpath> <cospath>，再 coscmd signurl <cospath> 获取链接
4. 返回访问链接给用户

文件下载

1. 按执行策略确定可用方式
2. 执行下载：
   • 方式一：调用 getObject
   • 方式二：node scripts/cos_node.mjs download --key <key> --output <path>
   • 方式三：coscmd download <cospath> <localpath>
3. 返回本地文件路径

图片处理（仅方式一）

1. 确认目标图片已在存储桶中（必要时先上传）
2. 调用对应图片处理工具
3. 若方式一不可用，提示用户：图片处理功能需要 cos-mcp MCP 工具支持

文档转换（仅方式一）

1. 确认文档已在存储桶中
2. 调用 createDocToPdfJob 创建任务
3. 使用 describeDocProcessJob 轮询结果
4. 若方式一不可用，提示用户：文档转换功能需要 cos-mcp MCP 工具支持

注意事项

• 所有文件路径（objectKey/cospath/--key）均为存储桶内的相对路径，如 images/photo.jpg
• 图片处理、智能搜索、文档转换等数据万象功能仅方式一可用，方式二和方式三仅覆盖基础存储操作
• 智能搜索需预先创建数据集并建立索引
• 文档转换和视频封面为异步任务，需通过 jobId 轮询结果
• 上传时如未指定目标文件名，默认使用原始文件名
• 方式二脚本源码见 scripts/cos_node.mjs
• MCP 工具详细参数参考见 references/api_reference.md
• MCP 配置模板见 references/config_template.json

File v1.0.1:_meta.json

{ "ownerId": "kn75r0rammt45k8qe5we0sh63580c5y0", "slug": "tencentcloud-cos-skills", "version": "1.0.1", "publishedAt": 1772272372435 }

File v1.0.1:references/api_reference.md

腾讯云 COS 操作参考

本文档记录三种操作方式的详细参数定义，供执行操作时查阅。

官方文档链接：

• cos-mcp GitHub: https://github.com/Tencent/cos-mcp
• COS Node.js SDK: https://www.tencentcloud.com/zh/document/product/436/8629
• COSCMD 工具: https://www.tencentcloud.com/zh/document/product/436/10976

---

方式一：cos-mcp MCP 工具参数参考

存储操作工具

getCosConfig

获取当前 COS 配置信息。

• 参数：无

putObject

上传本地文件到存储桶。

• filePath (string, 必需): 本地文件路径（包含文件名）
• fileName (string, 可选): 存储桶中的文件名
• targetDir (string, 可选): 存储桶中的目标目录

putString

上传字符串内容到存储桶。

• content (string, 必需): 要上传的字符串内容
• fileName (string, 必需): 存储桶中的文件名
• targetDir (string, 可选): 目标目录
• contentType (string, 可选): MIME 类型，默认 text/plain

putBase64

上传 base64 编码内容到存储桶。

• base64Content (string, 必需): base64 编码的内容
• fileName (string, 必需): 存储桶中的文件名
• targetDir (string, 可选): 目标目录
• contentType (string, 可选): MIME 类型，如 image/png、application/pdf

putBuffer

上传 buffer 内容到存储桶。

• content (string, 必需): buffer 内容字符串
• fileName (string, 必需): 存储桶中的文件名
• targetDir (string, 可选): 目标目录
• contentType (string, 可选): MIME 类型，默认 application/octet-stream
• encoding (string, 可选): 编码格式，枚举值: hex | base64 | utf8 | ascii | binary，默认 utf8

putObjectSourceUrl

通过 URL 下载文件并上传到存储桶。

• sourceUrl (string, 必需): 可下载的文件 URL
• fileName (string, 可选): 存储桶中的文件名
• targetDir (string, 可选): 目标目录

getObject

下载存储桶内的文件。

• objectKey (string, 必需): 文件在存储桶中的路径

getBucket

查询存储桶内的文件列表。

• Prefix (string, 可选): 路径前缀过滤，默认根路径

getObjectUrl

获取文件的带签名下载链接。

• objectKey (string, 必需): 文件在存储桶中的路径

图片处理工具

imageInfo

获取图片元数据信息。

• objectKey (string, 必需): 图片在存储桶中的路径

assessQuality

评估图片质量分数。

• objectKey (string, 必需): 图片在存储桶中的路径

aiSuperResolution

AI 超分辨率，提升图片分辨率。

• objectKey (string, 必需): 图片在存储桶中的路径

aiPicMatting

AI 智能抠图，去除图片背景。

• objectKey (string, 必需): 图片在存储桶中的路径
• width (string, 可选): 输出宽度
• height (string, 可选): 输出高度

aiQrcode

识别存储桶内图片中的二维码内容。

• objectKey (string, 必需): COS 对象键完整路径，如 images/qrcode.jpg

waterMarkFont

生成带文字水印的图片。

• objectKey (string, 必需): COS 对象键完整路径，如 images/photo.jpg
• text (string, 可选): 水印文字内容（支持中文），默认 test

智能搜索工具

imageSearchPic

以图搜图，从数据集中检索相似图片。

• uri (string, 必需): 图片地址

imageSearchText

文本搜图，根据文字描述检索匹配图片。

• text (string, 必需): 检索文本

文档与媒体处理工具

createDocToPdfJob

创建文档转 PDF 处理任务。

• objectKey (string, 必需): 文档在存储桶中的路径

describeDocProcessJob

查询文档转码任务结果。

• jobId (string, 必需): 任务 ID（通过提交文档任务的响应获取）

createMediaSmartCoverJob

创建视频智能封面任务。

• objectKey (string, 必需): 视频在存储桶中的路径

describeMediaJob

查询智能封面任务结果。

• jobId (string, 必需): 任务 ID（通过提交智能封面任务的响应获取）

---

方式二：scripts/cos_node.mjs 命令参考

脚本位于 scripts/cos_node.mjs，依赖 cos-nodejs-sdk-v5（npm install cos-nodejs-sdk-v5）。 所有凭证通过环境变量读取。输出 JSON 格式。

可用操作

| 操作 | 命令 | 说明 | |------|------|------| | upload | node scripts/cos_node.mjs upload --file <path> --key <key> | 上传本地文件 | | put-string | node scripts/cos_node.mjs put-string --content <text> --key <key> [--content-type <mime>] | 上传字符串内容 | | download | node scripts/cos_node.mjs download --key <key> --output <path> | 下载文件到本地 | | list | node scripts/cos_node.mjs list [--prefix <prefix>] [--max-keys <n>] | 列出文件 | | sign-url | node scripts/cos_node.mjs sign-url --key <key> [--expires <seconds>] | 获取签名下载链接 | | delete | node scripts/cos_node.mjs delete --key <key> | 删除文件 | | head | node scripts/cos_node.mjs head --key <key> | 查看文件元信息 |

返回格式

成功时 success: true，退出码 0；失败时 success: false，退出码 1。

---

方式三：COSCMD 命令参考

依赖 Python，通过 pip install coscmd 安装。首次使用需配置（写入 ~/.cos.conf，后续无需重复）：

coscmd config -a $TENCENT_COS_SECRET_ID -s $TENCENT_COS_SECRET_KEY -b $TENCENT_COS_BUCKET -r $TENCENT_COS_REGION

常用命令

| 操作 | 命令 | 说明 | |------|------|------| | 上传文件 | coscmd upload <localpath> <cospath> | 上传单个文件 | | 递归上传目录 | coscmd upload -r <localdir> <cosdir> | 上传整个目录 | | 下载文件 | coscmd download <cospath> <localpath> | 下载单个文件 | | 递归下载目录 | coscmd download -r <cosdir> <localdir> | 下载整个目录 | | 列出文件 | coscmd list [cospath] | 列出文件，加 -r 递归 | | 删除文件 | coscmd delete <cospath> | 删除单个文件 | | 递归删除 | coscmd delete -r <cosdir> -f | 强制递归删除 | | 签名 URL | coscmd signurl <cospath> [-t <seconds>] | 获取带签名的下载链接 | | 文件信息 | coscmd info <cospath> | 查看文件元信息 | | 复制 | coscmd copy <source> <dest> | 桶内/跨桶复制 | | 移动 | coscmd move <source> <dest> | 移动文件（复制+删除源） |

全局参数

• -c <CONFIG_PATH>：指定配置文件路径（默认 ~/.cos.conf）
• -b <BucketName-APPID>：指定存储桶（覆盖配置文件）
• -r <Region>：指定区域
• -d：调试模式，输出详细日志

File v1.0.1:references/config_template.json

{ "_description": "cos-mcp MCP 服务器配置模板，添加到客户端的 MCP 配置文件中",

"mcpServers": { "cos-mcp": { "_comment": "方式一：参数直接传入 args", "command": "npx", "args": [ "cos-mcp", "--Region=<替换为存储桶区域，如 ap-guangzhou>", "--Bucket=<替换为存储桶名称，格式 name-appid>", "--SecretId=<替换为腾讯云 API 密钥 ID>", "--SecretKey=<替换为腾讯云 API 密钥 Key>", "--DatasetName=<替换为数据万象数据集名称，无则删除此行>", "--connectType=stdio" ] },

"cos-mcp-env": {
  "_comment": "方式二：通过 env 传递敏感参数（推荐）",
  "command": "npx",
  "args": [
    "cos-mcp",
    "--connectType=stdio"
  ],
  "env": {
    "TENCENT_COS_SECRET_ID": "<替换为腾讯云 API 密钥 ID>",
    "TENCENT_COS_SECRET_KEY": "<替换为腾讯云 API 密钥 Key>",
    "TENCENT_COS_REGION": "<替换为存储桶区域，如 ap-guangzhou>",
    "TENCENT_COS_BUCKET": "<替换为存储桶名称，格式 name-appid>",
    "TENCENT_COS_DATASET_NAME": "<替换为数据万象数据集名称，无则删除此行>"
  }
},

"cos-mcp-sse": {
  "_comment": "方式三：SSE 模式（适合高频调用场景）",
  "command": "npx",
  "args": [
    "cos-mcp",
    "--connectType=sse",
    "--port=3001"
  ],
  "env": {
    "TENCENT_COS_SECRET_ID": "<替换为腾讯云 API 密钥 ID>",
    "TENCENT_COS_SECRET_KEY": "<替换为腾讯云 API 密钥 Key>",
    "TENCENT_COS_REGION": "<替换为存储桶区域，如 ap-guangzhou>",
    "TENCENT_COS_BUCKET": "<替换为存储桶名称，格式 name-appid>"
  }
}

},

"_参数说明": { "Region": "存储桶区域，如 ap-guangzhou、ap-shanghai、ap-beijing 等", "Bucket": "存储桶名称，格式为 name-appid，如 mybucket-1250000000", "SecretId": "腾讯云 API 密钥 ID，在 访问管理 > API密钥管理 中创建", "SecretKey": "腾讯云 API 密钥 Key，与 SecretId 配对使用", "DatasetName": "数据万象数据集名称（仅图片搜索等智能功能需要，无则不填）", "connectType": "连接模式：stdio（默认，推荐）或 sse", "port": "SSE 模式下的监听端口（默认 3001）" } }