Back to MCP Servers

Magg

Magg: A meta-MCP server that acts as a universal hub, allowing LLMs to autonomously discover, install, and orchestrate multiple MCP servers - essentially giving AI assistants the power to extend their own capabilities on-demand.

aggregatorsaillm
By sitbon
13523Updated 2 days agoPythonAGPL-3.0

Installation

npx -y magg

Configuration

{
  "mcpServers": {
    "magg": {
      "command": "npx",
      "args": ["-y", "magg"]
    }
  }
}

How to use

  1. Run the installation command above (if needed)
  2. Open your Claude Code settings file (~/.claude/settings.json)
  3. Add the configuration to the mcpServers section
  4. Restart Claude Code to apply changes

README

View on GitHub

🧲 Magg - The MCP Aggregator

Python Version PyPI Version GitHub Release DeepWiki Downloads

<!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->

Tests Docker

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.
  • MBro CLI: Included MCP Browser for interactive exploration and management of MCP servers, with script support for automation.

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:

# 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:

# 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:

# 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:

# 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 (available but not published)
  • 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): 1.2.3, 1.2, dev, 1.2-dev, 1.2-dev-py3.12, etc.
  • Branch tags (from beta branch): beta, beta-dev
  • Python-specific dev tags: beta-dev-py3.12, beta-dev-py3.13, etc.

Docker Compose

For easier management, use Docker Compose:

# 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 three 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

  3. Hybrid Mode - Both stdio and HTTP simultaneously:

    magg serve --hybrid
magg serve --hybrid --port 8080  # Custom port

    This is particularly useful when you want to use Magg through an MCP client while also allowing HTTP access. For example:

    With Claude Code:

    # Configure Claude Code to use Magg in hybrid mode
claude mcp add magg -- magg serve --hybrid --port 42000

    With mbro:

    # mbro hosts Magg and connects via stdio
mbro connect magg "magg serve --hybrid --port 8080"

# Other mbro instances can connect via HTTP
mbro connect magg http://localhost:8080

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

Quick Inspection with MBro

Magg includes the mbro (MCP Browser) CLI tool for interactive exploration. A unique feature is the ability to connect to Magg in stdio mode for quick inspection:

# Connect mbro to a Magg instance via stdio (no HTTP server needed)
mbro connect local-magg magg serve

# Now inspect your Magg setup from the MCP client perspective
mbro:local-magg> call magg_status
mbro:local-magg> call magg_list_servers

MBro also supports:

  • Scripts: Create .mbro files with commands for automation
  • Shell-style arguments: Use key=value syntax instead of JSON
  • Tab completion: Rich parameter hints after connecting

See the MBro Documentation for details.

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
  • `mag

…

View source on GitHub

You might also like

OpenAI Server
MCP Servers
Agenium
MCP Servers
Elisym
MCP Servers