tencent-cloud-cos

Tencent Cloud COS Skill

Manage Tencent Cloud Object Storage and Data万象 through cos-mcp MCP tools + Node.js SDK scripts + COSCMD.

First Use — Automatic Setup

When the user first requests a COS operation, follow this process:

Step 1: Check Current Status

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

If the output shows everything is OK (cos-mcp installed, credentials configured), skip to "Execution Strategy".

Step 2: If Not Configured, Guide the User to Provide Credentials

Tell the user:

I need your Tencent Cloud credentials to connect to the COS storage service. Please provide:

SecretId — Tencent Cloud API SecretId

SecretKey — Tencent Cloud API SecretKey

Region — Bucket region (e.g., ap-guangzhou)

Bucket — Bucket name (format name-appid, e.g., mybucket-1250000000)

DatasetName(Optional) — Data万象 dataset name (only required for intelligent search)

Domain(Optional) — Custom domain, used to replace the default COS access domain (e.g., cdn.example.com)

ServiceDomain(Optional) — Custom service domain, used to customize the COS API request domain

Protocol(Optional) — Protocol, such as https or http

You can obtain the key at Tencent Cloud Console > Access Management > API Key Management , and view bucket information at COS Console .

⚠️ Security Requirements：You must use a sub-account key, granting only COS-related permissions (such as QcloudCOSDataFullControl），Using a root account key is strictly prohibited. See the "Least Privilege and Sub-account Keys" section below for details.

Step 3: After the User Provides Credentials, Run Automatic Setup

Recommended Method(credentials will not appear in shell history):

export TENCENT_COS_SECRET_ID="<SecretId>"
export TENCENT_COS_SECRET_KEY="<SecretKey>"
export TENCENT_COS_REGION="<Region>"
export TENCENT_COS_BUCKET="<Bucket>"
# 可选：
# export TENCENT_COS_DATASET_NAME="<DatasetName>"
# export TENCENT_COS_DOMAIN="<Domain>"
# export TENCENT_COS_SERVICE_DOMAIN="<ServiceDomain>"
# export TENCENT_COS_PROTOCOL="<Protocol>"

{baseDir}/scripts/setup.sh --from-env

Alternative Method (credentials will appear in shell history, not recommended):

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

The script will automatically:

Check and locally install cos-mcp and cos-nodejs-sdk-v5 into the project node_modules（npm install, not globally)
Check and locally install mcporter into the project node_modules（npm install, not globally; invoked via npx mcporter )
Export credentials to environment variables in the current shell session (not written to ~/.zshrc / ~/.bashrc）
Create/update ~/.mcporter/mcporter.json, write the cos-mcp server configuration (credentials passed via the env field, permissions 600)
If coscmd is already installed, configure ~/.cos.conf(permissions 600);will notautomatically install coscmd
Verify COS connection

System Change Summary

Before installation, users should understand all changes that setup.sh will make:

Change Type	Specific Content	Persistence
npm local installation	`cos-mcp`、`cos-nodejs-sdk-v5`、`mcporter` installed into the project `node_modules/`	Persistent (project directory only)
Project file	If there is no `package.json` , create it	Persistent (project directory only)
Configuration file	`~/.mcporter/mcporter.json`(including credentials)	Persistent (user home directory)
Configuration file	`~/.cos.conf`(only when coscmd is installed)	Persistent (user home directory)
Environment variables	`TENCENT_COS_*` export to the current session	Temporary (invalid after closing the terminal)

⚠️ Scriptwill not：

Write to ~/.zshrc / ~/.bashrc or any shell startup file

Execute npm install -g(global installation)

Execute pip install(does not automatically install Python packages)

Modify permissions of the user's shell configuration file

Files to which credentials are written(⚠️ Persistently storing credentials increases exposure risk; see "Security Considerations" for details):

File	Content	Permissions
`~/.mcporter/mcporter.json`	The env field in the MCP server configuration contains credentials	600
`~/.cos.conf`	coscmd configuration (only when coscmd is installed)	600

To completely clean up credentials:rm -f ~/.mcporter/mcporter.json ~/.cos.conf If you need to persist environment variables, you can add the export statement to your shell configuration yourself. It is strongly recommended to use a sub-account key with least privilege, see the "Least Privilege and Sub-account Keys" section for details.

Once the setup is complete, you can start using it.

Execution Strategy

The three methods degrade by priority to ensure operations can always be completed:

Method 1: cos-mcp MCP tools(preferred) — most full-featured, supports storage + image processing + intelligent search + document and media processing
Method 2: Node.js SDK script — via scripts/cos_node.mjs to perform storage operations
Method 3: COSCMD command line — perform storage operations via shell commands

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

Determine Method 1 (mcporter)：npx mcporter --version succeeds and cat ~/.mcporter/mcporter.json | grep cos-mcp has output. Determine Method 1 (direct): try calling getCosConfig MCP tool; if it returns a result, it is available. Determine Method 2：node -e "require('cos-nodejs-sdk-v5')" succeeds, it is available. Determine Method 3：which coscmd has output, it is available.

Method 1: cos-mcp MCP tools (preferred)

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

See the MCP configuration template at references/config_template.json。

Call Format

Call the cos-mcp MCP tools via the mcporter command line:

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

List all available tools:

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

Determine whether mcporter is available：npx mcporter --version succeeds and ~/.mcporter/mcporter.json contains the cos-mcp configuration. If mcporter is unavailable, you can fall back to the client directly calling MCP tools (getCosConfig , etc.).

Tools Overview

Category	Description
Storage Operations	Upload, download, list, get signed URL
Image Processing	Quality assessment, super-resolution, cutout, QR code recognition, watermark
Intelligent Search	Image search by image, text search by image (requires a pre-built dataset)
Document Media	Document to PDF, video intelligent thumbnail (asynchronous task)

Common Operations

The following example demonstrates both invocation formats. The mcporter format omits the common prefix npx mcporter call cos-mcp. and --config ~/.mcporter/mcporter.json --output json. Full mcporter command:npx mcporter call cos-mcp.<tool> --config ~/.mcporter/mcporter.json --output json --args '<JSON>'

Storage

# 上传本地文件（mcporter 格式）
npx 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"

Smart search (requires a 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 tool parameter definitions, see references/api_reference.md。

Method 2: Node.js SDK script

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

When cos-mcp is unavailable, perform storage operations via scripts/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(required)
TENCENT_COS_DOMAIN / TENCENT_COS_SERVICE_DOMAIN / TENCENT_COS_PROTOCOL(optional, custom domain)

Common commands

The following omits the node {baseDir}/scripts/cos_node.mjs prefix. Full format: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

All commands output JSON format,success: true indicates success, exit code 0.

Limitations

Only storage operations are supported;does not supportimage processing, smart search, or document conversion.

Method 3: COSCMD command line

Official documentation: https://www.tencentcloud.com/zh/document/product/436/10976

Use when both Method 1 and Method 2 are unavailable. Configuration is persisted in ~/.cos.conf。

Custom domain support (limited):

ServiceDomain — corresponds to coscmd's -e ENDPOINT parameter; once set, Region becomes invalid
Protocol — if http, corresponds to coscmd's --do-not-use-ssl parameter
Domain — COSCMD does not support CDN custom domains

Common commands

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

Limitations

Only storage operations are supported;does not supportimage processing, smart search, or document conversion.

Feature comparison table

Feature	Method 1 cos-mcp	Method 2 Node SDK	Method 3 COSCMD
Upload file	✅	✅	✅
Upload string/Base64	✅	✅	❌
Upload via URL	✅	❌	❌
Download file	✅	✅	✅
List files	✅	✅	✅
Get signed URL	✅	✅	✅
Delete file	❌	✅	✅
View file information	❌	✅	✅
Recursively upload/download directories	❌	❌	✅
Image processing (CI)	✅	❌	❌
Smart search	✅	❌	❌
Document to PDF	✅	❌	❌
Video smart cover	✅	❌	❌

Security considerations

Credential handling policy

setup.sh follows these principles when handling credentials:

Does not modify the user's shell configuration files: credentials are not written to ~/.zshrc、~/.bashrc or other shell RC files
Environment variables are valid only for the current session: environment variables become invalid after closing the terminal and need to be exported again
Configuration file permissions 600: all written configuration files are readable and writable only by the current user
Does not perform global installation: npm packages are installed locally in the project node_modules/, without using npm install -g
Does not automatically install system packages: does not execute pip install or other system-level package installations

Credential persistent storage and exposure risks

⚠️ Important security notice: setup.sh will persistently write SecretId/SecretKey to a disk file. Although the file permissions are set to 600 (readable and writable only by the current user), persistent storage still increases the risk of credential exposure (such as disk theft, backup leaks, malware reading, etc.). Users should fully understand this risk.

After setup.sh runs, the credentials will be stored in the following files:

File	Write scenario	Stored content	Permissions	Risk
`~/.mcporter/mcporter.json`	Always written	The env field of the cos-mcp server configuration contains SecretId/SecretKey	600	Credentials are stored in plaintext in the user's home directory
`~/.cos.conf`	Only when coscmd is pre-installed	The coscmd configuration contains SecretId/SecretKey	600	Credentials are stored in plaintext in the user's home directory

Measures to reduce risk：

Use a least-privilege sub-account key(see the detailed guidance below), do not use the root account key
Clean up credentials promptly when no longer in use：rm -f ~/.mcporter/mcporter.json ~/.cos.conf
Rotate keys regularly: In Tencent Cloud Console > Access Management > API Key Management regularly change the key
If conditions permit, prefer using **temporary credentials (STS Token)** instead of permanent keys

Installation package supply chain risk

This skill installs the following registry packages via npm (standard npm installation, no arbitrary URL downloads):

cos-mcp — Tencent Cloud COS MCP server
cos-nodejs-sdk-v5 — Tencent Cloud COS Node.js SDK
mcporter — MCP command-line tool

These packages come from the npm public registry and, like all npm packages, carry supply chain risks. It is recommended to verify the package publisher and version via npm info <package> before installation.

Least privilege and sub-account keys (strongly recommended)

⚠️ Never use the root account key. The root account key has full control over all resources under the account, and the consequences of a leak are severe.

It is recommended to create a dedicated sub-account and grant a least-privilege policy limited to COS operations only:

Go to Tencent Cloud Console > Access Management > User List, create a sub-user
Grant only one of the following preset policies:
- QcloudCOSDataReadOnlyAccess — Read-only (if you only need to download/list)
- QcloudCOSDataFullControl — COS data read/write (recommended, if you need upload + download)
- If you need Data Processing (CI) features, additionally add QcloudCIFullAccess

You can further usecustom policiesto restrict to a specific bucket:

{
  "statement": [{
    "effect": "allow",
    "action": ["cos:*"],
    "resource": ["qcs::cos:<Region>::uid/<APPID>:<BucketName>/*"]
  }]
}

Create an API key for this sub-account and use that key to configure this skill

Temporary credentials (STS Token)

For scenarios with higher security requirements, it is recommended to use Tencent Cloud STS temporary credentials：

Temporary credentials have an expiration time (default 1800 seconds) and automatically become invalid after expiration
Suitable for automated pipelines or short-term task scenarios
cos-mcp supports passing an STS Token via environment variables (set the TENCENT_COS_TOKEN environment variable)

Other security recommendations

Credentials are sensitive information: A leaked SecretId / SecretKey can lead to bucket data being stolen or tampered with
Recommended to use --from-env modeSet credentials to avoid credentials appearing in shell history
Credentials are not displayed in plaintext: Never echo the user's SecretId/SecretKey in the conversation; guide the user to set them themselves via setup.sh or by editing the configuration file
mcporter configuration uses the env method: Credentials are passed to the child process via environment variables and are not exposed in the ps aux process list
Rotate keys regularly: It is recommended to change the API key every 90 days, in the Console > API Key Management operation
Credential cleanup: When no longer in use, run rm -f ~/.mcporter/mcporter.json ~/.cos.conf to clear persistent credentials

Usage guidelines

On first use, first run {baseDir}/scripts/setup.sh --check-only to check the environment
mcporter calls must include --config ~/.mcporter/mcporter.json and --output json(use npx mcporter to call)
All file paths（objectKey/cospath/--key) are relative paths within the bucket, such as images/photo.jpg
Image processing/intelligent search/document conversion are only available with method one, and if unavailable, clearly inform the user
Asynchronous tasks(document conversion, video cover) need to be polled for results via jobId Polling result
Actively obtain the link after upload: After the upload is complete, call getObjectUrl or sign-url to return the access link
Error handling: When a call fails, first use setup.sh --check-only to diagnose environment issues
Method two script source codeSee scripts/cos_node.mjs
Detailed parameters of MCP toolsSee references/api_reference.md
MCP configuration templateSee references/config_template.json

About this skill

First Use — Automatic Setup

Step 1: Check Current Status

Step 2: If Not Configured, Guide the User to Provide Credentials

Step 3: After the User Provides Credentials, Run Automatic Setup

System Change Summary

Execution Strategy

Method 1: cos-mcp MCP tools (preferred)

Call Format

Tools Overview

Common Operations

Storage

Image processing

Smart search (requires a pre-built dataset)

Document and media processing (asynchronous tasks)

Method 2: Node.js SDK script

Common commands

Limitations

Method 3: COSCMD command line

Common commands

Limitations

Feature comparison table

Security considerations

Credential handling policy

Credential persistent storage and exposure risks

Installation package supply chain risk

Least privilege and sub-account keys (strongly recommended)

Temporary credentials (STS Token)

Other security recommendations

Usage guidelines