MAGG

🧲 Magg - The MCP Aggregator

A Model Context Protocol 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.
• Dynamic Configuration Reloading: Automatically detects and applies config changes without restarting.
• 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.
• Real-time Messaging: Full support for MCP notifications and messages - receive tool/resource updates and progress notifications from backend servers.
• Python 3.12+ Support: Fully compatible with Python 3.12 and 3.13.
• Kit Management: Bundle related MCP servers into kits for easy loading/unloading as a group.

Installation

Prerequisites

• Python 3.12 or higher (3.13+ recommended)
• uv (recommended) - Install from astral.sh/uv

Quick Install (Recommended)

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

Alternative: Run Directly from GitHub

You can also run Magg directly from GitHub without installing:

Local Development

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

Docker

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

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, 1.2, dev, 1.2-dev, 1.2-dev-py3.12, etc.
• 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:

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.:
   magg serve
2. HTTP Mode - For system-wide access or web integrations:
   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)
• magg_reload_config - Reload configuration from disk and apply changes
• magg_load_kit - Load a kit and its servers into the configuration
• magg_unload_kit - Unload a kit and optionally its servers from the configuration
• magg_list_kits - List all available kits with their status
• magg_kit_info - Get detailed information about a specific kit

Authentication

Magg supports optional bearer token authentication to secure access:

Quick Start

1. Initialize authentication (creates RSA keypair):
   magg auth init
2. Generate a JWT token for clients:
   # 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):
     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:
     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 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.

Dynamic Configuration Reloading

Magg supports automatic configuration reloading without requiring a restart:

• Automatic file watching: Detects changes to config.json and reloads automatically (uses watchdog when available)
• SIGHUP signal: Send kill -HUP <pid> to trigger immediate reload (Unix-like systems)
• MCP tool: Use magg_reload_config tool from any MCP client
• Smart transitions: Only affected servers are restarted during reload

Configuration reload is enabled by default. You can control it with:

• MAGG_AUTO_RELOAD=false - Disable automatic reloading
• MAGG_RELOAD_POLL_INTERVAL=5.0 - Set polling interval in seconds (when watchdog unavailable)

See Configuration Reload Documentation for detailed information.

Example configuration:

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

Real-time Notifications with MaggClient

The MaggClient now supports real-time notifications from backend MCP servers:

See Messaging Documentation for advanced usage including custom message handlers.

Kit Management

Magg supports organizing related MCP servers into "kits" - bundles that can be loaded and unloaded as a group:

Kits are JSON files stored in ~/.magg/kit.d/ or .magg/kit.d/ that define a collection of related servers. See Kit Documentation for details on creating and managing kits.

Documentation

For more documentation, see docs/.