What can you do with this server?

The MinIO PUT MCP Server is a write‑only archiving tool that supports: * Single file upload (put_file): Upload a local file to a MinIO bucket with automatic path organization and companion metadata generation. * Batch upload (put_files): Upload multiple local files in one call, sharing date and source identifiers while assigning unique file IDs and isolating individual failures. * URL streaming (put_stream): Fetch data from a remote URL and stream it directly into MinIO without local storage, suitable for large files; content type can be inferred or manually set. * Automatic structured paths: Objects are stored under bucket/did/sid/fid, where did is the date (yyyy-mm-dd), sid is a source fingerprint (auto‑generated from hostname/MAC or user‑provided), and fid is a unique UUID. * Automatic metadata: Every upload creates a sidecar JSON file recording the original input, upload result (etag, versionId), timestamp, and any errors for full auditability. * Strict PUT‑only design: No read or delete operations are permitted, ensuring data integrity and compliance with archival requirements. * CLI configuration: Endpoint, port, access keys, region, and default path components can be set via command‑line arguments. * AI agent integration: Supports npx and node.exe driving methods for seamless embedding into automated workflows. Overall, the server provides a minimal, secure, and auditable ingestion pipeline into MinIO object storage.

Which integrations are available for this server?

Allows uploading files and data streams to MinIO storage with automatic path organization (date/source/file), metadata generation, and audit trails. Provides tools for single file upload, batch upload, and streaming upload from URLs.

How do I use MinIO PUT MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MinIO PUT MCP Server Upload report.pdf to archive bucket" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MinIO PUT MCP Server

by zymeli

Overview Schema Source Related Servers Discussions Admin

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。

安装

方式一：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 时，服务器启动时自动收集本机以下信息：

主机名（os.hostname()）
所有非零网络接口 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

Available Tools

3 tools

put_fileA

上传单个本地文件到 MinIO。自动构建目标路径为 did/sid/fid，并上传元数据 JSON。返回元数据 JSON 对象 (含 did/sid/fid/originalInput/putResult/timestamp)。

Inputs: filePath (required), bucketName (required), metadata.

put_filesA

批量上传多个本地文件。共享同一 did/sid，每个文件独立生成 fid。返回元数据 JSON 对象数组。

Inputs: files (required), bucketName (required).

put_streamA

从 URL 源流式上传数据到 MinIO。数据不落盘，适合大文件。返回元数据 JSON 对象。

Inputs: sourceUrl (required), bucketName (required), metadata, contentType.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-07-30 05:15 across 3 tools

Disambiguation5/5

三个工具分别针对单文件上传、批量上传和流式上传，目的清晰不重叠。

Naming Consistency5/5

所有工具使用一致的 put_ 前缀加具体对象（file, files, stream），命名模式统一。

Tool Count5/5

3个工具完美覆盖服务器主题（上传到MinIO），数量适中，无冗余。

Completeness4/5

覆盖了单文件、批量、流式三种上传场景，但缺少列出或删除等管理操作，不过服务器名称限定了PUT操作。

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

thoughts
ai.thoughtbox.api
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Cloud Storage Finance
2
https://api.thoughtbox.ai/mcp
QuLab Infinite MCP Server
io.github.Workofarttattoo
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
Research & Data Command Line Code Execution
2
https://workofarttattoo-qulab-mcp.azurewebsites.net/mcp
Station Zero
services.stationzero
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Knowledge & Memory File Systems Workplace & Productivity
1
https://stationzero.services/mcp
Novada MCP
io.github.NovadaLabs
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Browser Automation Web Scraping Search
13
https://mcp.novada.com/mcp

Related MCP Servers

S3-Compatible 3D Storage MCP
Cloud Storage Cloud Platforms App Automation
TencentCloudADP-DevRel
F
license
Not graded
quality
D
maintenance
An MCP server for managing and publishing 3D files using S3-compatible storage providers like Cloudflare R2 and AWS S3. It enables users to upload models, generate interactive 3D viewers, and manage temporary access via presigned URLs.
Updated a year ago (2025-12-05 03:42 UTC)
-
@zhigang1992/uploadfile-mcp
Cloud Storage File Systems
zhigang1992
A
license
Not graded
quality
D
maintenance
An MCP server that enables users to upload local files to S3-compatible storage and retrieve shareable public URLs. Files are automatically organized into unique UUID-based folders to prevent naming conflicts while preserving original filenames.
Updated 10 months ago (2026-01-16 02:13 UTC)
16 npm
MIT
minio_mcp
Cloud Storage File Systems Developer Tools
ClearMind1
F
license
C
quality
D
maintenance
A FastMCP-based server that enables uploading text and base64-encoded content to MinIO object storage through an HTTP transport. It supports automated bucket management and secure file path generation to streamline remote storage operations.
Updated 9 months ago (2026-02-11 01:28 UTC)
-
mcp-server-s3
Cloud Platforms Cloud Storage File Systems
ofershap
A
license
A
quality
D
maintenance
MCP server for AWS S3 — list buckets, browse objects, upload/download files, and generate presigned URLs.
Updated 3 months ago (2026-08-10 07:38 UTC)
7
146 npm
4
MIT

MinIO PUT MCP 服务器

仓库地址

适用场景

核心概念

路径示例

帮助信息

安装

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

方式二：npx 免安装运行

方式三：源码编译

在 AI Agent 中配置（mcp.json）

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

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

启动参数

SID 自动生成规则

MCP 工具

1. put_file — 上传单个文件

2. put_files — 批量上传文件

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

返回值

返回示例 (put_file / put_stream)

返回示例 (put_files 批量)

元数据 JSON 结构

开发

技术栈

许可证

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

S3-Compatible 3D Storage MCP

@zhigang1992/uploadfile-mcp

minio_mcp

mcp-server-s3

1. `put_file` — 上传单个文件

2. `put_files` — 批量上传文件

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

返回示例 (`put_file` / `put_stream`)

返回示例 (`put_files` 批量)