使用说明

MinIO MCP服务器

用于与MinIO对象存储交互的模型上下文协议（MCP）服务器。此服务器在Docker中运行，并提供用于上传、下载和管理MinIO bucket中文件的工具。

🚀 快速开始

选项1：使用Docker Run（建议用于Cursor MCP）

拉取Docker镜像：

docker pull foxsnow/minio-mcp

选项2：使用Docker Compose

步骤1：创建.env文件

创建一个 .env 文件在 mcp/minioMcp 目录：

# MinIO Server Configuration
MINIO_ENDPOINT=your-minio-server.com
MINIO_PORT=9000
MINIO_USERNAME=your-access-key
MINIO_PASSWORD=your-secret-key
MINIO_USE_SSL=false

# MCP Server Configuration
MCP_PORT=5055

# Permissions (true/false)
MINIO_CAN_READ=true
MINIO_CAN_EDIT=true
MINIO_CAN_DELETE=true
MINIO_CAN_CREATE=true

⚠️ 安全说明： 这 .env 文件通过以下方式自动从git中排除 .gitignore。切勿将凭据提交到版本控制！

第二步：从Docker Compose开始

cd mcp/minioMcp
docker-compose up -d

步骤3：停止服务

docker-compose down

在游标中配置

将此配置添加到您的 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "minio-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/Users/your-username/path/to/downloads:/downloads",
        "-e",
        "MINIO_ENDPOINT=your-minio-server.com",
        "-e",
        "MINIO_PORT=443",
        "-e",
        "MINIO_USERNAME=your-username",
        "-e",
        "MINIO_PASSWORD=your-password",
        "-e",
        "MINIO_USE_SSL=true",
        "-e",
        "MINIO_CAN_READ=true",
        "-e",
        "MINIO_CAN_EDIT=true",
        "-e",
        "MINIO_CAN_DELETE=true",
        "-e",
        "MINIO_CAN_CREATE=true",
        "-e",
        "DOWNLOAD_PATH=/downloads",
        "foxsnow/minio-mcp"
      ]
    }
  }
}

📋 配置参数

Docker Args详解

参数	描述
`run -i --rm`	以交互方式运行容器，并在停止时将其删除
`-v /host/path:/downloads`	将本地文件夹装载到容器的 `/downloads` 文件夹
`-e MINIO_ENDPOINT`	MinIO服务器地址（不含http/https）
`-e MINIO_PORT`	MinIO服务器端口（通常为9000或443）
`-e MINIO_USERNAME`	MinIO访问密钥/用户名
`-e MINIO_PASSWORD`	MinIO密钥/密码
`-e MINIO_USE_SSL`	使用HTTPS连接(`true` 或 `false`)
`-e MINIO_CAN_READ`	允许读取操作(`true` 或 `false`)
`-e MINIO_CAN_EDIT`	允许编辑操作(`true` 或 `false`)
`-e MINIO_CAN_DELETE`	允许删除操作(`true` 或 `false`)
`-e MINIO_CAN_CREATE`	允许创建/上传操作(`true` 或 `false`)
`-e DOWNLOAD_PATH`	容器的下载目录（使用 `/downloads`)

🔒 重要提示：Docker文件系统限制

⚠️ 批判性理解

此MCP服务器在Docker内部运行，这意味着它具有有限的文件系统访问权限：

✅ 可以访问： 仅装载的文件 /downloads 目录
❌ 无法访问： 主机系统上其他任何位置的文件
📁 卷装载： 这 -v flag将您的主机目录映射到容器的 /downloads

文件路径示例

✅ 正确的文件路径（容器内部）

/downloads/myfile.jpg
/downloads/documents/report.pdf
/downloads/subfolder/image.png

❌ 文件路径不正确（将失败）

/Users/username/Documents/file.jpg    ❌ Host path - not accessible
C:\Users\file.jpg                      ❌ Windows path - not accessible
~/Downloads/file.jpg                   ❌ Home directory - not accessible

📤 如何上传文件

步骤1：将文件复制到下载文件夹

首先，将您的文件复制到您在Docker中挂载的文件夹中：

# Example: If you mounted /Users/username/minio-downloads:/downloads
cp /path/to/your/file.jpg /Users/username/minio-downloads/

步骤2：使用MCP上传

使用容器路径的MCP工具(/downloads/filename):

// In Cursor AI Chat
Upload /downloads/file.jpg to bucket "my-bucket"

