This MCP server exposes a bridge between MCP-compatible clients and a MinIO object storage backend. It implements seven MCP tools organized into two domains: Bucket Management and Object Management. Bucket tools include listing buckets, retrieving bucket information, creating buckets with validation, and deleting buckets (empty or with contents). Object tools cover listing objects (with optional prefix filtering, recursive listing, and configurable limits), retrieving object metadata, and deleting objects (with optional version support for versioned objects). The server uses Async FastMCP under the hood and provides standardized, validated responses and error handling. To use it, deploy the server in your environment, configure MinIO connection details via environment variables, and connect your MCP client to the server using the MCP protocol. Typical client interactions include commands like listing all buckets, viewing bucket info, listing objects within a bucket, and inspecting or deleting specific objects. The project emphasizes modular design with dedicated BucketTools and ObjectTools components, making it straightforward to extend or customize operations for MinIO.

Prerequisites:

• Python 3.11 or higher
• A MinIO server (local or remote)
• uv (Python package manager for MCP) recommended

Installation steps:

1. Clone the repository: git clone <repository-url> cd minio-mcp-server

2. Install dependencies via uv: uv sync

3. Install the project in development mode: uv pip install -e .

4. Prepare environment file and MinIO configuration (see configuration section in README). Copy example env and adjust values as needed: cp .env.example .env

   Edit .env to set MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_SECURE, etc.

5. Run the server (example using uv): uv run python src/minio_mcp/server.py

   or test with MCP Inspector:

   uv run mcp src/minio_mcp/server.py

Note: The exact command may vary depending on how you package and run the server in your environment. The example above follows the guidance provided in the README for a Python/uv-based setup.

Tips and common issues:

• Ensure your MinIO server is reachable from the MCP server and that the endpoint, access key, and secret key are correctly configured in the environment (.env).
• The default MinIO security flag is true; set MINIO_SECURE=false for non-HTTPS connections in development.
• The server uses a modular architecture with BucketTools and ObjectTools; if you need to customize behavior, focus on these modules.
• For Claude Desktop integration, follow the example configuration provided in the README to wire the uv-based start command and environment variables.
• If you encounter authentication or connectivity errors, double-check network accessibility and that MINIO_ENDPOINT uses host:port format (e.g., localhost:9000).
• Tests and development guidance in the README rely on uv run pytest; use these commands to validate changes during development.