cos-mcp

v1.0.15

Published

a month ago

基于MCP协议的腾讯云COS MCP Server，无需编码即可让大模型快速接入腾讯云存储(COS)和数据万象(CI)能力

0High
0Medium
0Low

shawnmzhang

mcp cos ci upload storage ai

中文 | English

腾讯云 COS MCP Server 🚀🚀🚀

基于 MCP 协议的腾讯云 COS MCP Server，无需编码即可让大模型快速接入腾讯云存储 (COS) 和数据万象 (CI) 能力。

✨ 核心功能

云端存储能力

⬆️ 文件上传到云端
⬇️ 文件从云端下载
📋 获取云端文件列表

云端处理能力

🖼️ 获取图片信息
🔍 图片超分辨率
✂️ 图片裁剪
📲 二维码识别
🏆 图片质量评估
🅰️ 文字水印
🎬 元数据/自然语言检索 (MateInsight)
📄 文档转 PDF
🎥 视频封面

💡 典型应用场景

使用其他 MCP 能力获取的文本/图片/视频/音频等数据，可直接上传到 COS 云端存储。
本地数据快速通过大模型转存到 COS 云端存储/备份。
通过大模型实现自动化：将网页里的视频/图片/音频/文本等数据批量转存到 COS 云端存储。
自动化将视频/图片/音频/文本等数据在云端处理，并转存到 COS 云端存储。

🌟 功能示例

上传文件到 COS
图片质量评估
自然语言检索图片
视频截帧

🔧 安装使用

参数说明

为了保护您的数据私密性，请准备以下参数：

1. SecretId / SecretKey

说明: 腾讯云 COS 的密钥，用于身份认证，请妥善保管，切勿泄露。
获取方式:
1. 访问腾讯云密钥管理。
2. 新建密钥并复制生成的 SecretId 和 SecretKey。

2. Bucket

示例: mybucket-123456
说明: 存储桶名称，用于存放数据，相当于您的个人存储空间。
获取方式:
1. 访问存储桶列表。
2. 复制存储桶名称。如果没有存储桶，可点击“创建存储桶”，一般选择默认配置即可快速完成创建。

3. Region

示例: ap-beijing
说明: 存储桶所在的地域。
获取方式:
1. 在存储桶列表中找到存储桶。
2. 在存储桶名称一行查看所属地域并复制，例如：ap-beijing。

4. DatasetName

说明: 非必填参数，数据智能检索操作需要此参数。
获取方式:
1. 访问数据集管理。
2. 创建数据集并等待索引建立完成后，复制数据集名称。

5. connectType

说明: 非必填参数，指定连接方式，可选值为 stdio（本地）或 sse（远程）。
默认值: stdio

6. port

说明: 非必填参数，当连接方式为 sse 时，可自由设置端口。
默认值: 3001

从 npx 启动

在大模型内使用时（例如: cursor），需要在 mcp.json 中配置：

{
  "mcpServers": {
    "cos-mcp": {
      "command": "npx",
      "args": [
        "cos-mcp",
        "--Region=yourRegion",
        "--Bucket=yourBucket",
        "--SecretId=yourSecretId",
        "--SecretKey=yourSecretKey",
        "--DatasetName=yourDatasetname"
      ]
    }
  }
}

也可以通过 JSON 配置：

{
  "mcpServers": {
    "cos-mcp": {
      "command": "npx",
      "args": [
        "cos-mcp",
        "--cos-config='{\"Region\":\"yourRegion\",\"Bucket\":\"yourBucket\",\"SecretId\":\"yourSecretId\",\"SecretKey\":\"yourSecretKey\",\"DatasetName\":\"yourDatasetname\"}'"
      ]
    }
  }
}

使用 npm 安装

# 安装
npm install -g cos-mcp@latest

# 运行开启 SSE 模式
cos-mcp --Region=yourRegion --Bucket=yourBucket --SecretId=yourSecretId --SecretKey=yourSecretKey --DatasetName=yourDatasetname --port=3001 --connectType=sse

# 或通过 JSON 配置
cos-mcp --cos-config='{"Region":"yourRegion","Bucket":"BucketName-APPID","SecretId":"yourSecretId","SecretKey":"yourSecretKey","DatasetName":"datasetName"}' --port=3001 --connectType=sse

在大模型内使用 SSE 模式时（例如: cursor），需要在 mcp.json 中配置：

{
  "mcpServers": {
    "cos-mcp": {
      "url": "http://localhost:3001/sse"
    }
  }
}

使用源码安装

