Content
# MinIO MCP Server
A Model Context Protocol (MCP) server that provides a bridge between MCP-compatible clients and MinIO object storage. This server exposes MinIO operations as MCP tools for seamless bucket management and object operations.
## Features
- **7 MCP Tools** organized by domain for comprehensive MinIO operations:
### Bucket Management
- `list_buckets`: List all available buckets with creation dates
- `get_bucket_info`: Get detailed bucket information (metadata, policies, object count, total size, encryption)
- `create_bucket`: Create new buckets with name validation and existence checks
- `delete_bucket`: Delete buckets (empty only) or force delete with all contents
### Object Management
- `list_objects`: List objects with filtering (prefix, recursive) and configurable limits (default 25)
- `get_object_info`: Get detailed object metadata (size, content-type, etag, version info, custom metadata)
- `delete_object`: Delete objects from buckets with optional version support for versioned objects
### Key Features
- **FastMCP Integration**: Built on FastMCP framework for robust MCP protocol support
- **Comprehensive Validation**: Input validation, error handling with appropriate HTTP status codes (400, 404, 409, 500)
- **Async Architecture**: Full async/await support for MCP protocol compliance
- **Modular Design**: Separated concerns with BucketTools and ObjectTools classes
- **Extensive Testing**: 100% test coverage with advanced mocking techniques
- **Standardized Responses**: Consistent error handling via TextContent entity
## Quick Start
### Prerequisites
- Python 3.11 or higher
- MinIO server (local or remote)
- UV package manager (recommended)
### Installation
```bash
# Clone the repository
git clone <repository-url>
cd minio-mcp-server
# Install dependencies
uv sync
# Install in development mode
uv pip install -e .
```
### Configuration
1. Copy the example environment file:
```bash
cp .env.example .env
```
2. Configure your MinIO connection in `.env`:
```env
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_SECURE=false
MINIO_LOG_LEVEL=INFO
```
### Running the Server
```bash
# Start the MCP server (stdio transport for Claude Desktop)
uv run python src/minio_mcp/server.py
# Test with MCP Inspector (interactive testing)
uv run mcp src/minio_mcp/server.py
# Alternative: Direct python execution
cd src/minio_mcp
python server.py
```
## Using with Claude Desktop
To connect this MCP server with Claude Desktop:
### 1. Configure Claude Desktop
Edit your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
Add this configuration (adjust paths for your system):
```json
{
"mcpServers": {
"minio-mcp-server": {
"command": "/Users/your_username/.local/bin/uv",
"args": [
"--directory",
"/path/to/your/minio-mcp-server",
"run",
"python",
"src/minio_mcp/server.py"
],
"env": {
"MINIO_ENDPOINT": "localhost:9000",
"MINIO_ACCESS_KEY": "minioadmin",
"MINIO_SECRET_KEY": "minioadmin",
"MINIO_SECURE": "false"
}
}
}
}
```
### 2. Restart Claude Desktop
After saving the configuration, completely restart Claude Desktop.
### 3. Test the Connection
Try commands like:
- "List all buckets in MinIO"
- "Show me information about the 'my-bucket' bucket"
- "List the first 10 objects in 'my-bucket'"
- "Get information about 'file.txt' in 'my-bucket'"
- "Delete 'old-file.txt' from 'my-bucket'"
## Architecture
### Core Components
- **FastMCP Server** (`server.py`): Main MCP protocol handler using FastMCP framework
- **MinioClient** (`infrastructure/minio_client.py`): Infrastructure layer with MinIO client management and configuration
- **BucketTools** (`tools/bucket_tools.py`): Business logic for bucket operations with validation and error handling
- **ObjectTools** (`tools/object_tools.py`): Business logic for object operations with comprehensive metadata extraction
- **TextContent** (`tools/entities.py`): Standardized response entity for consistent error handling
### Data Flow
```
MCP Client → FastMCP Server → BucketTools/ObjectTools → MinioClient → MinIO Server
```
## Configuration Options
| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `MINIO_ENDPOINT` | MinIO server endpoint | Required |
| `MINIO_ACCESS_KEY` | Access key for authentication | Required |
| `MINIO_SECRET_KEY` | Secret key for authentication | Required |
| `MINIO_SECURE` | Use HTTPS (true/false) | `true` |
| `MINIO_LOG_LEVEL` | Logging level (DEBUG/INFO/WARNING/ERROR) | `INFO` |
| `MINIO_MAX_OBJECTS_LIST` | Maximum objects per list operation | `25` |
## Development
### Setting up a Test MinIO Server
```bash
docker run -p 9000:9000 -p 9001:9001 \
--name minio-test \
-e "MINIO_ROOT_USER=minioadmin" \
-e "MINIO_ROOT_PASSWORD=minioadmin" \
quay.io/minio/minio server /data --console-address ":9001"
```
### Running Tests
```bash
# Run all tests
uv run pytest
# Run with coverage report
uv run pytest --cov=src/minio_mcp --cov-report=html
# Run specific test files
uv run pytest tests/tools/test_bucket_tools.py -v
uv run pytest tests/tools/test_object_tools.py -v
uv run pytest tests/infrastructure/test_minio_client.py -v
# Test specific functionality
uv run pytest -k "test_create_bucket" -v
```
### Code Quality
```bash
# Lint and format check
uv run ruff check src tests
# Auto-format code
uv run ruff format src tests
# Type checking
uv run mypy src
```
## License
[Add your license here]
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass and code quality checks succeed
6. Submit a pull request
## Support
For issues and questions, please check the documentation or open an issue in the repository.
