MinIO MCP Server

MCP (Model Context Protocol) server for MinIO object storage operations. This server provides tools for interacting with MinIO/S3-compatible storage through Claude and other MCP clients.

Features

Bucket Operations

• minio_list_buckets - List all buckets
• minio_make_bucket - Create a new bucket
• minio_remove_bucket - Remove an empty bucket
• minio_bucket_exists - Check if a bucket exists

Object Operations

• minio_list_objects - List objects in a bucket
• minio_get_object - Get object content
• minio_put_object - Upload content as an object
• minio_upload_file - Upload a local file
• minio_download_file - Download object to local file
• minio_remove_object - Remove an object
• minio_stat_object - Get object metadata
• minio_presigned_url - Generate presigned download URL
• minio_copy_object - Copy object to another location

Installation

Using pip

pip install minio-mcp

Using uv (recommended)

uv pip install minio-mcp

From source

git clone <repository-url>
cd minio-mcp
pip install -e .

Configuration

Set the following environment variables:

export MINIO_ENDPOINT="localhost:9000"
export MINIO_ACCESS_KEY="your-access-key"
export MINIO_SECRET_KEY="your-secret-key"
export MINIO_SECURE="false"  # Set to "true" for HTTPS

Or create a .env file:

MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=your-access-key
MINIO_SECRET_KEY=your-secret-key
MINIO_SECURE=false

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/AppData/Roaming/Claude/claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "minio": {
      "command": "uv",
      "args": ["--directory", "D:\\Documents\\minio-mcp", "run", "minio-mcp"],
      "env": {
        "MINIO_ENDPOINT": "localhost:9000",
        "MINIO_ACCESS_KEY": "your-access-key",
        "MINIO_SECRET_KEY": "your-secret-key",
        "MINIO_SECURE": "false"
      }
    }
  }
}

Or using Python directly:

{
  "mcpServers": {
    "minio": {
      "command": "python",
      "args": ["-m", "minio_mcp.server"],
      "env": {
        "MINIO_ENDPOINT": "localhost:9000",
        "MINIO_ACCESS_KEY": "your-access-key",
        "MINIO_SECRET_KEY": "your-secret-key",
        "MINIO_SECURE": "false"
      }
    }
  }
}

Tool Reference

Bucket Operations

minio_list_buckets

List all buckets in MinIO storage.

{}

minio_make_bucket

Create a new bucket.

{
  "bucket_name": "my-new-bucket"
}

minio_remove_bucket

Remove an empty bucket.

{
  "bucket_name": "my-bucket"
}

minio_bucket_exists

Check if a bucket exists.

{
  "bucket_name": "my-bucket"
}

Object Operations

minio_list_objects

List objects in a bucket.

{
  "bucket_name": "my-bucket",
  "prefix": "folder/",
  "recursive": true
}

minio_get_object

Get object content.

{
  "bucket_name": "my-bucket",
  "object_name": "path/to/file.txt"
}

minio_put_object

Upload content as an object.

{
  "bucket_name": "my-bucket",
  "object_name": "new-file.txt",
  "content": "Hello, MinIO!",
  "content_type": "text/plain"
}

minio_upload_file

Upload a local file.

{
  "bucket_name": "my-bucket",
  "object_name": "uploaded-file.txt",
  "file_path": "/path/to/local/file.txt"
}

minio_download_file

Download object to local file.

{
  "bucket_name": "my-bucket",
  "object_name": "file.txt",
  "file_path": "/path/to/save/file.txt"
}

minio_remove_object

Remove an object.

{
  "bucket_name": "my-bucket",
  "object_name": "file-to-delete.txt"
}

minio_stat_object

Get object metadata.

{
  "bucket_name": "my-bucket",
  "object_name": "file.txt"
}

minio_presigned_url

Generate a presigned URL for downloading.

{
  "bucket_name": "my-bucket",
  "object_name": "file.txt",
  "expires": 3600
}

minio_copy_object

Copy an object.

{
  "source_bucket": "source-bucket",
  "source_object": "file.txt",
  "dest_bucket": "dest-bucket",
  "dest_object": "copied-file.txt"
}

Development

Setup Development Environment

# Clone the repository
git clone <repository-url>
cd minio-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate  # Windows

# Install with dev dependencies
pip install -e ".[dev]"

Running Tests

pytest

Quick Start with MinIO

If you don't have MinIO running, you can start it with Docker:

docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  minio/minio server /data --console-address ":9001"

Then configure the MCP server with:

• MINIO_ENDPOINT=localhost:9000
• MINIO_ACCESS_KEY=minioadmin
• MINIO_SECRET_KEY=minioadmin
• MINIO_SECURE=false

The MinIO Console will be available at http://localhost:9001

License

MIT License