步骤 1: 克隆项目代码

git clone https://github.com/Tencent/cos-mcp.git
cd cos-mcp

步骤 2: 安装依赖

npm install

步骤 3: 启动服务

3.1 配置本地环境变量

创建 .env 文件，并配置以下环境变量：

Region='yourRegion'
Bucket='yourBucket'
SecretId='yourSecretId'
SecretKey='yourSecretKey'
DatasetName="yourDatasetName"

# 可选的高级配置参数
Domain='yourBucket.cos.yourRegion.tencentcos.cn'  # COS域名，默认会自动生成
ServiceDomain='service.cos.tencentcos.cn'         # COS服务域名，默认值
Protocol='https:'                                 # 协议类型，可选 'http:' 或 'https:'

高级配置参数说明：

Domain: 自定义COS访问域名
ServiceDomain: COS服务域名
Protocol: 访问协议，可选 http: 或 https:，注意冒号是必须的

3.2 本地 SSE 模式启动（方式一）

npm run start:sse

3.3 本地构建后使用 STDIO 模式（方式二）

npm run build

构建产物位于 dist/index.js。

步骤 4: 在大模型内使用

SSE 模式配置

{
  "mcpServers": {
    "cos-mcp": {
      "url": "http://localhost:3001/sse"
    }
  }
}

STDIO 模式配置

{
  "mcpServers": {
    "cos-mcp": {
      "command": "node",
      "args": [
        "${your work space}/dist/index.js"
      ]
    }
  }
}

完成以上步骤后，即可通过源码运行 COS MCP Server。

🔒 安全性说明

连接模式安全建议

STDIO 模式

STDIO 模式为本地进程通信，仅限本机调用，安全性较高，适合个人开发使用。

SSE 模式

SSE 模式（/sse）通过 HTTP 提供服务，适合内网部署，开放给团队内部使用。
⚠️ 切勿将 /sse 端口直接暴露到公网，否则任何人都可以通过该接口操作您的 COS 存储桶，造成数据泄露或资源滥用。
如需在生产环境或公网使用，开发者必须在上层封装自己的业务鉴权逻辑，例如：
- 在反向代理（Nginx / API Gateway）层添加鉴权中间件
- 使用 Token、OAuth、API Key 等机制校验请求合法性
- 配置 IP 白名单或 VPN 等网络层访问控制

工具调用管控

SSE 模式下，MCP Server 会将所有已注册的工具（Tool）暴露给连接的客户端。在团队共享场景下，建议开发者根据实际业务需求在上层进行 工具调用的管控与限制：

工具白名单：在业务网关层按用户角色/权限只放行允许调用的工具，避免低权限用户执行高危操作（如删除文件、批量操作等）。
操作审计与日志：记录每次工具调用的请求者、调用参数和执行结果，便于事后追溯和安全审计。
调用频率限制：在网关或中间件层对工具调用设置速率限制（Rate Limiting），防止资源被恶意或意外滥用。
敏感操作二次确认：对文件删除、覆盖写入等高风险操作，建议在业务层增加二次确认或审批流程。
输入参数校验：在网关层对用户传入的参数（如文件路径、Bucket 名称等）进行合法性校验，防止路径穿越或越权访问。

密钥安全

SecretId / SecretKey 是腾讯云 API 密钥，拥有操作您云资源的权限，请务必妥善保管。
建议使用子账号密钥并遵循 最小权限原则，仅授予必要的 COS 操作权限。
禁止将密钥硬编码在代码中或提交到公开仓库。
推荐通过环境变量（.env 文件）管理密钥，并将 .env 加入 .gitignore。

⚠️ 注意事项

如果安装了旧版本的包，可以将上述内容内 cos-mcp 改为 cos-mcp@latest 安装最新版包。
如果全局安装后直接使用 cos-mcp 不行，可能是全局变量有问题，可以使用拆分变量或 npx 的方式启动：
```
npm install -g cos-mcp@latest
cos-mcp --cos-config=xxx --port=3001 --connectType=sse
```
上述命令效果等同于：
```
npx cos-mcp@latest --cos-config=xxx --port=3001 --connectType=sse
```

如果出现解析问题，可能是终端对双引号敏感，可以将配置参数改为以下格式再尝试：

--cos-config='{\"Region\":\"yourRegion\",\"Bucket\":\"BucketName-APPID\",\"SecretId\":\"yourSecretId\",\"SecretKey\":\"yourSecretKey\",\"DatasetName\":\"datasetName\"}' --port=3001 --connectType=sse