cos-mcp
Version:
基于MCP协议的腾讯云COS MCP Server，无需编码即可让大模型快速接入腾讯云存储(COS)和数据万象(CI)能力
304 lines (229 loc) • 9.62 kB
Markdown
中文 | [English](README.en.md)
# 腾讯云 COS MCP Server 🚀🚀🚀
 [](https://www.npmjs.com/package/cos-mcp) [](License.txt)
<p align="center">
<img alt="logo" src="https://raw.githubusercontent.com/Tencent/cos-mcp/master/src/img/logo.png"/>
</p>
基于 MCP 协议的腾讯云 COS MCP Server，无需编码即可让大模型快速接入腾讯云存储 (COS) 和数据万象 (CI) 能力。
---
## ✨ 核心功能
### 云端存储能力
- ⬆️ 文件上传到云端
- ⬇️ 文件从云端下载
- 📋 获取云端文件列表
### 云端处理能力
- 🖼️ 获取图片信息
- 🔍 图片超分辨率
- ✂️ 图片裁剪
- 📲 二维码识别
- 🏆 图片质量评估
- 🅰️ 文字水印
- 🎬 元数据/自然语言检索 (MateInsight)
- 📄 文档转 PDF
- 🎥 视频封面
---
## 💡 典型应用场景
- 使用其他 MCP 能力获取的文本/图片/视频/音频等数据，可直接上传到 COS 云端存储。
- 本地数据快速通过大模型转存到 COS 云端存储/备份。
- 通过大模型实现自动化：将网页里的视频/图片/音频/文本等数据批量转存到 COS 云端存储。
- 自动化将视频/图片/音频/文本等数据在云端处理，并转存到 COS 云端存储。
---
## 🌟 功能示例
1. 上传文件到 COS
2. 图片质量评估
3. 自然语言检索图片
4. 视频截帧
---
# 🔧 安装使用
## 参数说明
为了保护您的数据私密性，请准备以下参数：
### 1. **SecretId / SecretKey**
- **说明**: 腾讯云 COS 的密钥，用于身份认证，请妥善保管，切勿泄露。
- **获取方式**:
1. 访问 [腾讯云密钥管理](https://console.cloud.tencent.com/cam/capi)。
2. 新建密钥并复制生成的 **SecretId** 和 **SecretKey**。
### 2. **Bucket**
- **示例**: `mybucket-123456`
- **说明**: 存储桶名称，用于存放数据，相当于您的个人存储空间。
- **获取方式**:
1. 访问 [存储桶列表](https://console.cloud.tencent.com/cos/bucket)。
2. 复制存储桶名称。如果没有存储桶，可点击“创建存储桶”，一般选择默认配置即可快速完成创建。
### 3. **Region**
- **示例**: `ap-beijing`
- **说明**: 存储桶所在的地域。
- **获取方式**:
1. 在 [存储桶列表](https://console.cloud.tencent.com/cos/bucket) 中找到存储桶。
2. 在存储桶名称一行查看所属地域并复制，例如：`ap-beijing`。
### 4. **DatasetName**
- **说明**: 非必填参数，数据智能检索操作需要此参数。
- **获取方式**:
1. 访问 [数据集管理](https://console.cloud.tencent.com/cos/metaInsight/dataManage)。
2. 创建数据集并等待索引建立完成后，复制数据集名称。
### 5. **connectType**
- **说明**: 非必填参数，指定连接方式，可选值为 `stdio`（本地）或 `sse`（远程）。
- **默认值**: `stdio`
### 6. **port**
- **说明**: 非必填参数，当连接方式为 `sse` 时，可自由设置端口。
- **默认值**: `3001`
---
## 从 npx 启动
在大模型内使用时（例如: cursor），需要在 `mcp.json` 中配置：
```json
{
"mcpServers": {
"cos-mcp": {
"command": "npx",
"args": [
"cos-mcp",
"--Region=yourRegion",
"--Bucket=yourBucket",
"--SecretId=yourSecretId",
"--SecretKey=yourSecretKey",
"--DatasetName=yourDatasetname"
]
}
}
}
```
也可以通过 JSON 配置：
```json
{
"mcpServers": {
"cos-mcp": {
"command": "npx",
"args": [
"cos-mcp",
"--cos-config='{\"Region\":\"yourRegion\",\"Bucket\":\"yourBucket\",\"SecretId\":\"yourSecretId\",\"SecretKey\":\"yourSecretKey\",\"DatasetName\":\"yourDatasetname\"}'"
]
}
}
}
```
---
## 使用 npm 安装
```bash
# 安装
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` 中配置：
```json
{
"mcpServers": {
"cos-mcp": {
"url": "http://localhost:3001/sse"
}
}
}
```
---
## 使用源码安装
### 步骤 1: 克隆项目代码
```bash
git clone https://github.com/Tencent/cos-mcp.git
cd cos-mcp
```
### 步骤 2: 安装依赖
```bash
npm install
```
### 步骤 3: 启动服务
#### 3.1 配置本地环境变量
创建 `.env` 文件，并配置以下环境变量：
```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 模式启动（方式一）
```bash
npm run start:sse
```
#### 3.3 本地构建后使用 STDIO 模式（方式二）
```bash
npm run build
```
构建产物位于 `dist/index.js`。
---
### 步骤 4: 在大模型内使用
#### SSE 模式配置
```json
{
"mcpServers": {
"cos-mcp": {
"url": "http://localhost:3001/sse"
}
}
}
```
#### STDIO 模式配置
```json
{
"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 密钥，拥有操作您云资源的权限，请务必妥善保管。
- 建议使用 [子账号密钥](https://cloud.tencent.com/document/product/598/13674) 并遵循 **最小权限原则**，仅授予必要的 COS 操作权限。
- 禁止将密钥硬编码在代码中或提交到公开仓库。
- 推荐通过环境变量（`.env` 文件）管理密钥，并将 `.env` 加入 `.gitignore`。
---
## ⚠️ 注意事项
1. 如果安装了旧版本的包，可以将上述内容内 `cos-mcp` 改为 `cos-mcp@latest` 安装最新版包。
2. 如果全局安装后直接使用 `cos-mcp` 不行，可能是全局变量有问题，可以使用拆分变量或 `npx` 的方式启动：
```bash
npm install -g cos-mcp@latest
cos-mcp --cos-config=xxx --port=3001 --connectType=sse
```
上述命令效果等同于：
```bash
npx cos-mcp@latest --cos-config=xxx --port=3001 --connectType=sse
```
3. 如果出现解析问题，可能是终端对双引号敏感，可以将配置参数改为以下格式再尝试：
```bash
--cos-config='{\"Region\":\"yourRegion\",\"Bucket\":\"BucketName-APPID\",\"SecretId\":\"yourSecretId\",\"SecretKey\":\"yourSecretKey\",\"DatasetName\":\"datasetName\"}' --port=3001 --connectType=sse
```