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 datesget_bucket_info: Get detailed bucket information (metadata, policies, object count, total size, encryption)create_bucket: Create new buckets with name validation and existence checksdelete_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
- 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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass and code quality checks succeed
- Submit a pull request
Support
For issues and questions, please check the documentation or open an issue in the repository.