---
slug: "minio"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ucesys/minio-python-mcp@main/README.md"
repo: "https://github.com/ucesys/minio-python-mcp"
source_file: "README.md"
branch: "main"
---
# MinIO Model-Context Protocol (MCP)

This project implements a Model-Context Protocol (MCP) server and client for MinIO object storage. It provides a standardized way to interact with MinIO.

## Features

### Server

#### Resources

Exposes MinIO data through **Resources**. The server can access and provide:
- Text files (automatically detected based on file extension)
- Binary files (handled as application/octet-stream)
- Bucket contents (up to 1000 objects per bucket)

#### Tools

* **ListBuckets**
  * Returns a list of all buckets owned by the authenticated sender of the request
  * Optional parameters: `start_after` (pagination), `max_buckets` (limit results)

* **ListObjects**
  * Returns some or all (up to 1,000) of the objects in a bucket with each request
  * Required parameter: `bucket_name`
  * Optional parameters: `prefix` (filter by prefix), `max_keys` (limit results)

* **GetObject**
  * Retrieves an object from MinIO
  * Required parameters: `bucket_name`, `object_name`

* **PutObject**
  * Uploads a file to MinIO bucket using fput method
  * Required parameters: `bucket_name`, `object_name`, `file_path`

### Client

The project includes multiple client implementations:

1. **Basic Client** - Simple client for direct interaction with the MinIO MCP server
2. **Anthropic Client** - Integration with Anthropic's Claude models for AI-powered interactions with MinIO

## Installation

1. Clone the repository:
```bash
git clone https://github.com/yourusername/minio-mcp.git
cd minio-mcp
```

2. Install dependencies using pip:
```bash
pip install -r requirements.txt
```

Or using uv:
```bash
uv pip install -r requirements.txt
```

## Environment Configuration

Create a `.env` file in the root directory with the following configuration:

```env
# MinIO Configuration
MINIO_ENDPOINT=play.min.io
MINIO_ACCESS_KEY=your_access_key
MINIO_SECRET_KEY=your_secret_key
MINIO_SECURE=true
MINIO_MAX_BUCKETS=5

# Server Configuration
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

# For Anthropic Client (if using)
ANTHROPIC_API_KEY=your_anthropic_api_key
```

## Usage

### Running the Server

The server can be run directly:

```bash
python src/minio_mcp_server/server.py
```

### Using the Basic Client

```python
from src.client import main
import asyncio

asyncio.run(main())
```

### Using the Anthropic Client

1. Configure the servers in `src/client/servers_config.json`:

```json
{
  "mcpServers": {
    "minio_service": {
      "command": "python",
      "args": ["path/to/minio_mcp_server/server.py"]
    }
  }
}
```

2. Run the client:

```bash
python src/client/mcp_anthropic_client.py
```

3. Interact with the assistant:
   - The assistant will automatically detect available tools
   - You can ask questions about your MinIO data
   - The assistant will use the appropriate tools to retrieve information

4. Exit the session:
   - Type `quit` or `exit` to end the session

## Integration with Claude Desktop

You can integrate this MCP server with Claude Desktop:

### Configuration

On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`  
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "minio-mcp": {
      "command": "python",
      "args": [
        "path/to/minio-mcp/src/minio_mcp_server/server.py"
      ]
    }
  }
}
```

## Development

### Project Structure

```
minio-mcp/
├── src/
│   ├── client/                  # Client implementations
│   │   ├── mcp_anthropic_client.py  # Anthropic integration
│   │   └── servers_config.json  # Server configuration
│   ├── minio_mcp_server/        # MCP server implementation
│   │   ├── resources/           # Resource implementations
│   │   │   └── minio_resource.py  # MinIO resource
│   │   └── server.py            # Main server implementation
│   ├── __init__.py
│   └── client.py                # Basic client implementation
├── LICENSE
├── pyproject.toml
├── README.md
└── requirements.txt
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black src/
isort src/
flake8 src/
```

## Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we recommend using the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector python path/to/minio-mcp/src/minio_mcp_server/server.py
```

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

## License

This project is licensed under the MIT License - see the LICENSE file for details.