MinIO PUT MCP 服务器

PUT-only 的 MinIO MCP 服务器 — 只上传、不查询、不删除，专为数据归档与写入场景设计。

---

仓库地址

https://github.com/zymeli/minio-put-mcp.git

---

适用场景

• 需要将文件、数据流归档到 MinIO 存储
• 审计合规要求：按 日期/机器/文件 三级路径自动组织存储结构
• 杜绝误删、误读操作，服务器只开放上传权限

核心概念

每次上传的 目标路径 由三个标识串联而成：

存储桶 / <did> / <sid> / <fid>

标识	全称	说明
did	Date ID	日期，yyyy-mm-dd 格式
sid	Source ID	来源机器标识，32 位 MD5 hex
fid	File ID	文件标识，UUID v4 格式

路径示例

my-bucket/2026-07-29/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/550e8400-e29b-41d4-a716-446655440000

每个文件上传后，还会自动生成一个 元数据 JSON 文件，存储在相同路径但附加 .json 后缀：

my-bucket/2026-07-29/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/550e8400-e29b-41d4-a716-446655440000.json

元数据文件记录了原始输入信息、上传结果和精确时间戳，便于后续审计与追踪。

---

帮助信息

服务启动时可通过 --help 或 -h 参数查看完整的帮助说明：

node build/index.js --help

帮助信息包含所有启动参数说明、工具列表、返回值格式和示例，输出到 stderr。

---

安装

# 克隆项目后安装依赖
git clone https://github.com/zymeli/minio-put-mcp.git
cd minio-put-mcp
npm install

# 编译
npm run build

启动参数

node build/index.js \
  --endpoint=192.168.1.100 \
  --port=9000 \
  --access-key=YOUR_ACCESS_KEY \
  --secret-key=YOUR_SECRET_KEY \
  [--use-ssl=false] \
  [--region=us-east-1] \
  [--did=2026-07-29] \
  [--sid=abc123...] \
  [--fid=550e8400-...]

参数	必需	说明
--endpoint	是	MinIO 服务器地址
--port	否	端口，默认 9000
--access-key	是	访问密钥
--secret-key	是	秘密密钥
--use-ssl	否	是否使用 SSL，默认 false
--region	否	区域设置
--did	否	日期 yyyy-mm-dd，未指定时用当天日期
--sid	否	32 位 MD5 hex，未指定时根据本机硬件指纹自动生成
--fid	否	UUID 格式，未指定时随机生成（单文件模式优先使用）

SID 自动生成规则

当不指定 --sid 时，服务器启动时自动收集本机以下信息：

1. 主机名（os.hostname()）
2. 所有非零网络接口 MAC 地址

将以上信息拼接后取 MD5，生成 32 位 hex 作为默认识别 ID。同一台机器多次启动结果一致。

---

MCP 工具

1. put_file — 上传单个文件

输入参数：

{
  "bucketName": "my-bucket",
  "filePath": "D:\\report.pdf",
  "metadata": { "department": "finance" }
}

执行效果：

• 自动生成目标路径 did/sid/fid
• 上传文件本体
• 上传元数据 JSON（含 etag、时间戳等）

---

2. put_files — 批量上传文件

输入参数：

{
  "bucketName": "my-bucket",
  "files": [
    { "filePath": "D:\\photo1.jpg", "metadata": { "tag": "travel" } },
    { "filePath": "D:\\photo2.jpg" }
  ]
}

执行效果：

• 共享同一 did 和 sid
• 每个文件独立生成 fid
• 逐个上传，失败不影响后续文件

---

3. put_stream — 流式上传（从 URL 源）

输入参数：

{
  "bucketName": "my-bucket",
  "sourceUrl": "https://example.com/large-audio.mp3",
  "contentType": "audio/mpeg",
  "metadata": { "description": "会议录音" }
}

执行效果：

