Minio Python MCP

🚀 MinIO Model Context Protocol (MCP)

This project implements the Model Context Protocol (MCP) server and client for MinIO object storage, offering a standard way to interact with MinIO.

🚀 Quick Start

This project provides a standard approach to interact with MinIO through the implementation of the Model Context Protocol (MCP) server and client.

✨ Features

Server

Resources

The server provides MinIO data via resources and can access and offer:

• Text files (automatically detected based on file extensions)
• Binary files (treated as application/octet - stream)
• Contents of each bucket (displaying up to 1000 objects per bucket)

Tools

• List Buckets

  • Returns a list of all buckets owned by the authenticated sender who sent the request.
  • Optional parameters: start_after (for pagination), max_buckets (to limit the number of results).

• List Objects

  • Returns some or all (up to 1000) objects in a specific bucket, with a certain number of objects returned per request.
  • Required parameter: bucket_name
  • Optional parameters: prefix (to filter by prefix), max_keys (to limit the number of results).

• Get Object

  • Retrieves an object from MinIO.
  • Required parameters: bucket_name, object_name

• Upload Object

  • Uploads a file to a MinIO bucket using the fput method.
  • Required parameters: bucket_name, object_name, file_path

Client

This project includes multiple client implementations:

1. Basic Client - A simple client for direct interaction with the MinIO MCP server.
2. Anthropic Client - Integrated with Anthropic's Claude model, providing AI - driven MinIO interaction capabilities.

📦 Installation

1. Clone the repository:

git clone https://github.com/yourusername/minio-mcp.git
cd minio-mcp

2. Install dependencies using pip:

pip install -r requirements.txt

Or use uv:

uv pip install -r requirements.txt

📚 Documentation

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 the Anthropic Client (if used)
ANTHROPIC_API_KEY=your_api_key

Usage

Run the Server

To run the MCP server, execute the following command:

python -m minio_mcp_server.main

Basic Client

The basic client provides the following interfaces:

• list_buckets()
• list_objects(bucket_name, prefix=None, max_keys=1000)
• get_object(bucket_name, object_name)
• put_object(bucket_name, object_name, file_path)

Anthropic Client

To use the Anthropic client, first install the Anthropic library:

pip install anthropic

Then configure the environment variable ANTHROPIC_API_KEY and refer to the Anthropic documentation for its usage.

Development

Project Structure

minio_mcp/
├── server/
│   ├── main.py          # Main program of the MCP server
│   └── utils.py        # Helper functions and tools
├── client/
│   ├── basic_client.py  # Implementation of the basic client
│   └── anthropic_client.py  # Implementation of the Anthropic client
└── config/             # Configuration files and environment variable handling
    └── settings.py     # Application settings and configuration

Run Tests

To run tests for the MCP server, execute the following command:

python -m pytest tests/

Code Formatting

To maintain code consistency and readability, we use the following tools:

• black to format the code
• isort to arrange import statements
• flake8 to check code style and errors

Install these tools:

pip install black isort flake8

Run formatting and checks:

black .
isort .
flake8

Debugging

Since the MCP server runs through standard input/output, 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

After starting, the inspector will display a URL that you can access in your browser to start debugging.

📄 License

This project is released under the MIT License - see the LICENSE file for details.