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:
- Basic Client - Simple client for direct interaction with the MinIO MCP server
- Anthropic Client - Integration with Anthropic's Claude models for AI-powered interactions with MinIO
Installation
- Clone the repository:
git clone https://github.com/yourusername/minio-mcp.git
cd minio-mcp
- Install dependencies using pip:
pip install -r requirements.txt
Or using uv:
uv pip install -r requirements.txt
Environment Configuration
Create a .env file in the root directory with the following configuration:
# 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:
python src/minio_mcp_server/server.py
Using the Basic Client
from src.client import main
import asyncio
asyncio.run(main())
Using the Anthropic Client
- Configure the servers in
src/client/servers_config.json:
{
"mcpServers": {
"minio_service": {
"command": "python",
"args": ["path/to/minio_mcp_server/server.py"]
}
}
}
- Run the client:
python src/client/mcp_anthropic_client.py
- 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
- 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
{
"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
pytest
Code Formatting
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:
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.
