Overview

VolcEngine TOS MCP Server 提供一个基于 MCP（Model Context Protocol）的服务层，允许开发者通过自然语言查询和检索存储在火山引擎 TOS（对象存储）中的资源。它将 TOS 的桶和对象信息以工具（Tool）的形式暴露给上层大模型或智能代理，简化数据发现、快速读取对象内容，并可将二进制对象以 Base64 返回以便后续处理。

该服务适合需要把存储数据与自然语言理解能力结合的场景，例如内容检索、智能助理、媒体管理系统或数据探索平台。通过标准化的 Tools 接口，它能无缝集成到火山引擎的 MCP 生态或第三方大模型代理中。

GitHub 仓库：https://github.com/dinghuazhou/sample-mcp-server-tos

Features

支持自然语言驱动的 TOS 资源检索与浏览
三类核心工具：列举桶、列举对象、读取对象（文本/二进制）
文本对象直接返回内容；二进制（图片/视频）以 Base64 编码返回
支持分页、前缀过滤与续传 Token
可作为 MCP Server 在方舟（Ark）、Python、Cursor 等平台上适配运行
使用火山引擎标准鉴权（AccessKey/SecretKey/Region/Endpoint）

Installation / Configuration

先决条件：

Python 3.10+
推荐使用 uv / uvx 运行（详见下文）

克隆仓库并进入项目目录：

git clone https://github.com/dinghuazhou/sample-mcp-server-tos.git
cd sample-mcp-server-tos

环境变量（在 .env 或进程环境中设置）：

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"
export VOLCENGINE_REGION="your-region"
export TOS_ENDPOINT="https://tos-region.volcengineapi.com"
# 可选
export SECURITY_TOKEN=""
export TOS_BUCKETS="bucket1,bucket2"

常用命令（使用 uv）：

# 使用 uv 同步依赖并构建
uv sync
uv build

# 直接运行 mcp server（示例）
uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/src/mcp_server_tos run mcp-server-tos

在 MCP settings 中注册（示例）：

{
  "mcpServers": {
    "tos-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/src/mcp_server_tos",
        "run",
        "mcp-server-tos"
      ]
    }
  }
}

可配置环境变量（表格）

环境变量	描述	必需
VOLCENGINE_ACCESS_KEY	火山引擎访问密钥 ID	是
VOLCENGINE_SECRET_KEY	火山引擎访问密钥 Secret	是
VOLCENGINE_REGION	TOS 区域	是
TOS_ENDPOINT	TOS Endpoint URL	是
SECURITY_TOKEN	临时安全 Token（可选）	否
TOS_BUCKETS	指定可访问的桶列表（逗号分隔，可选）	否

Available Tools

该 MCP Server 暴露以下 Tools（接口），可以被上层大模型或代理调用。

list_buckets
- 类型：SaaS
- 描述：列出当前账号拥有的 TOS 存储桶（包含桶名、创建时间、位置、访问域名等）。
- 调试输入（简化示例）：
```
{
  "name": "list_buckets",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}
```
- 最容易触发的 Prompt 示例：列举火山引擎 TOS 的存储桶列表。

list_objects

类型：SaaS
描述：列出指定桶下的对象。支持 prefix、start_after、continuation_token 分页与过滤（每次最多返回 1000 条）。

调试输入示例：

{
  "name": "list_objects",
  "inputSchema": {
    "type": "object",
    "required": ["bucket"],
    "properties": {
      "bucket": {"type": "string"},
      "prefix": {"type": "string"},
      "start_after": {"type": "string"},
      "continuation_token": {"type": "string"}
    }
  }
}

Prompt 示例：列举火山引擎 TOS 的 example 桶下的对象。

get_object

类型：SaaS
描述：获取指定对象内容。文本类型直接返回文本；二进制类型返回 Base64 字符串。

调试输入示例：

{
  "name": "get_object",
  "inputSchema": {
    "type": "object",
    "required": ["bucket", "key"],
    "properties": {
      "bucket": {"type": "string"},
      "key": {"type": "string"}
    }
  }
}

Prompt 示例：读取火山引擎 TOS 桶 example 下名为 example.txt 的文件内容

Use Cases

交互式数据探索：在大模型助手中输入自然语言，如“显示上个月上传到 media 桶的所有视频”，代理调用 list_objects + 筛选并返回结果列表。
文件快速读取：用户询问“把 logs/2026-04-01.log 的内容发给我”，系统调用 get_object 并将文本直接呈现。
媒体预览 & 处理：检索到图片或视频时，get_object 返回 Base64，可供前端解码展示或传递给后续的视觉模型进行分析。
自定义搜索体验：结合外部向量搜索，将对象元数据与文本内容索引起来，由大模型执行语义检索并调用本服务拉取原始对象以供展示或处理。

适配与扩展

支持在方舟（Ark）、Python 或 Cursor 平台上作为 MCP Server 运行和调试。
可在项目中扩展更多 Tool（例如对象删除、上传、元数据查询）以满足业务需求。
建议将敏感凭据置于安全的密钥管理系统（KMS）或环境变量注入管道，而不是源码或公共配置文件中。

更多细节与源码示例，请参见仓库：https://github.com/dinghuazhou/sample-mcp-server-tos 。

VolcEngine TOS MCP Server Natural Language Retrieval