# 🧲 **Magg** - *The MCP Aggregator*
[//]: # ([](https://github.com/sitbon/magg/actions/workflows/test.yml))
[](https://pypi.org/project/magg/)
[](https://pypi.org/project/magg/)
[](https://github.com/sitbon/magg/releases)
[](https://deepwiki.com/sitbon/magg)
[](https://pypistats.org/packages/magg)
<!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->
[](https://github.com/sitbon/magg/actions/workflows/test.yml)
[](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.
- **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](docs/mbro.md) 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](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 (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:
```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 three 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
```
3. **Hybrid Mode** - Both stdio and HTTP simultaneously:
```bash
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:**
```bash
# Configure Claude Code to use Magg in hybrid mode
claude mcp add magg -- magg serve --hybrid --port 42000
```
**With mbro:**
```bash
# 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:
```bash
# 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](docs/mbro.md) for details.
### 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.
#### 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](docs/config-reload.md) 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 mode
- `MAGG_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:
```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
### Real-time Notifications with MaggClient
The `MaggClient` now supports real-time notifications from backend MCP servers:
```python
from magg import MaggClient, MaggMessageHandler
# Using callbacks
handler = MaggMessageHandler(
on_tool_list_changed=lambda n: print("Tools changed!"),
on_progress=lambda n: print(f"Progress: {n.params.progress}")
)
async with MaggClient("http://localhost:8000/mcp", message_handler=handler) as client:
# Client will receive notifications while connected
tools = await client.list_tools()
```
See [Messaging Documentation](docs/messaging.md) 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:
```bash
# List available kits
magg kit list
# Load a kit (adds all its servers)
magg kit load web-tools
# Unload a kit (removes servers only in that kit)
magg kit unload web-tools
# Get information about a kit
magg kit info web-tools
```
You can also manage kits programmatically through Magg's tools when connected via an MCP client:
- `magg_list_kits` - List all available kits
- `magg_load_kit` - Load a kit and its servers
- `magg_unload_kit` - Unload a kit
- `magg_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](docs/kits.md) for details on creating and managing kits.
### MBro Scripts
Automate common workflows with MBro scripts:
```bash
# Create a setup script
cat > setup.mbro <<EOF
# Connect to Magg and check status
connect magg magg serve
call magg_status
call magg_list_servers
# Add a new server if needed
call magg_add_server name=calculator source="npx -y @modelcontextprotocol/server-calculator"
EOF
# Run the script
mbro -x setup.mbro
```
## Documentation
For more documentation, see [docs/](docs/index.md).
## 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
* [DeepWiki](https://deepwiki.com/sitbon/magg) - AI-generated documentation
* [Glama.ai](https://glama.ai/mcp/servers/@sitbon/magg) - MCP server listing and hosting
### Awesome GitHub MCP Lists
* [@modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
* [@punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
* [@wong2/awesome-mcp-servers](https://github.com/wong2/awesome-mcp-servers)
Raw data
{
"_id": null,
"home_page": null,
"name": "magg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "agent, aggregator, ai, aiohttp, context, fastmcp, mcp, model, protocol, proxy, pydantic, pydantic-settings, rich",
"author": null,
"author_email": "Phillip Sitbon <phillip.sitbon@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/32/47/e4606a494731e7c4c4e61b27dd5262c976bae1d8097009dea254c6fe4bcd/magg-0.10.1.tar.gz",
"platform": null,
"description": "# \ud83e\uddf2 **Magg** - *The MCP Aggregator*\n\n[//]: # ([](https://github.com/sitbon/magg/actions/workflows/test.yml))\n[](https://pypi.org/project/magg/)\n[](https://pypi.org/project/magg/)\n[](https://github.com/sitbon/magg/releases)\n[](https://deepwiki.com/sitbon/magg)\n[](https://pypistats.org/packages/magg)\n<!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->\n\n[](https://github.com/sitbon/magg/actions/workflows/test.yml)\n[](https://github.com/sitbon/magg/actions/workflows/docker-publish.yml)\n\nA *[Model Context Protocol](https://modelcontextprotocol.io/)* server that manages, aggregates, and proxies other MCP servers, enabling LLMs to dynamically extend their own capabilities.\n\n## What is Magg?\n\nMagg is a meta-MCP server that acts as a central hub for managing multiple MCP servers. It provides tools that allow LLMs to:\n\n- Search for new MCP servers and discover setup instructions\n- Add and configure MCP servers dynamically\n- Enable/disable servers on demand\n- Aggregate tools from multiple servers under unified prefixes\n- Persist configurations across sessions\n\nThink of Magg as a \"package manager for LLM tools\" - it lets AI assistants install and manage their own capabilities at runtime.\n\n## Features\n\n- **Self-Service Tool Management**: LLMs can search for and add new MCP servers without human intervention.\n- **Dynamic Configuration Reloading**: Automatically detects and applies config changes without restarting.\n- **Automatic Tool Proxying**: Tools from added servers are automatically exposed with configurable prefixes.\n- **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).\n- **Smart Configuration**: Uses MCP sampling to intelligently configure servers from just a URL.\n- **Persistent Configuration**: Maintains server configurations in `.magg/config.json`.\n- **Multiple Transport Support**: Works with stdio, HTTP, and in-memory transports.\n- **Bearer Token Authentication**: Optional RSA-based JWT authentication for secure HTTP access.\n- **Docker Support**: Pre-built images for production, staging, and development workflows.\n- **Health Monitoring**: Built-in `magg_status` and `magg_check` tools for server health checks.\n- **Real-time Messaging**: Full support for MCP notifications and messages - receive tool/resource updates and progress notifications from backend servers.\n- **Python 3.12+ Support**: Fully compatible with Python 3.12 and 3.13.\n- **Kit Management**: Bundle related MCP servers into kits for easy loading/unloading as a group.\n- **MBro CLI**: Included [MCP Browser](docs/mbro.md) for interactive exploration and management of MCP servers, with script support for automation.\n\n## Installation\n\n### Prerequisites\n\n- Python 3.12 or higher (3.13+ recommended)\n- `uv` (recommended) - Install from [astral.sh/uv](https://astral.sh/uv)\n\n### Quick Install (Recommended)\n\nThe easiest way to install Magg is as a tool using `uv`:\n\n```bash\n# Install Magg as a tool\nuv tool install magg\n\n# Run with stdio transport (for Claude Desktop, Cline, etc.)\nmagg serve\n\n# Run with HTTP transport (for system-wide access)\nmagg serve --http\n```\n\n### Alternative: Run Directly from GitHub\n\nYou can also run Magg directly from GitHub without installing:\n\n```bash\n# Run with stdio transport\nuvx --from git+https://github.com/sitbon/magg.git magg\n\n# Run with HTTP transport\nuvx --from git+https://github.com/sitbon/magg.git magg serve --http\n```\n\n### Local Development\n\nFor development, clone the repository and install in editable mode:\n\n```bash\n# Clone the repository\ngit clone https://github.com/sitbon/magg.git\ncd magg\n\n# Install in development mode with dev dependencies\nuv sync --dev\n\n# Or with poetry\npoetry install --with dev\n\n# Run the CLI\nmagg --help\n```\n\n### Docker\n\nMagg is available as pre-built Docker images from GitHub Container Registry:\n\n```bash\n# Run production image (WARNING log level)\ndocker run -p 8000:8000 ghcr.io/sitbon/magg:latest\n\n# Run with authentication (mount or set private key)\ndocker run -p 8000:8000 \\\n -v ~/.ssh/magg:/home/magg/.ssh/magg:ro \\\n ghcr.io/sitbon/magg:latest\n\n# Or with environment variable\ndocker run -p 8000:8000 \\\n -e MAGG_PRIVATE_KEY=\"$(cat ~/.ssh/magg/magg.key)\" \\\n ghcr.io/sitbon/magg:latest\n\n# Run beta image (INFO log level)\ndocker run -p 8000:8000 ghcr.io/sitbon/magg:beta\n\n# Run with custom config directory\ndocker run -p 8000:8000 \\\n -v /path/to/config:/home/magg/.magg \\\n ghcr.io/sitbon/magg:latest\n```\n\n#### Docker Image Strategy\n\nMagg uses a multi-stage Docker build with three target stages:\n\n- **`pro` (Production)**: Minimal image with WARNING log level, suitable for production deployments\n- **`pre` (Pre-production)**: Same as production but with INFO log level for staging/testing (available but not published)\n- **`dev` (Development)**: Includes development dependencies and DEBUG logging for troubleshooting\n\nImages are automatically published to GitHub Container Registry with the following tags:\n\n- **Version tags** (from main branch): `1.2.3`, `1.2`, `dev`, `1.2-dev`, `1.2-dev-py3.12`, etc.\n- **Branch tags** (from beta branch): `beta`, `beta-dev`\n- **Python-specific dev tags**: `beta-dev-py3.12`, `beta-dev-py3.13`, etc.\n\n#### Docker Compose\n\nFor easier management, use Docker Compose:\n\n```bash\n# Clone the repository\ngit clone https://github.com/sitbon/magg.git\ncd magg\n\n# Run production version\ndocker compose up magg\n\n# Run staging version (on port 8001)\ndocker compose up magg-beta\n\n# Run development version (on port 8008)\n# This uses ./.magg/config.json for configuration\ndocker compose up magg-dev\n\n# Build and run with custom registry\nREGISTRY=my.registry.com docker compose build\nREGISTRY=my.registry.com docker compose push\n```\n\nSee `compose.yaml` and `.env.example` for configuration options.\n\n## Usage\n\n### Running Magg\n\nMagg can run in three modes:\n\n1. **Stdio Mode** (default) - For integration with Claude Desktop, Cline, Cursor, etc.:\n ```bash\n magg serve\n ```\n\n2. **HTTP Mode** - For system-wide access or web integrations:\n ```bash\n magg serve --http --port 8000\n ```\n\n3. **Hybrid Mode** - Both stdio and HTTP simultaneously:\n ```bash\n magg serve --hybrid\n magg serve --hybrid --port 8080 # Custom port\n ```\n \n This is particularly useful when you want to use Magg through an MCP client while also allowing HTTP access. For example:\n \n **With Claude Code:**\n ```bash\n # Configure Claude Code to use Magg in hybrid mode\n claude mcp add magg -- magg serve --hybrid --port 42000\n ```\n \n **With mbro:**\n ```bash\n # mbro hosts Magg and connects via stdio\n mbro connect magg \"magg serve --hybrid --port 8080\"\n \n # Other mbro instances can connect via HTTP\n mbro connect magg http://localhost:8080\n ```\n\n### Available Tools\n\nOnce Magg is running, it exposes the following tools to LLMs:\n\n- `magg_list_servers` - List all configured MCP servers\n- `magg_add_server` - Add a new MCP server\n- `magg_remove_server` - Remove a server\n- `magg_enable_server` / `magg_disable_server` - Toggle server availability\n- `magg_search_servers` - Search for MCP servers online\n- `magg_list_tools` - List all available tools from all servers\n- `magg_smart_configure` - Intelligently configure a server from a URL\n- `magg_analyze_servers` - Analyze configured servers and suggest improvements\n- `magg_status` - Get server and tool statistics\n- `magg_check` - Health check servers with repair actions (report/remount/unmount/disable)\n- `magg_reload_config` - Reload configuration from disk and apply changes\n- `magg_load_kit` - Load a kit and its servers into the configuration\n- `magg_unload_kit` - Unload a kit and optionally its servers from the configuration\n- `magg_list_kits` - List all available kits with their status\n- `magg_kit_info` - Get detailed information about a specific kit\n\n### Quick Inspection with MBro\n\nMagg 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:\n\n```bash\n# Connect mbro to a Magg instance via stdio (no HTTP server needed)\nmbro connect local-magg magg serve\n\n# Now inspect your Magg setup from the MCP client perspective\nmbro:local-magg> call magg_status\nmbro:local-magg> call magg_list_servers\n```\n\nMBro also supports:\n- **Scripts**: Create `.mbro` files with commands for automation\n- **Shell-style arguments**: Use `key=value` syntax instead of JSON\n- **Tab completion**: Rich parameter hints after connecting\n\nSee the [MBro Documentation](docs/mbro.md) for details.\n\n### Authentication\n\nMagg supports optional bearer token authentication to secure access:\n\n#### Quick Start\n\n1. **Initialize authentication** (creates RSA keypair):\n ```bash\n magg auth init\n ```\n\n2. **Generate a JWT token** for clients:\n ```bash\n # Generate token (displays on screen)\n magg auth token\n \n # Export as environment variable\n export MAGG_JWT=$(magg auth token -q)\n ```\n\n3. **Connect with authentication**:\n - Using `MaggClient` (auto-loads from MAGG_JWT):\n ```python\n from magg.client import MaggClient\n \n async def main():\n async with MaggClient(\"http://localhost:8000/mcp\") as client:\n tools = await client.list_tools()\n ```\n - Using FastMCP with explicit token:\n ```python\n from fastmcp import Client\n from fastmcp.client import BearerAuth\n \n jwt_token = \"your-jwt-token-here\"\n async with Client(\"http://localhost:8000/mcp\", auth=BearerAuth(jwt_token)) as client:\n tools = await client.list_tools()\n ```\n\n#### Key Management\n\n- Keys are stored in `~/.ssh/magg/` by default\n- Private key can be set via `MAGG_PRIVATE_KEY` environment variable\n- To disable auth, remove keys or set non-existent `key_path` in `.magg/auth.json`\n\n#### Authentication Commands\n\n- `magg auth init` - Initialize authentication (generates RSA keypair)\n- `magg auth status` - Check authentication configuration\n- `magg auth token` - Generate JWT token\n- `magg auth public-key` - Display public key (for verification)\n- `magg auth private-key` - Display private key (for backup)\n\nSee [examples/authentication.py](examples/authentication.py) for more usage patterns.\n\n### Configuration\n\nMagg stores its configuration in `.magg/config.json` in your current working directory. This allows for project-specific tool configurations.\n\n#### Dynamic Configuration Reloading\n\nMagg supports automatic configuration reloading without requiring a restart:\n\n- **Automatic file watching**: Detects changes to `config.json` and reloads automatically (uses watchdog when available)\n- **SIGHUP signal**: Send `kill -HUP <pid>` to trigger immediate reload (Unix-like systems)\n- **MCP tool**: Use `magg_reload_config` tool from any MCP client\n- **Smart transitions**: Only affected servers are restarted during reload\n\nConfiguration reload is enabled by default. You can control it with:\n- `MAGG_AUTO_RELOAD=false` - Disable automatic reloading\n- `MAGG_RELOAD_POLL_INTERVAL=5.0` - Set polling interval in seconds (when watchdog unavailable)\n\nSee [Configuration Reload Documentation](docs/config-reload.md) for detailed information.\n\n#### Environment Variables\n\nMagg supports several environment variables for configuration:\n- `MAGG_CONFIG_PATH` - Path to config file (default: `.magg/config.json`)\n- `MAGG_LOG_LEVEL` - Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)\n- `MAGG_STDERR_SHOW=1` - Show stderr output from subprocess MCP servers (default: suppressed)\n- `MAGG_AUTO_RELOAD` - Enable/disable config auto-reload (default: true)\n- `MAGG_RELOAD_POLL_INTERVAL` - Config polling interval in seconds (default: 1.0)\n- `MAGG_READ_ONLY=true` - Run in read-only mode\n- `MAGG_SELF_PREFIX` - Prefix for Magg tools (default: \"magg\"). Tools will be named as `{prefix}{sep}{tool}` (e.g., `magg_list_servers`)\n- `MAGG_PREFIX_SEP` - Separator between prefix and tool name (default: \"_\")\n\nExample configuration:\n```json\n{\n \"servers\": {\n \"calculator\": {\n \"name\": \"calculator\",\n \"source\": \"https://github.com/executeautomation/calculator-mcp\",\n \"command\": \"npx @executeautomation/calculator-mcp\",\n \"prefix\": \"calc\",\n \"enabled\": true\n }\n }\n}\n```\n\n### Adding Servers\n\nServers can be added in several ways:\n\n1. **Using the LLM** (recommended):\n ```\n \"Add the Playwright MCP server\"\n \"Search for and add a calculator tool\"\n ```\n\n2. **Manual configuration** via `magg_add_server`:\n ```\n name: playwright\n url: https://github.com/microsoft/playwright-mcp\n command: npx @playwright/mcp@latest\n prefix: pw\n ```\n\n3. **Direct config editing**: Edit `.magg/config.json` directly\n\n### Real-time Notifications with MaggClient\n\nThe `MaggClient` now supports real-time notifications from backend MCP servers:\n\n```python\nfrom magg import MaggClient, MaggMessageHandler\n\n# Using callbacks\nhandler = MaggMessageHandler(\n on_tool_list_changed=lambda n: print(\"Tools changed!\"),\n on_progress=lambda n: print(f\"Progress: {n.params.progress}\")\n)\n\nasync with MaggClient(\"http://localhost:8000/mcp\", message_handler=handler) as client:\n # Client will receive notifications while connected\n tools = await client.list_tools()\n```\n\nSee [Messaging Documentation](docs/messaging.md) for advanced usage including custom message handlers.\n\n### Kit Management\n\nMagg supports organizing related MCP servers into \"kits\" - bundles that can be loaded and unloaded as a group:\n\n```bash\n# List available kits\nmagg kit list\n\n# Load a kit (adds all its servers)\nmagg kit load web-tools\n\n# Unload a kit (removes servers only in that kit)\nmagg kit unload web-tools\n\n# Get information about a kit\nmagg kit info web-tools\n```\n\nYou can also manage kits programmatically through Magg's tools when connected via an MCP client:\n- `magg_list_kits` - List all available kits\n- `magg_load_kit` - Load a kit and its servers\n- `magg_unload_kit` - Unload a kit\n- `magg_kit_info` - Get detailed kit information\n\nKits are JSON files stored in `~/.magg/kit.d/` or `.magg/kit.d/` that define a collection of related servers. See [Kit Documentation](docs/kits.md) for details on creating and managing kits.\n\n### MBro Scripts\n\nAutomate common workflows with MBro scripts:\n\n```bash\n# Create a setup script\ncat > setup.mbro <<EOF\n# Connect to Magg and check status\nconnect magg magg serve\ncall magg_status\ncall magg_list_servers\n\n# Add a new server if needed\ncall magg_add_server name=calculator source=\"npx -y @modelcontextprotocol/server-calculator\"\nEOF\n\n# Run the script\nmbro -x setup.mbro\n```\n\n## Documentation\n\nFor more documentation, see [docs/](docs/index.md).\n\n## Appearances\n\nMagg appears in multiple locations. Please feel free to submit a PR to add more appearances below in alphabetical order.\n\n### Listing, Index, and other MCP Sites\n\n* [DeepWiki](https://deepwiki.com/sitbon/magg) - AI-generated documentation\n* [Glama.ai](https://glama.ai/mcp/servers/@sitbon/magg) - MCP server listing and hosting\n\n### Awesome GitHub MCP Lists\n\n* [@modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)\n* [@punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)\n* [@wong2/awesome-mcp-servers](https://github.com/wong2/awesome-mcp-servers)\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "MCP Aggregator",
"version": "0.10.1",
"project_urls": {
"Documentation": "https://github.com/sitbon/magg#readme",
"Homepage": "https://github.com/sitbon/magg",
"Issues": "https://github.com/sitbon/magg/issues",
"Release Notes": "https://github.com/sitbon/magg/releases",
"Repository": "https://github.com/sitbon/magg.git"
},
"split_keywords": [
"agent",
" aggregator",
" ai",
" aiohttp",
" context",
" fastmcp",
" mcp",
" model",
" protocol",
" proxy",
" pydantic",
" pydantic-settings",
" rich"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "33a43617f7e92221cec23a725e307dd74086c87800d78f822a4c27b242470551",
"md5": "46b331e28dd82ae2951b0f51ad1e5b0c",
"sha256": "35f014746a795f0700286890dfe066d932ccd88aa7672c0f07500df08351af50"
},
"downloads": -1,
"filename": "magg-0.10.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "46b331e28dd82ae2951b0f51ad1e5b0c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 135366,
"upload_time": "2025-08-07T01:41:06",
"upload_time_iso_8601": "2025-08-07T01:41:06.276062Z",
"url": "https://files.pythonhosted.org/packages/33/a4/3617f7e92221cec23a725e307dd74086c87800d78f822a4c27b242470551/magg-0.10.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3247e4606a494731e7c4c4e61b27dd5262c976bae1d8097009dea254c6fe4bcd",
"md5": "b50e40375005c52a04295b9f1e96d602",
"sha256": "9b773ac029e6ec814bee987b49244da30fb67b3dfbe6e6af489fc3edc63ce1f5"
},
"downloads": -1,
"filename": "magg-0.10.1.tar.gz",
"has_sig": false,
"md5_digest": "b50e40375005c52a04295b9f1e96d602",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 275612,
"upload_time": "2025-08-07T01:41:07",
"upload_time_iso_8601": "2025-08-07T01:41:07.597971Z",
"url": "https://files.pythonhosted.org/packages/32/47/e4606a494731e7c4c4e61b27dd5262c976bae1d8097009dea254c6fe4bcd/magg-0.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 01:41:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sitbon",
"github_project": "magg#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "magg"
}
JSON
