MAGG functions as a meta-MCP server that aggregates and manages multiple MCP servers, enabling LLMs to dynamically extend their capabilities.
- Dynamic Server Management: Add, remove, enable, and disable MCP servers.
- Tool Aggregation & Proxying: Access tools, resources, and prompts from multiple MCP servers through a unified interface.
- Intelligent Configuration: Configure and add servers from URLs using LLM sampling.
- Health Monitoring: Check server health, handle unresponsive servers, and view statistics.
- Discovery: Search for and discover new MCP servers online.
- Customization: Assign prefixes to tools for organized access and reload configurations dynamically.
- Authentication Support: Secure access with optional RSA-based JWT authentication.
Provides ability to discover and integrate MCP servers hosted on GitHub repositories, fetching setup instructions and configuration details directly from source.
Enables installation and management of Python-based MCP servers published on PyPI, with version tracking and dependency management.
Supports Python-based MCP servers with automatic configuration and tool proxying capabilities.
🧲 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
andmagg_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
:
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 deploymentspre
(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:
See compose.yaml
and .env.example
for configuration options.
Usage
Running Magg
Magg can run in three modes:
- Stdio Mode (default) - For integration with Claude Desktop, Cline, Cursor, etc.:
- HTTP Mode - For system-wide access or web integrations:
- Hybrid Mode - Both stdio and HTTP simultaneously:This is particularly useful when you want to use Magg through an MCP client while also allowing HTTP access. For example:With Claude Code:With mbro:
Available Tools
Once Magg is running, it exposes the following tools to LLMs:
magg_list_servers
- List all configured MCP serversmagg_add_server
- Add a new MCP servermagg_remove_server
- Remove a servermagg_enable_server
/magg_disable_server
- Toggle server availabilitymagg_search_servers
- Search for MCP servers onlinemagg_list_tools
- List all available tools from all serversmagg_smart_configure
- Intelligently configure a server from a URLmagg_analyze_servers
- Analyze configured servers and suggest improvementsmagg_status
- Get server and tool statisticsmagg_check
- Health check servers with repair actions (report/remount/unmount/disable)magg_reload_config
- Reload configuration from disk and apply changesmagg_load_kit
- Load a kit and its servers into the configurationmagg_unload_kit
- Unload a kit and optionally its servers from the configurationmagg_list_kits
- List all available kits with their statusmagg_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:
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
- Initialize authentication (creates RSA keypair):
- Generate a JWT token for clients:
- Connect with authentication:
- Using
MaggClient
(auto-loads from MAGG_JWT): - Using FastMCP with explicit token:
- Using
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 configurationmagg auth token
- Generate JWT tokenmagg 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 reloadingMAGG_RELOAD_POLL_INTERVAL=5.0
- Set polling interval in seconds (when watchdog unavailable)
See Configuration Reload Documentation for detailed information.
Environment Variables
Magg supports several environment variables for configuration:
MAGG_CONFIG_PATH
- Path to config file (default:.magg/config.json
)MAGG_LOG_LEVEL
- Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)MAGG_STDERR_SHOW=1
- Show stderr output from subprocess MCP servers (default: suppressed)MAGG_AUTO_RELOAD
- Enable/disable config auto-reload (default: true)MAGG_RELOAD_POLL_INTERVAL
- Config polling interval in seconds (default: 1.0)MAGG_READ_ONLY=true
- Run in read-only modeMAGG_SELF_PREFIX
- Prefix for Magg tools (default: "magg"). Tools will be named as{prefix}{sep}{tool}
(e.g.,magg_list_servers
)MAGG_PREFIX_SEP
- Separator between prefix and tool name (default: "_")
Example configuration:
Adding Servers
Servers can be added in several ways:
- Using the LLM (recommended):
- Manual configuration via
magg_add_server
: - 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:
You can also manage kits programmatically through Magg's tools when connected via an MCP client:
magg_list_kits
- List all available kitsmagg_load_kit
- Load a kit and its serversmagg_unload_kit
- Unload a kitmagg_kit_info
- Get detailed kit information
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.
MBro Scripts
Automate common workflows with MBro scripts:
Documentation
For more documentation, see docs/.
Appearances
Magg appears in multiple locations. Please feel free to submit a PR to add more appearances below in alphabetical order.
Listing, Index, and other MCP Sites
Awesome GitHub MCP Lists
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A meta-MCP server that manages and aggregates other MCP servers, enabling LLMs to dynamically extend their own capabilities by searching for, adding, and configuring tool servers.
Related MCP Servers
- AsecurityAlicenseAqualityA proxy server that unifies multiple MCP servers, enabling seamless tool, prompt, and resource management via the MetaMCP App.Last updated -453141TypeScriptApache 2.0
- AsecurityAlicenseAqualityAn MCP server that provides LLMs access to other LLMsLast updated -442557JavaScriptMIT License
- AsecurityFlicenseAqualityAn MCP server that allows users to create custom tools on the fly by stitching together actions from multiple MCP tools into reusable routines.Last updated -4211TypeScript
- -securityAlicense-qualityA Meta-MCP Server that acts as a tool discovery service, helping AI assistants find appropriate MCP servers from a database of 800+ servers when they need capabilities that aren't currently available.Last updated -4PythonMIT License