MinIO Model-Context Protocol (MCP) Server

# 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.