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