Skip to main content
Glama
zymeli

MinIO PUT MCP Server

by zymeli
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local
README.md
# MinIO PUT MCP 服务器

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

---

## 仓库地址

[https://github.com/zymeli/minio-put-mcp.git](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` 参数查看完整的帮助说明：

```bash
node build/index.js --help
```

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

---

## 安装

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

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

```bash
npm install -g minio-put-mcp
```

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

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

### 方式二：npx 免安装运行

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

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

### 方式三：源码编译

```bash
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 拉取最新版本包，无需手动安装：

```json
{
  "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`：

```json
{
  "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 中，请确保该文件仅本人可读写，或改用环境变量传递。

## 启动参数

```bash
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` — 上传单个文件

**输入参数：**
```json
{
  "bucketName": "my-bucket",
  "filePath": "D:\\report.pdf",
  "metadata": { "department": "finance" }
}
```

**执行效果：**
- 自动生成目标路径 `did/sid/fid`
- 上传文件本体
- 上传元数据 JSON（含 etag、时间戳等）

---

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

**输入参数：**
```json
{
  "bucketName": "my-bucket",
  "files": [
    { "filePath": "D:\\photo1.jpg", "metadata": { "tag": "travel" } },
    { "filePath": "D:\\photo2.jpg" }
  ]
}
```

**执行效果：**
- 共享同一 `did` 和 `sid`
- 每个文件独立生成 `fid`
- 逐个上传，失败不影响后续文件

---

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

**输入参数：**
```json
{
  "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`)

```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"
}
```

### 返回示例 (`put_files` 批量)

```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": { ... },
    "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` 元数据文件，内容示例如下：

```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` | （仅失败时存在）错误描述信息 |

---

## 开发

```bash
# 启动监听编译
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](./LICENSE)
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 across 3 tools

Disambiguation5/5

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

Naming Consistency5/5

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

Tool Count5/5

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

Completeness4/5

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

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources