Tencent Cloud COS MCP Server

腾讯云 COS MCP 服务器

一个基于 Node.js 的 Model Context Protocol (MCP)服务器，为 Claude Desktop、Cursor 和 Windsurf 等 IDE 提供腾讯云对象存储(COS)功能。

功能特性

🚀 文件上传 - 支持单文件和批量文件上传到腾讯云 COS
📦 大文件上传 - 自动分片上传，支持断点续传和进度监控
🔄 并发控制 - 智能重试机制和可配置并发限制
🧹 资源清理 - 自动清理临时文件，防止磁盘空间泄漏
📁 文件管理 - 复制、移动、重命名文件操作
🗂️ 文件夹操作 - 创建、删除文件夹，支持递归操作
🔗 临时 URL - 生成带签名的临时访问链接，支持自定义过期时间
📋 对象管理 - 列出存储桶中的对象，支持前缀过滤和文件夹视图
🗑️ 批量删除 - 支持单个和批量删除 COS 中的对象
📊 统计分析 - 文件夹统计信息，包括大小、数量、类型分布
🔧 MCP 兼容 - 完全兼容 Model Context Protocol 规范

快速开始

📖 快速上手: 查看快速参考指南了解所有工具的基本用法

📚 详细文档: 查看工具使用说明获取完整的API文档和示例

本地调试

# 克隆项目
git clone https://github.com/156554395/tx-cos-mcp.git
cd tx-cos-mcp

# 安装依赖
pnpm install

# 配置环境变量
export COS_SECRET_ID=your-secret-id
export COS_SECRET_KEY=your-secret-key
export COS_REGION=your-region
export COS_BUCKET=your-bucket
export COS_DOMAIN=your-custom-domain.com

# 启动调试服务器
pnpm inspector

环境配置

服务器通过环境变量读取腾讯云 COS 配置：

作为 MCP 服务器使用（推荐）

在 MCP 兼容编辑器中配置：

{
  "command": "npx",
  "args": ["-y", "tx-cos-mcp@latest"],
  "env": {
    "COS_SECRET_ID": "your-secret-id",
    "COS_SECRET_KEY": "your-secret-key",
    "COS_REGION": "your-region",
    "COS_BUCKET": "your-bucket",
    "COS_DOMAIN": "your-custom-domain.com"
  },
  "transportType": "stdio"
}

环境变量说明

变量名	必需	说明	示例
`COS_SECRET_ID`	✅	腾讯云 Secret ID	`AKIDxxx...`
`COS_SECRET_KEY`	✅	腾讯云 Secret Key	`xxx...`
`COS_REGION`	✅	COS 地域	`ap-beijing`, `ap-shanghai`
`COS_BUCKET`	✅	存储桶名称	`my-bucket-1234567890`
`COS_DOMAIN`	❌	自定义域名	`cdn.example.com`

MCP 工具列表

1. upload_file - 单文件上传

{
  "file_path": "/path/to/local/file.jpg",    // 必需：本地文件路径
  "object_key": "images/file.jpg",           // 可选：COS中的对象键
  "custom_domain": "cdn.example.com"        // 可选：自定义域名
}

2. upload_multiple - 批量文件上传

{
  "files": [
    {
      "file_path": "/path/to/file1.jpg",
      "object_key": "images/file1.jpg"       // 可选
    },
    {
      "file_path": "/path/to/file2.png"      // 使用文件名作为对象键
    }
  ]
}

3. get_signed_url - 获取临时访问 URL

{
  "object_key": "images/file.jpg",          // 必需：COS对象键
  "expire_time": 3600                       // 可选：过期时间(秒)，默认1小时
}

4. list_objects - 列出存储桶对象

{
  "prefix": "images/"                       // 可选：对象键前缀过滤
}

5. delete_object - 删除对象

{
  "object_key": "images/file.jpg"           // 必需：要删除的对象键
}

6. copy_object - 复制对象

{
  "source_key": "images/file.jpg",          // 必需：源对象键
  "target_key": "backup/file.jpg",          // 必需：目标对象键
  "target_bucket": "other-bucket"           // 可选：目标存储桶
}

7. move_object - 移动对象

{
  "source_key": "temp/file.jpg",            // 必需：源对象键
  "target_key": "images/file.jpg",          // 必需：目标对象键
  "target_bucket": "other-bucket"           // 可选：目标存储桶
}

8. rename_object - 重命名对象

{
  "old_key": "images/old_name.jpg",         // 必需：原对象键
  "new_key": "images/new_name.jpg"          // 必需：新对象键
}

9. delete_multiple - 批量删除对象

{
  "object_keys": [                          // 必需：对象键数组
    "images/file1.jpg",
    "images/file2.jpg",
    "temp/file3.png"
  ]
}

10. create_folder - 创建文件夹

{
  "folder_path": "images/thumbnails"        // 必需：文件夹路径
}

11. delete_folder - 删除文件夹

{
  "folder_path": "temp/",                   // 必需：文件夹路径
  "recursive": true                         // 可选：是否递归删除，默认false
}

12. list_folders - 列出文件夹和文件

{
  "prefix": "images/"                       // 可选：路径前缀，默认根目录
}

13. get_folder_stats - 获取文件夹统计

{
  "folder_path": "images/"                  // 可选：文件夹路径，为空则统计整个存储桶
}

