S3 Butler

A Model Context Protocol (MCP) server that provides tools for S3 bucket management, IAM policy inspection, and ClickHouse analytics.

Quick Start

# 1. Clone the repository git clone <your-repo-url> cd mcp-server # 2. Install uv (Python package manager) curl -LsSf https://astral.sh/uv/install.sh | sh # 3. Set up environment variables cp .env.example .env # Edit .env with your credentials (see Environment Setup below) # 4. Install dependencies uv sync # 5. Run the server uv run python src/server.py

Your MCP server is now running at http://localhost:8000/mcp 🎉

Environment Setup

Create a .env file with your credentials:

# Server Configuration MCP_HOST=0.0.0.0 MCP_PORT=8000 MCP_PATH=/mcp # S3/IAM Configuration (Required) S3_ENDPOINT=http://127.0.0.1:8000 # Your S3 endpoint S3_ACCESS_KEY=your_access_key # Your S3 access key S3_SECRET_KEY=your_secret_key # Your S3 secret key IAM_ENDPOINT=http://127.0.0.1:8600 # Your IAM endpoint # ClickHouse Configuration (Optional - for analytics) CLICKHOUSE_HOST=localhost # Leave blank to disable ClickHouse CLICKHOUSE_USER= # Optional CLICKHOUSE_PASSWORD= # Optional # ngrok Configuration (Optional - for remote access) NGROK_AUTH_TOKEN= # Get from https://dashboard.ngrok.com

Available Tools

The server provides these MCP tools:

get_team_name - Returns the team name
list_buckets - Lists all S3 buckets
get_iam_policies_for_bucket - Shows IAM policies for a specific bucket
get_top_buckets_by_operations - Analytics: most active buckets (requires ClickHouse)
get_top_buckets_by_inbound_traffic - Analytics: buckets with most uploads (requires ClickHouse)
get_top_buckets_by_outbound_traffic - Analytics: buckets with most downloads (requires ClickHouse)

Testing Your Server

Option 1: MCP Inspector (Recommended)

# Install MCP Inspector npm install -g @modelcontextprotocol/inspector # Start the inspector npx @modelcontextprotocol/inspector http://localhost:8000/mcp # Open http://localhost:5173 in your browser

Option 2: Test Scripts

# Test all tools uv run python test_client.py # Test list_buckets specifically uv run python test_list_buckets.py

Remote Access with ngrok

To access your server remotely:

# Run server with ngrok tunnel uv run python scripts/run_with_ngrok.py # The script will display your public URL

Development

Project Structure

mcp-server/ ├── src/ │ ├── server.py # Main MCP server │ ├── s3.py # S3/IAM utilities │ └── clickhouse_config.py # ClickHouse configuration ├── scripts/ │ └── run_with_ngrok.py # ngrok launcher ├── .env # Your configuration (create from .env.example) └── test_*.py # Test scripts

Adding New Tools

Edit src/server.py and add your tool:

@mcp.tool() def your_new_tool(param: str) -> str: """Description of your tool""" return f"Result for {param}"

Code Quality

# Format code uv run black src/ --line-length 100 # Lint uv run ruff src/ # Type check uv run mypy src/

Troubleshooting

Server won't start

Check Python version: python --version (needs 3.10+)
Verify .env file exists and has correct credentials
Check if port 8000 is already in use

Can't connect to S3/IAM

Verify S3_ENDPOINT and IAM_ENDPOINT are correct
Check S3_ACCESS_KEY and S3_SECRET_KEY are valid
Test connection: uv run python test_list_buckets.py

ClickHouse tools not showing

Set CLICKHOUSE_HOST in .env
Verify ClickHouse is running and accessible
Check logs for connection errors

Team MCP Server