# 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

```bash
pip install minio-mcp
```

### Using uv (recommended)

```bash
uv pip install minio-mcp
```

### From source

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

## Configuration

Set the following environment variables:

```bash
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:

```env
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):

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

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

```json
{}
```

#### minio_make_bucket
Create a new bucket.

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

#### minio_remove_bucket
Remove an empty bucket.

```json
{
  "bucket_name": "my-bucket"
}
```

#### minio_bucket_exists
Check if a bucket exists.

```json
{
  "bucket_name": "my-bucket"
}
```

### Object Operations

#### minio_list_objects
List objects in a bucket.

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

#### minio_get_object
Get object content.

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

#### minio_put_object
Upload content as an object.

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

#### minio_upload_file
Upload a local file.

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

#### minio_download_file
Download object to local file.

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

#### minio_remove_object
Remove an object.

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

#### minio_stat_object
Get object metadata.

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

#### minio_presigned_url
Generate a presigned URL for downloading.

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

#### minio_copy_object
Copy an object.

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

## Development

### Setup Development Environment

```bash
# 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

```bash
pytest
```

## Quick Start with MinIO

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

```bash
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