Skip to main content
Glama
zymeli

MinIO PUT MCP Server

by zymeli
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
JavaScript
Local

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。

安装

方式一：npm 全局安装（推荐）

包已发布到 npm，可直接全局安装，无需克隆仓库：

npm install -g minio-put-mcp

安装后可直接用 minio-put-mcp 命令启动：

minio-put-mcp --endpoint=192.168.1.100 --port=9000 --access-key=YOUR_ACCESS_KEY --secret-key=YOUR_SECRET_KEY

方式二：npx 免安装运行

无需安装，npx 会自动从 npm 拉取并运行（-y 跳过确认）：

npx -y minio-put-mcp --endpoint=192.168.1.100 --port=9000 --access-key=YOUR_ACCESS_KEY --secret-key=YOUR_SECRET_KEY

方式三：源码编译

git clone https://github.com/zymeli/minio-put-mcp.git
cd minio-put-mcp
npm install

# 编译
npm run build

在 AI Agent 中配置（mcp.json）

支持 node.exe 与 npx 两种驱动方式，任选其一即可。

方式一：npx 驱动（推荐，免安装）

npx 会自动从 npm 拉取最新版本包，无需手动安装：

{
  "mcpServers": {
    "minio-put-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "minio-put-mcp",
        "--endpoint=192.168.1.100",
        "--port=9000",
        "--access-key=YOUR_ACCESS_KEY",
        "--secret-key=YOUR_SECRET_KEY"
      ]
    }
  }
}

Windows 提示：部分 AI Agent（如 Claude Desktop）需要将 command 写为 npx.cmd 才能正确识别。

方式二：node.exe 直接驱动（本地已安装包）

需先在本地安装包或克隆源码编译，再指向 build/index.js：

{
  "mcpServers": {
    "minio-put-mcp": {
      "command": "node",
      "args": [
        "D:/path/to/minio-put-mcp/build/index.js",
        "--endpoint=192.168.1.100",
        "--port=9000",
        "--access-key=YOUR_ACCESS_KEY",
        "--secret-key=YOUR_SECRET_KEY"
      ]
    }
  }
}

安全提示：密钥会明文出现在 mcp.json 中，请确保该文件仅本人可读写，或改用环境变量传递。

启动参数

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

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