例子：

File location on host: /Users/john/minio-downloads/photo.jpg
File location in container: /downloads/photo.jpg
Use in MCP: /downloads/photo.jpg ✅

📥 如何下载文件

使用MCP从MinIO下载

下载的文件会自动保存到 /downloads 容器内的目录，该目录映射到您的主机文件夹。

例子：

Download object "report.pdf" from bucket "documents"
→ File saved to: /downloads/report.pdf
→ Available on host at: /Users/username/minio-downloads/report.pdf

🛠️ 可用操作

铲斗操作

list_buckets -列出所有桶
make_bucket -创建新bucket
bucket_exists -检查铲斗是否存在
remove_bucket -取出一个空桶
list_objects -列出bucket中的对象

上传操作

fput_object -从以下位置上传文件 /downloads 目录
put_object -上传文本/字符串内容
upload_folder -从上传整个文件夹 /downloads

下载操作

get_object -下载小文本文件
文件保存到 /downloads 目录

对象管理

stat_object -获取对象元数据
copy_object -在MinIO中复制对象
remove_object -删除对象
remove_objects -删除多个对象

预先签名的URL

presigned_get_object -生成临时下载URL
presigned_put_object -生成临时上传URL

💡 用法示例

示例1：上传图像

# 1. Copy image to downloads folder
cp ~/Pictures/photo.jpg /Users/username/minio-downloads/

# 2. In Cursor AI, ask:
"Upload /downloads/photo.jpg to bucket 'photos' as 'vacation-2024.jpg'"

示例2：上传多个文件

# 1. Copy files to a subfolder
mkdir -p /Users/username/minio-downloads/documents
cp ~/Documents/*.pdf /Users/username/minio-downloads/documents/

# 2. In Cursor AI, ask:
"Upload all files from /downloads/documents to bucket 'my-docs'"

示例3：下载文件

"Download the file 'report.pdf' from bucket 'documents'"

该文件将出现在您已挂载的下载文件夹中： /Users/username/minio-downloads/report.pdf

🐛 故障排除

错误：“文件不存在”

原因： 文件不在已装载的 /downloads 目录。

解决方案：

检查您的音量： -v /host/path:/downloads
将文件复制到已装载的主机目录
使用容器路径： /downloads/filename

错误：“权限被拒绝”

原因： Docker无权访问已挂载的文件夹。

解决方案：

# Give Docker access to the folder
chmod -R 755 /path/to/your/downloads

下载后文件未显示

检查：

查看已装载的主机目录（不是 /downloads)
验证您的中的卷装载量 mcp.json
检查容器权限

🔐 安全最佳实践

专用下载文件夹： 为MinIO传输创建一个特定文件夹
权限控制： 使用 MINIO_CAN_* 用于限制操作的标志
临时文件： 定期清理下载文件夹
敏感数据： 不要将凭据或敏感文件留在下载文件夹中

📝 高级配置

只读模式

{
  "minio-mcp": {
    "args": [
      // ... other args ...
      "-e",
      "MINIO_CAN_READ=true",
      "-e",
      "MINIO_CAN_EDIT=false",
      "-e",
      "MINIO_CAN_DELETE=false",
      "-e",
      "MINIO_CAN_CREATE=false"
    ]
  }
}

多个MinIO服务器

{
  "mcpServers": {
    "minio-production": {
      // ... production config ...
    },
    "minio-development": {
      // ... development config ...
    }
  }
}

🔨 开发与建筑

在本地构建Docker镜像

cd mcp/minioMcp
docker build -t minio-mcp .

运行本地构建的映像

docker run -i --rm \
  -v $(pwd)/downloads:/downloads \
  -e MINIO_ENDPOINT=your-server.com \
  -e MINIO_PORT=443 \
  -e MINIO_USERNAME=your-username \
  -e MINIO_PASSWORD=your-password \
  -e MINIO_USE_SSL=true \
  -e MINIO_CAN_READ=true \
  -e MINIO_CAN_EDIT=true \
  -e MINIO_CAN_DELETE=true \
  -e MINIO_CAN_CREATE=true \
  minio-mcp

重建TypeScript

npm run build

推送到Docker Hub（仅限维护人员）

# Build for multiple platforms
docker buildx build --platform linux/amd64,linux/arm64 \
  -t foxsnow/minio-mcp:latest \
  -t foxsnow/minio-mcp:v1.0.0 \
  --push .