# 火山引擎 对象存储 TOS 非官方 MCP工具

* TOS 非官方 MCP 工具

## 快速开始

### macOS 从零开始配置

#### 1. 安装必要依赖

```bash
# 安装 Homebrew（如果还没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Python 3（如果还没有）
brew install python@3.12

# 安装 uv（Python 包管理器）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 重新加载 shell 配置
source ~/.zshrc  # 如果使用 zsh
# 或
source ~/.bash_profile  # 如果使用 bash
```

#### 2. 方式一：直接从 GitHub 使用（推荐，无需克隆）

使用 uvx 可以直接从 GitHub 运行，无需克隆仓库：

```bash
# 直接运行（会自动从 GitHub 下载和安装）
uvx --from git+https://github.com/jneless/tos-mcp.git tos-mcp-server
```

#### 3. 方式二：克隆到本地使用

如果需要修改代码或本地开发：

```bash
# 克隆项目
git clone https://github.com/jneless/tos-mcp.git
cd tos-mcp

# 自动安装依赖
uv sync

# 运行服务器
uv run tos-mcp-server
```

### 环境变量配置

复制环境变量模板：
```bash
cp .env.example .env
```

编辑 `.env` 文件并填入配置，或者设置环境变量：
```bash
export TOS_ACCESS_KEY="your_access_key"
export TOS_SECRET_KEY="your_secret_key"
export TOS_REGION="cn-beijing"
export TOS_ENDPOINT="https://tos-cn-beijing.volces.com"
```


## MCP 配置

### 方式一：直接从 GitHub 安装（推荐，无需克隆仓库）

 Cline 或其他 MCP 客户端的配置文件中添加：

```json
{
  "mcpServers": {
    "tos-mcp-server": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/jneless/tos-mcp.git", "tos-mcp-server"],
      "env": {
        "TOS_ACCESS_KEY": "your-access-key",
        "TOS_SECRET_KEY": "your-secret-key",
        "TOS_REGION": "cn-beijing",
        "TOS_ENDPOINT": "https://tos-cn-beijing.volces.com"
      }
    }
  }
}
```


### 环境变量配置说明

- `TOS_ACCESS_KEY`: 火山引擎访问密钥 ID
- `TOS_SECRET_KEY`: 火山引擎访问密钥 Secret
- `TOS_REGION`: TOS 服务区域（如 cn-beijing）
- `TOS_ENDPOINT`: TOS 服务端点（可选，如果不设置会根据 region 自动生成）

## API 测试状态

| API 名称 | 功能描述 | 分类 | 测试状态 | 测试环境 | 备注 |
|---------|---------|------|---------|---------|------|
| `tos_create_bucket` | 创建存储桶 | 桶管理 | ✅ 已测试 | Cline | - |
| `tos_list_buckets` | 列举存储桶 | 桶管理 | ✅ 已测试 | Cline | - |
| `tos_get_bucket_meta` | 获取存储桶元数据 | 桶管理 | ✅ 已测试 | Cline | - |
| `tos_delete_bucket` | 删除存储桶 | 桶管理 | ✅ 已测试 | Cline | - |
| `tos_put_object` | 上传对象 | 对象管理 | ✅ 已测试 | Cline | - |
| `tos_get_object` | 下载对象 | 对象管理 | ✅ 已测试 | Cline | - |
| `tos_list_objects` | 列举对象 | 对象管理 | ✅ 已测试 | Cline | - |
| `tos_delete_object` | 删除对象 | 对象管理 | ✅ 已测试 | Cline | - |
| `tos_presigned_url` | 生成预签名URL | 预签名 | ✅ 已测试 | Cline | - |
| `tos_image_process` | 基础图片处理 | 图片处理 | ✅ 已测试 | Cline | 回写，并提供 URL 下载 |
| `tos_image_info` | 获取图片信息 | 图片处理 | ✅ 已测试 | Cline | - |
| `tos_video_snapshot` | 视频截帧 | 视频处理 | ✅ 已测试 | Cline | - |
| `tos_video_info` | 获取视频信息 | 视频处理 | ✅ 已测试 | Cline  | 回写，并提供 URL 下载 |


## 测试图片

### Cline 配置测试
![](doc/test-record/1.png)

### 创建bucket
![](doc/test-record/2.png)

### list bucket
![](doc/test-record/3.png)

### 删除 bucket
![](doc/test-record/4.png)

### 获取 bucket 元数据
![](doc/test-record/5.png)

### 生成预签名 url
![](doc/test-record/6.png)

### 下载TOS文件 到本地
![](doc/test-record/7.png)

### 上传本地文件 到TOS
![](doc/test-record/8.png)

### 列举桶内对象
![](doc/test-record/9.png)

### 删除文件
![](doc/test-record/10.png)

### 获取图片元信息
![](doc/test-record/11.png)

### 图像处理，并回写，生成 presign url
![](doc/test-record/12.png)

### 视频截帧，并回写，生成 presign url
![](doc/test-record/13.png)


## TOS 文档
* Python SDK 简介:https://www.volcengine.com/docs/6349/92785
* 安装 Python SDK:https://www.volcengine.com/docs/6349/93479
* 初始化客户端（Python SDK）:https://www.volcengine.com/docs/6349/93483
* 快速入门（Python SDK）:https://www.volcengine.com/docs/6349/92786
* 普通预签名（Python SDK）:https://www.volcengine.com/docs/6349/135725
* 创建桶(PythonSDK):https://www.volcengine.com/docs/6349/92793
* 列举桶(PythonSDK):https://www.volcengine.com/docs/6349/92794
* 获取桶元数据(PythonSDK):https://www.volcengine.com/docs/6349/92795
* 删除桶(PythonSDK):https://www.volcengine.com/docs/6349/92796
* 普通上传（Python SDK）:https://www.volcengine.com/docs/6349/92800
* 普通下载（Python SDK）:https://www.volcengine.com/docs/6349/92803
* 列举对象 V2（Python SDK）:https://www.volcengine.com/docs/6349/173820
* 删除对象（Python SDK）:https://www.volcengine.com/docs/6349/92805
* 基础图片处理（Python SDK）:https://www.volcengine.com/docs/6349/1157332
* 获取图片信息（Python SDK）:https://www.volcengine.com/docs/6349/1157336
* 图片处理持久化（Python SDK）:https://www.volcengine.com/docs/6349/1157338
* 视频截帧（Python SDK）:https://www.volcengine.com/docs/6349/1157340
* 获取视频信息（Python SDK）:https://www.volcengine.com/docs/6349/1157341
* 获取视频信息（Python SDK）:https://www.volcengine.com/docs/6349/1157343

## Appendix
* 本项目参考 https://github.com/dinghuazhou/sample-mcp-server-tos