14. upload_large_file - 大文件分片上传

{
  "file_path": "/path/to/large/video.mp4",    // 必需：本地大文件路径
  "object_key": "videos/video.mp4",           // 可选：COS中的对象键
  "custom_domain": "cdn.example.com",        // 可选：自定义域名
  "chunk_size": 2097152,                     // 可选：分片大小(字节)，默认1MB
  "concurrency": 5,                          // 可选：并发上传数，默认3，最大10
  "force_slice": true                        // 可选：强制使用分片上传
}

15. get_upload_progress - 获取上传进度

{
  "session_id": "abc123def456"               // 可选：特定会话ID，不提供则返回所有
}

16. clear_upload_progress - 清理上传进度

{
  "session_id": "abc123def456"               // 必需：要清理的会话ID
}

17. manage_temp_files - 管理临时文件

{
  "action": "cleanup",                       // 必需：'stats'(统计) 或 'cleanup'(清理)
  "type": "progress",                        // 可选：'progress'/'cache'/'uploads'/'all'
  "older_than_days": 7                       // 可选：清理多少天前的文件，默认7天
}

IDE 集成配置

使用本地运行集成

{
  "mcpServers": {
    "tx-cos-mcp": {
      "command": "node",
      "args": ["your-absolute-path/tx-cos-mcp/index.js"],
      "env": {
        "COS_SECRET_ID": "your-secret-id",
        "COS_SECRET_KEY": "your-secret-key",
        "COS_REGION": "your-region",
        "COS_BUCKET": "your-bucket",
        "COS_DOMAIN": "your-custom-domain.com"
      }
    }
  }
}

已发布到 npm 集成

{
  "mcpServers": {
    "tx-cos-mcp": {
      "command": "npx",
      "args": ["y", "tx-cos-mcp@latest"],
      "env": {
        "COS_SECRET_ID": "your-secret-id",
        "COS_SECRET_KEY": "your-secret-key",
        "COS_REGION": "your-region",
        "COS_BUCKET": "your-bucket",
        "COS_DOMAIN": "your-custom-domain.com"
      },
      "transportType": "stdio"
    }
  }
}

Claude code 中集成

在配置中添加 MCP 服务器配置，使用相同的 JSON 格式。

Cursor IDE

在设置中添加 MCP 服务器配置，使用相同的 JSON 格式。

Windsurf IDE

参考官方文档配置 MCP 服务器，使用上述配置参数。

常用命令

# 查看版本
npx tx-cos-mcp --version

# 测试配置
COS_SECRET_ID=xxx COS_SECRET_KEY=xxx COS_REGION=your-region COS_BUCKET=test npx tx-cos-mcp

# 开发模式
npm run dev

# 运行测试
npm run test              # 基础功能测试
npm run test:mcp          # MCP协议合规性测试
npm run test:temp         # 临时目录管理测试
npm run test:cleanup      # 临时文件清理测试
npm run test:path         # 文件路径验证测试

# 发布到npm (维护者)
npm run publish:npm

测试

项目包含完整的测试套件，确保功能的可靠性：

测试文件

test/test.js - 基础功能测试
test/test-mcp.js - MCP协议合规性测试
test/test-temp.js - 临时目录管理测试
test/test-cleanup.js - 临时文件清理测试
test/test-path-validation.js - 文件路径验证测试

运行测试

# 运行所有测试
npm test

# 单独测试
npm run test:mcp          # 测试MCP协议功能
npm run test:temp         # 测试临时目录管理
npm run test:cleanup      # 测试临时文件清理
npm run test:path         # 测试文件路径验证

测试覆盖

✅ COS服务基础功能验证
✅ MCP协议标准输出合规性
✅ 临时目录结构和管理
✅ 上传完成后资源清理
✅ 断点续传进度管理
✅ 异常情况资源回收
✅ 文件路径清理和中文支持

开发指南

项目结构

tx-cos-mcp/
├── index.js              # MCP服务器主入口
├── src/
│   ├── cosService.js     # COS SDK封装服务
│   ├── config.js         # 配置管理
│   ├── uploadProgress.js # 上传进度管理
│   └── tempManager.js    # 临时文件管理
├── test/                 # 测试文件目录
│   ├── test.js           # 基础功能测试
│   ├── test-mcp.js       # MCP协议合规性测试
│   ├── test-temp.js      # 临时目录管理测试
│   └── test-cleanup.js   # 临时文件清理测试
├── config-examples/      # 配置示例
├── package.json          # 项目配置
└── README.md            # 项目文档

核心依赖

@modelcontextprotocol/sdk - MCP 协议实现
cos-nodejs-sdk-v5 - 腾讯云 COS 官方 SDK

贡献指南

Fork 项目
创建功能分支 (git checkout -b feature/new-feature)
提交更改 (git commit -am 'Add new feature')
推送分支 (git push origin feature/new-feature)
创建 Pull Request

许可证

MIT License - 查看LICENSE文件了解详情。

支持与反馈

🐛 问题反馈: GitHub Issues
💡 功能建议: GitHub Discussions
📧 联系作者: 156554395@qq.com

Deploy Server

HTTP connection URL

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Enables interaction with Tencent Cloud Object Storage (COS) through MCP protocol. Supports file upload, download, deletion, listing objects, and generating temporary signed URLs for cloud storage management.