# 🧲 **Magg** - *The MCP Aggregator*

[//]: # ([![Tests]&#40;https://img.shields.io/github/actions/workflow/status/sitbon/magg/test.yml?style=flat-square&label=tests&#41;]&#40;https://github.com/sitbon/magg/actions/workflows/test.yml&#41;)
[![Python Version](https://img.shields.io/pypi/pyversions/magg?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/magg/)
[![PyPI Version](https://img.shields.io/pypi/v/magg?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/magg/)
[![GitHub Release](https://img.shields.io/github/v/release/sitbon/magg?style=flat-square&logo=github)](https://github.com/sitbon/magg/releases)
[![DeepWiki](https://img.shields.io/badge/DeepWiki-sitbon%2Fmagg-blue.svg?logo=data:image/png;base64, )](https://deepwiki.com/sitbon/magg)
[![Downloads](https://img.shields.io/pypi/dm/magg?style=flat-square)](https://pypistats.org/packages/magg)
<!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->

[![Tests](https://github.com/sitbon/magg/actions/workflows/test.yml/badge.svg)](https://github.com/sitbon/magg/actions/workflows/test.yml)
[![Docker](https://github.com/sitbon/magg/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/sitbon/magg/actions/workflows/docker-publish.yml)

A *[Model Context Protocol](https://modelcontextprotocol.io/)* server that manages, aggregates, and proxies other MCP servers, enabling LLMs to dynamically extend their own capabilities.

## What is Magg?

Magg is a meta-MCP server that acts as a central hub for managing multiple MCP servers. It provides tools that allow LLMs to:

- Search for new MCP servers and discover setup instructions
- Add and configure MCP servers dynamically
- Enable/disable servers on demand
- Aggregate tools from multiple servers under unified prefixes
- Persist configurations across sessions

Think of Magg as a "package manager for LLM tools" - it lets AI assistants install and manage their own capabilities at runtime.

## Features

- **Self-Service Tool Management**: LLMs can search for and add new MCP servers without human intervention.
- **Automatic Tool Proxying**: Tools from added servers are automatically exposed with configurable prefixes.
- **ProxyMCP Tool**: A built-in tool that proxies the MCP protocol to itself, for clients that don't support notifications or dynamic tool updates (which is most of them currently).
- **Smart Configuration**: Uses MCP sampling to intelligently configure servers from just a URL.
- **Persistent Configuration**: Maintains server configurations in `.magg/config.json`.
- **Multiple Transport Support**: Works with stdio, HTTP, and in-memory transports.
- **Bearer Token Authentication**: Optional RSA-based JWT authentication for secure HTTP access.
- **Docker Support**: Pre-built images for production, staging, and development workflows.
- **Health Monitoring**: Built-in `magg_status` and `magg_check` tools for server health checks.
- **Python 3.12+ Support**: Fully compatible with Python 3.12 and 3.13.

## Installation

### Prerequisites

- Python 3.12 or higher (3.13+ recommended)
- `uv` (recommended) - Install from [astral.sh/uv](https://astral.sh/uv)

### Quick Install (Recommended)

The easiest way to install Magg is as a tool using `uv`:

```bash
# Install Magg as a tool
uv tool install magg

# Run with stdio transport (for Claude Desktop, Cline, etc.)
magg serve

# Run with HTTP transport (for system-wide access)
magg serve --http
```

### Alternative: Run Directly from GitHub

You can also run Magg directly from GitHub without installing:

```bash
# Run with stdio transport
uvx --from git+https://github.com/sitbon/magg.git magg

# Run with HTTP transport
uvx --from git+https://github.com/sitbon/magg.git magg serve --http
```

### Local Development

For development, clone the repository and install in editable mode:

```bash
# Clone the repository
git clone https://github.com/sitbon/magg.git
cd magg

# Install in development mode with dev dependencies
uv sync --dev

# Or with poetry
poetry install --with dev

# Run the CLI
magg --help
```

### Docker

Magg is available as pre-built Docker images from GitHub Container Registry:

```bash
# Run production image (WARNING log level)
docker run -p 8000:8000 ghcr.io/sitbon/magg:latest

# Run with authentication (mount or set private key)
docker run -p 8000:8000 \
  -v ~/.ssh/magg:/home/magg/.ssh/magg:ro \
  ghcr.io/sitbon/magg:latest

# Or with environment variable
docker run -p 8000:8000 \
  -e MAGG_PRIVATE_KEY="$(cat ~/.ssh/magg/magg.key)" \
  ghcr.io/sitbon/magg:latest

# Run beta image (INFO log level)
docker run -p 8000:8000 ghcr.io/sitbon/magg:beta

# Run with custom config directory
docker run -p 8000:8000 \
  -v /path/to/config:/home/magg/.magg \
  ghcr.io/sitbon/magg:latest
```

#### Docker Image Strategy

Magg uses a multi-stage Docker build with three target stages:

- **`pro` (Production)**: Minimal image with WARNING log level, suitable for production deployments
- **`pre` (Pre-production)**: Same as production but with INFO log level for staging/testing
- **`dev` (Development)**: Includes development dependencies and DEBUG logging for troubleshooting

Images are automatically published to GitHub Container Registry with the following tags:

- **Version tags** (from main branch): `latest`, `1.2.3.4`, `1.2`
- **Branch tags** (from beta branch): `beta`, `beta-pre`, `beta-dev`
- **Python-specific dev tags**: `beta-dev-py3.12`, `beta-dev-py3.13`, etc.

#### Docker Compose

For easier management, use Docker Compose:

```bash
# Clone the repository
git clone https://github.com/sitbon/magg.git
cd magg

# Run production version
docker compose up magg

# Run staging version (on port 8001)
docker compose up magg-beta

# Run development version (on port 8008)
# This uses ./.magg/config.json for configuration
docker compose up magg-dev

# Build and run with custom registry
REGISTRY=my.registry.com docker compose build
REGISTRY=my.registry.com docker compose push
```

See `compose.yaml` and `.env.example` for configuration options.

## Usage

### Running Magg

Magg can run in two modes:

1. **Stdio Mode** (default) - For integration with Claude Desktop, Cline, Cursor, etc.:
   ```bash
   magg serve
   ```

2. **HTTP Mode** - For system-wide access or web integrations:
   ```bash
   magg serve --http --port 8000
   ```

### Available Tools

Once Magg is running, it exposes the following tools to LLMs:

- `magg_list_servers` - List all configured MCP servers
- `magg_add_server` - Add a new MCP server
- `magg_remove_server` - Remove a server
- `magg_enable_server` / `magg_disable_server` - Toggle server availability
- `magg_search_servers` - Search for MCP servers online
- `magg_list_tools` - List all available tools from all servers
- `magg_smart_configure` - Intelligently configure a server from a URL
- `magg_analyze_servers` - Analyze configured servers and suggest improvements
- `magg_status` - Get server and tool statistics
- `magg_check` - Health check servers with repair actions (report/remount/unmount/disable)

### Authentication

Magg supports optional bearer token authentication to secure access:

#### Quick Start

1. **Initialize authentication** (creates RSA keypair):
   ```bash
   magg auth init
   ```

2. **Generate a JWT token** for clients:
   ```bash
   # Generate token (displays on screen)
   magg auth token
   
   # Export as environment variable
   export MAGG_JWT=$(magg auth token -q)
   ```

3. **Connect with authentication**:
   - Using `MaggClient` (auto-loads from MAGG_JWT):
     ```python
     from magg.client import MaggClient
     
     async def main():
         async with MaggClient("http://localhost:8000/mcp") as client:
             tools = await client.list_tools()
     ```
   - Using FastMCP with explicit token:
     ```python
     from fastmcp import Client
     from fastmcp.client import BearerAuth
     
     jwt_token = "your-jwt-token-here"
     async with Client("http://localhost:8000/mcp", auth=BearerAuth(jwt_token)) as client:
         tools = await client.list_tools()
     ```

#### Key Management

- Keys are stored in `~/.ssh/magg/` by default
- Private key can be set via `MAGG_PRIVATE_KEY` environment variable
- To disable auth, remove keys or set non-existent `key_path` in `.magg/auth.json`

#### Authentication Commands

- `magg auth init` - Initialize authentication (generates RSA keypair)
- `magg auth status` - Check authentication configuration
- `magg auth token` - Generate JWT token
- `magg auth public-key` - Display public key (for verification)
- `magg auth private-key` - Display private key (for backup)

See [examples/authentication.py](examples/authentication.py) for more usage patterns.

### Configuration

Magg stores its configuration in `.magg/config.json` in your current working directory. This allows for project-specific tool configurations.

Example configuration:
```json
{
  "servers": {
    "calculator": {
      "name": "calculator",
      "source": "https://github.com/executeautomation/calculator-mcp",
      "command": "npx @executeautomation/calculator-mcp",
      "prefix": "calc",
      "enabled": true
    }
  }
}
```

### Adding Servers

Servers can be added in several ways:

1. **Using the LLM** (recommended):
   ```
   "Add the Playwright MCP server"
   "Search for and add a calculator tool"
   ```

2. **Manual configuration** via `magg_add_server`:
   ```
   name: playwright
   url: https://github.com/microsoft/playwright-mcp
   command: npx @playwright/mcp@latest
   prefix: pw
   ```

3. **Direct config editing**: Edit `.magg/config.json` directly

## Documentation

For more documentation, see [docs/](docs/index.md).
