Skip to main content
Glama
zymeli

MinIO PUT MCP Server

by zymeli
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

MinIO PUT MCP 服务器

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

仓库地址

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

Related MCP server: @zhigang1992/uploadfile-mcp

适用场景

  • 需要将文件、数据流归档到 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

Install Server
A
license - permissive license
A
quality
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
2Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/zymeli/minio-put-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server