Which integrations are available for this server?

Provides analytics tools for querying S3 bucket operations data, including top buckets by operations, inbound traffic, and outbound traffic metrics stored in ClickHouse

How do I use Team MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Team MCP Server list all S3 buckets" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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