Team MCP Server

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