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 requests COS operations for the first time, 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 Policy".

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 Secret ID

SecretKey — Tencent Cloud API Secret Key

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 get the keys at Tencent Cloud Console > Access Management > API Key Management , and view bucket information at COS Console .

⚠️ Security requirements：Must use sub-account keys, granting only COS-related permissions (e.g., QcloudCOSDataFullControl），Strictly prohibited to use root account keys. See the "Least Privilege and Sub-account Keys" section below.

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 global)
Check and locally install mcporter into the project node_modules（npm install, not global; 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 env field, permissions 600)
If coscmd is already installed, configure ~/.cos.conf(permissions 600);will notautomatically install coscmd
Verify COS connection

System Change Summary

Users should understand all changes that setup.sh will make before installing:

Change Type	Details	Persistence
npm local install	`cos-mcp`、`cos-nodejs-sdk-v5`、`mcporter` install into project `node_modules/`	Persistent (project directory only)
Project files	If no `package.json` , then create	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_*` exported to the current session	Temporary (invalidated when the terminal is closed)

⚠️ 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(⚠️ Persistent credential storage 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 export statements to your shell configuration yourself. It is strongly recommended to use a sub-account key with minimum permissions; see the "Minimum Permissions and Sub-account Keys" section for details.

Once setup is complete, you can start using it.

Execution policy

The three methods fall back in order of priority to ensure operations can always be completed:

Method 1: cos-mcp MCP tools(preferred) — most complete functionality, supporting 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 the 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。

Invocation format

Invoke 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 calling the MCP tools directly from the client (getCosConfig , etc.).

Tool 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, image search by text (requires a pre-built dataset)
Document and media	Document to PDF, intelligent video cover (asynchronous tasks)

Common operations

The following examples show 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"

Intelligent 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 node {baseDir}/scripts/cos_node.mjs prefix is omitted below. 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;success: true indicates success, with exit code 0.

Limitations

Only storage operations are supported;not supportedfor image processing, intelligent search, and 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 ineffective
Protocol — if it is 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;not supportedfor image processing, intelligent search, and 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)	✅	❌	❌
Intelligent 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 the terminal is closed and must 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 persistence storage and exposure risks

⚠️ Important security notice: setup.sh will persistently write SecretId/SecretKey to disk files. 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 (e.g., disk theft, backup leaks, malware reading, etc.). Users should fully understand this risk.

After setup.sh runs, credentials are 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	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 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 , change keys regularly
If conditions permit, prefer **temporary credentials (STS Token)** over permanent keys

Installer 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 risk. 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 a leak would have serious consequences.

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

Go to Tencent Cloud Console > Access Management > User List, and 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 to upload + download)
- If you need Cloud Infinite (CI) features, additionally add QcloudCIFullAccess

You can further restrict to a specific bucket viaa custom policy:

{
  "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 SecretId / SecretKey leak can lead to bucket data being stolen or tampered with
Recommended to use --from-env modeSet up credentials to avoid credentials appearing in shell history
Credentials are not displayed in plain text: 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
The mcporter configuration uses the env approach: Credentials are passed to child processes 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 section
Credential cleanup: When no longer in use, run rm -f ~/.mcporter/mcporter.json ~/.cos.conf to clear persisted credentials

Usage Guidelines

On first use, run {baseDir}/scripts/setup.sh --check-only first 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; when unavailable, clearly inform the user
Asynchronous tasks(document conversion, video cover) require polling for results via jobId Polling result
Actively obtain the link after uploading: 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
For detailed MCP tool parameterssee 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 policy

Method 1: cos-mcp MCP tools (preferred)

Invocation format

Tool overview

Common operations

Storage

Image processing

Intelligent 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 persistence storage and exposure risks

Installer Supply Chain Risk

Least Privilege and Sub-account Keys (Strongly Recommended)

Temporary Credentials (STS Token)

Other Security Recommendations

Usage Guidelines