• 从 sourceUrl 获取数据，流式直传 MinIO
• 数据不落盘、不占用内存，适合音视频等大文件
• 自动从 HTTP 响应头推导 content-type

---

返回值

所有 MCP 工具执行完成后，返回值即是上传到 MinIO 的元数据 JSON 文件内容， 与服务器上 <did>/<sid>/<fid>.json 中存储的数据完全一致。

工具	返回格式
put_file	单个元数据 JSON 对象
put_stream	单个元数据 JSON 对象
put_files	元数据 JSON 对象数组

返回示例 (put_file / put_stream)

{
  "schema": "https://github.com/zymeli/minio-put-mcp",
  "objectName": "2026-07-29/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/550e8400-e29b-41d4-a716-446655440000",
  "did": "2026-07-29",
  "sid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "fid": "550e8400-e29b-41d4-a716-446655440000",
  "originalInput": {
    "bucketName": "my-bucket",
    "filePath": "D:\\report.pdf",
    "metadata": { "department": "finance" }
  },
  "putResult": {
    "etag": "\"5d41402abc4b2a76b9719d911017c592\"",
    "versionId": null
  },
  "timestamp": "2026-07-29T10:30:00.000Z"
}

返回示例 (put_files 批量)

[
  {
    "schema": "https://github.com/zymeli/minio-put-mcp",
    "objectName": "2026-07-29/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/550e8400-e29b-41d4-a716-446655440000",
    "did": "2026-07-29",
    "sid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "fid": "550e8400-e29b-41d4-a716-446655440000",
    "originalInput": { ... },
    "putResult": { "etag": "...", "versionId": null },
    "timestamp": "2026-07-29T10:30:00.000Z"
  },
  {
    "schema": "https://github.com/zymeli/minio-put-mcp",
    "objectName": "2026-07-29/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/660e8400-e29b-41d4-a716-446655440001",
    "did": "2026-07-29",
    "sid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "fid": "660e8400-e29b-41d4-a716-446655440001",
    "originalInput": { ... },
    "putResult": { "etag": "", "versionId": null },
    "timestamp": "2026-07-29T10:30:01.000Z",
    "error": "文件不存在: D:\\missing.jpg"
  }
]

---

元数据 JSON 结构

上传完成后，每个文件对应一个 .json 元数据文件，内容示例如下：

{
  "schema": "https://github.com/zymeli/minio-put-mcp",
  "objectName": "2026-07-29/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/550e8400-e29b-41d4-a716-446655440000",
  "did": "2026-07-29",
  "sid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "fid": "550e8400-e29b-41d4-a716-446655440000",
  "originalInput": {
    "bucketName": "my-bucket",
    "filePath": "D:\\report.pdf",
    "metadata": { "department": "finance" }
  },
  "putResult": {
    "etag": "\"5d41402abc4b2a76b9719d911017c592\"",
    "versionId": null
  },
  "timestamp": "2026-07-29T10:30:00.000Z"
}

字段	说明
schema	JSON schema 来源，指向项目仓库，AI Agent 可借此理解各字段含义
objectName	文件在存储桶内的落盘路径，格式 <did>/<sid>/<fid>，下游 Agent 可直接定位
did	本次会话的日期标识
sid	本次会话的来源机器标识
fid	本次上传文件的唯一标识
originalInput	用户上传时传入的原始参数
putResult	MinIO 返回的上传结果（etag、versionId），失败时 etag 为空
timestamp	上传完成的精确时间（ISO 8601）
error	（仅失败时存在）错误描述信息

---

开发

# 启动监听编译
npm run dev

# 编译
npm run build

# 启动服务（需先连接 MinIO）
npm run start -- --endpoint=... --access-key=... --secret-key=...

技术栈

• 运行时: Node.js >= 18.0
• 语言: TypeScript 5.x
• MCP 协议: @modelcontextprotocol/sdk ^1.0.0
• MinIO 客户端: minio ^8.0.1
• 数据校验: zod ^3.22.4

许可证

MIT