foxsnow/minio-mcp

•Updated 11 months ago

https://github.com/myagizmaktav/minio-mcp

Image

257

foxsnow/minio-mcp repository overview

⁠MinIO MCP Server

A Model Context Protocol (MCP) server for interacting with MinIO object storage. This server runs inside Docker and provides tools for uploading, downloading, and managing files in MinIO buckets.

⁠🚀 Quick Start

⁠Option 1: Using Docker Run (Recommended for Cursor MCP)

Pull the Docker image:

docker pull foxsnow/minio-mcp

⁠Option 2: Using Docker Compose

⁠Step 1: Create .env File

Create a .env file in the mcp/minioMcp directory:

# 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

⚠️ Security Note: The .env file is automatically excluded from git via .gitignore. Never commit credentials to version control!

⁠Step 2: Start with Docker Compose

cd mcp/minioMcp
docker-compose up -d

⁠Step 3: Stop the Service

docker-compose down

⁠Configure in Cursor

Add this configuration to your ~/.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"
      ]
    }
  }
}

⁠📋 Configuration Parameters

⁠Docker Args Explained

Argument	Description
`run -i --rm`	Run container interactively and remove it when stopped
`-v /host/path:/downloads`	Mount your local folder to container's `/downloads` folder
`-e MINIO_ENDPOINT`	MinIO server address (without http/https)
`-e MINIO_PORT`	MinIO server port (typically 9000 or 443)
`-e MINIO_USERNAME`	MinIO access key / username
`-e MINIO_PASSWORD`	MinIO secret key / password
`-e MINIO_USE_SSL`	Use HTTPS connection (`true` or `false`)
`-e MINIO_CAN_READ`	Allow read operations (`true` or `false`)
`-e MINIO_CAN_EDIT`	Allow edit operations (`true` or `false`)
`-e MINIO_CAN_DELETE`	Allow delete operations (`true` or `false`)
`-e MINIO_CAN_CREATE`	Allow create/upload operations (`true` or `false`)
`-e DOWNLOAD_PATH`	Container's download directory (use `/downloads`)

⁠🔒 Important: Docker Filesystem Restrictions

⁠⚠️ Critical Understanding

This MCP server runs inside Docker, which means it has LIMITED filesystem access:

✅ Can access: Only files in the mounted /downloads directory
❌ Cannot access: Files anywhere else on your host system
📁 Volume Mount: The -v flag maps your host directory to container's /downloads

⁠File Path Examples

⁠✅ Correct File Paths (Inside Container)

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

⁠❌ Incorrect File Paths (Will Fail)

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

⁠📤 How to Upload Files

⁠Step 1: Copy File to Downloads Folder

First, copy your file to the folder you mounted in Docker:

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

⁠Step 2: Upload Using MCP

Use the MCP tool with the container's path (/downloads/filename):

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

Example:

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

⁠📥 How to Download Files

⁠Using MCP to Download from MinIO

Downloaded files are automatically saved to the /downloads directory inside the container, which is mapped to your host folder.

Example:

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

⁠🛠️ Available Operations

⁠Bucket Operations

list_buckets - List all buckets
make_bucket - Create a new bucket
bucket_exists - Check if bucket exists
remove_bucket - Remove an empty bucket
list_objects - List objects in a bucket

⁠Upload Operations

fput_object - Upload a file from /downloads directory
put_object - Upload text/string content
upload_folder - Upload entire folder from /downloads

⁠Download Operations

get_object - Download small text files
Files are saved to /downloads directory

⁠Object Management

stat_object - Get object metadata
copy_object - Copy objects within MinIO
remove_object - Delete an object
remove_objects - Delete multiple objects

⁠Presigned URLs

presigned_get_object - Generate temporary download URL
presigned_put_object - Generate temporary upload URL

⁠💡 Usage Examples

⁠Example 1: Upload an Image

# 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'"

⁠Example 2: Upload Multiple Files

# 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'"

⁠Example 3: Download a File

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

The file will appear in your mounted downloads folder: /Users/username/minio-downloads/report.pdf

⁠🐛 Troubleshooting

⁠Error: "File does not exist"

Cause: The file is not in the mounted /downloads directory.

Solution:

Check your volume mount: -v /host/path:/downloads
Copy the file to the mounted host directory
Use the container path: /downloads/filename

⁠Error: "Permission denied"

Cause: Docker doesn't have permission to access the mounted folder.

Solution:

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

⁠Files Not Appearing After Download

Check:

Look in the mounted host directory (not /downloads)
Verify the volume mount in your mcp.json
Check container permissions

⁠🔐 Security Best Practices

Dedicated Downloads Folder: Create a specific folder just for MinIO transfers
Permission Control: Use MINIO_CAN_* flags to restrict operations
Temporary Files: Clean up the downloads folder regularly
Sensitive Data: Don't leave credentials or sensitive files in downloads folder

⁠📝 Advanced Configuration

⁠Read-Only Mode

{
  "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"
    ]
  }
}

⁠Multiple MinIO Servers

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

⁠🔨 Development & Building

⁠Build Docker Image Locally

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

⁠Run Locally Built Image

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

⁠Rebuild TypeScript

npm run build

⁠Push to Docker Hub (Maintainers Only)

# 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 .

⁠📚 Additional Resources

⁠🤝 Contributing

Issues and pull requests are welcome at the GitHub repository.

⁠📄 License

This project is licensed under the Apache License 2.0.

Tag summary

Recent tags

Content type

Image

Digest

sha256:a7d610619…

Size

71.3 MB

Last updated

11 months ago

docker pull foxsnow/minio-mcp