Magg

🧲 Magg - MCP アグリゲーター

LLM が自身の機能を動的に拡張できるよう、ほかの MCP サーバーを管理、集約、プロキシする Model Context Protocol サーバーです。

Magg とは？

Magg は、複数の MCP サーバーを管理するための中央ハブとして機能するメタ MCP サーバーです。LLM が次の操作を行えるツールを提供します。

• 新しい MCP サーバーを検索し、セットアップ手順を見つける
• MCP サーバーを動的に追加、設定する
• 必要に応じてサーバーを有効化／無効化する
• 複数のサーバーのツールを統一されたプレフィックスのもとに集約する
• セッションをまたいで設定を保持する

Magg は「LLM ツール向けのパッケージマネージャー」のようなものです。AI アシスタントが実行時に自身の機能をインストールし、管理できるようにします。

特長

• セルフサービスのツール管理：LLM は、人の介入なしに MCP サーバーを検索して追加できます。
• 動的な設定の再読み込み：再起動せずに設定の変更を自動で検出し、適用します。
• 自動ツールプロキシ：追加したサーバーのツールは、設定可能なプレフィックスを付けて自動的に公開されます。
• ProxyMCP ツール：MCP プロトコルを自身にプロキシする組み込みツールです。通知や動的なツールの更新に対応していないクライアント（現在は大半が該当します）で使用できます。
• スマートな設定：MCP サンプリングを使用し、URL だけからサーバーをインテリジェントに設定します。
• 永続的な設定：サーバーの設定を .magg/config.json に保持します。
• 複数のトランスポートに対応：stdio、HTTP、インメモリのトランスポートで動作します。
• ベアラートークン認証：安全な HTTP アクセスのための、RSA ベースの JWT 認証を任意で使用できます。
• Docker に対応：本番、ステージング、開発のワークフロー向けに、ビルド済みイメージを利用できます。
• ヘルスモニタリング：サーバーのヘルスチェック用に、組み込みの magg_status および magg_check ツールを提供します。
• リアルタイムメッセージング：MCP の通知とメッセージを完全にサポートし、バックエンドサーバーからツールやリソースの更新、進捗通知を受信します。
• Python 3.12 以降に対応：Python 3.12 および 3.13 と完全に互換性があります。
• キット管理：関連する MCP サーバーをキットにまとめ、グループ単位で簡単に読み込み、読み込み解除できます。
• MBro CLI：MCP サーバーを対話形式で探索、管理できるMCP Browserを同梱しています。自動化用のスクリプトにも対応しています。

インストール

前提条件

• Python 3.12 以降（3.13 以降を推奨）
• uv（推奨） - astral.sh/uv からインストール

クイックインストール（推奨）

Magg をインストールする最も簡単な方法は、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

代替方法：GitHub から直接実行

インストールせずに GitHub から Magg を直接実行することもできます。

# 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

ローカル開発

開発する場合は、リポジトリをクローンし、編集可能モードでインストールします。

# 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 は GitHub Container Registry からビルド済みの Docker イメージとして利用できます。

# 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 イメージの戦略

Magg は、3 つのターゲットステージを含むマルチステージ Docker ビルドを使用します。

• pro（本番）：WARNING ログレベルの最小限のイメージで、本番環境へのデプロイに適しています
• pre（本番前）：本番用と同じですが、ステージング／テスト用に INFO ログレベルを使用します（利用可能ですが、公開されていません）
• dev（開発）：トラブルシューティング用の開発依存関係と DEBUG ログを含みます

イメージは、以下のタグを付けて GitHub Container Registry に自動で公開されます。

• バージョンタグ（main ブランチから）：1.2.3、1.2、dev、1.2-dev、1.2-dev-py3.12 など
• ブランチタグ（beta ブランチから）：beta、beta-dev
• Python バージョン固有の開発タグ：beta-dev-py3.12、beta-dev-py3.13 など

プルリクエストではイメージのビルドとテストが行われますが、メンテナーが push-image ラベルを追加しない限り、公開されません。このラベルを追加すると、一時的な pr-NN／pr-NN-dev タグが公開されます（同一リポジトリ内のプルリクエストのみ）。一時的な pr-* タグとタグのないマニフェストは毎週クリーンアップされます。バージョンタグは 永久に保持されるため、タグを固定したデプロイには影響しません。

Docker Compose

管理を簡単にするには、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

設定オプションについては、compose.yaml と .env.example を参照してください。

使用方法

Magg の実行

Magg は 3 つのモードで実行できます。

1. Stdio モード（デフォルト）- Claude Desktop、Cline、Cursor などとの統合向け：

   magg serve
   

2. HTTP モード - システム全体からのアクセスやウェブ統合向け：

   magg serve --http --port 8000
   

3. ハイブリッドモード - stdio と HTTP を同時に使用します：

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

   MCP クライアント経由で Magg を使用しながら、HTTP アクセスも可能にしたい場合に特に便利です。たとえば、以下のように使用できます。

   Claude Code の場合：

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

   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
   

利用可能なツール

Magg の実行中、LLM に次のツールを公開します。

• magg_list_servers - 設定済みのすべての MCP サーバーを一覧表示します
• magg_add_server - 新しい MCP サーバーを追加します
• magg_remove_server - サーバーを削除します
• magg_enable_server / magg_disable_server - サーバーの利用可否を切り替えます
• magg_search_servers - オンラインで MCP サーバーを検索します
• magg_list_tools - すべてのサーバーで利用可能なツールを一覧表示します
• magg_smart_configure - URL からサーバーをインテリジェントに設定します
• magg_analyze_servers - 設定済みサーバーを分析し、改善案を提案します
• magg_status - サーバーとツールの統計情報を取得します
• magg_check - 修復アクション（報告／再マウント／マウント解除／無効化）を伴うサーバーのヘルスチェックを実行します
• magg_reload_config - ディスクから設定を再読み込みし、変更を適用します
• magg_load_kit - キットとそのサーバーを設定に読み込みます
• magg_unload_kit - キットと、必要に応じてそのサーバーを設定から読み込み解除します
• magg_list_kits - 利用可能なすべてのキットとその状態を一覧表示します
• magg_kit_info - 特定のキットの詳細情報を取得します

MBro による簡単な確認

Magg には、インタラクティブな探索に使える mbro（MCP ブラウザー）CLI ツールが含まれています。独自の機能として、すばやく確認できるよう stdio モードで Magg に接続できます。

# 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 は次の機能もサポートしています。

• スクリプト：自動化用のコマンドを記述した .mbro ファイルを作成します
• シェルスタイルの引数：JSON の代わりに key=value 構文を使用します
• タブ補完：接続後に詳細なパラメーターのヒントを表示します

詳細はMBro ドキュメントをご覧ください。

認証

Magg は、アクセスを保護するためのオプションのベアラートークン認証をサポートしています。

クイックスタート

1. 認証を初期化します（RSA キーペアを作成します）。

   magg auth init
   

2. クライアント用の JWT トークンを生成します。

   # Generate token (displays on screen)
   magg auth token
   
   # Export as environment variable
   export MAGG_JWT=$(magg auth token -q)
   

3. 認証を使用して接続します。

   • MaggClient を使用する場合（MAGG_JWT から自動的に読み込みます）。

     from magg.client import MaggClient
     
     async def main():
         async with MaggClient("http://localhost:8000/mcp") as client:
             tools = await client.list_tools()
     

   • 明示的なトークンを指定して FastMCP を使用する場合。

     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()
     

キー管理

• キーはデフォルトで ~/.ssh/magg/ に保存されます
• 秘密鍵は MAGG_PRIVATE_KEY 環境変数で設定できます
• 認証を無効にするには、キーを削除するか、.magg/auth.json で存在しない key_path を設定します

認証コマンド

• magg auth init - 認証を初期化します（RSA キーペアを生成します）
• magg auth status - 認証設定を確認します
• magg auth token - JWT トークンを生成します
• magg auth public-key - 公開鍵を表示します（検証用）
• magg auth private-key - 秘密鍵を表示します（バックアップ用）

使用例の詳細は、examples/authentication.pyをご覧ください。

設定

Magg は、現在の作業ディレクトリにある .magg/config.json に設定を保存します。これにより、プロジェクトごとにツールの設定を管理できます。

動的な設定の再読み込み

Magg は、再起動せずに設定を自動的に再読み込みできます。

• ファイルの自動監視：config.json の変更を検出して自動的に再読み込みします（利用可能な場合は watchdog を使用します）
• SIGHUP シグナル：kill -HUP <pid> を送信して即時に再読み込みを実行します（Unix 系システム）
• MCP ツール：任意の MCP クライアントから magg_reload_config ツールを使用します
• スマートな移行：再読み込み時には、影響を受けるサーバーのみを再起動します

設定の再読み込みはデフォルトで有効です。次の設定で制御できます。

• MAGG_AUTO_RELOAD=false - 自動再読み込みを無効にします
• MAGG_RELOAD_POLL_INTERVAL=5.0 - ポーリング間隔を秒単位で設定します（watchdog が利用できない場合）

詳しくは設定の再読み込みに関するドキュメントをご覧ください。

環境変数

Magg は、設定に使用できる複数の環境変数をサポートしています。

• MAGG_CONFIG_PATH - 設定ファイルのパス（デフォルト：.magg/config.json）
• MAGG_LOG_LEVEL - ログレベル：DEBUG、INFO、WARNING、ERROR、CRITICAL（デフォルト：INFO）
• MAGG_STDERR_SHOW=1 - サブプロセスの MCP サーバーからの stderr 出力を表示します（デフォルト：非表示）
• MAGG_AUTO_RELOAD - 設定の自動再読み込みを有効／無効にします（デフォルト：true）
• MAGG_RELOAD_POLL_INTERVAL - 設定を確認する間隔（秒）（デフォルト：1.0）
• MAGG_READ_ONLY=true - 読み取り専用モードで実行します
• MAGG_SELF_PREFIX - Magg のツールに付けるプレフィックス（デフォルト："magg"）。ツール名は {prefix}{sep}{tool} になります（例：magg_list_servers）
• MAGG_PREFIX_SEP - Magg のプレフィックスとツール名の間の区切り文字（デフォルト："_"）。バックエンドサーバーのツールでは常に _ が使われます
• MAGG_BACKEND_INIT_TIMEOUT - バックエンドサーバーを起動してから、起動を断念するまでの待機時間（秒）（デフォルト：30、0 は無期限に待機）

設定例：

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

サーバーの追加

サーバーは、いくつかの方法で追加できます。

1. LLM を使用する（推奨）：

   "Add the Playwright MCP server"
   "Search for and add a calculator tool"
   

2. magg_add_server による手動設定：

   name: playwright
   url: https://github.com/microsoft/playwright-mcp
   command: npx @playwright/mcp@latest
   prefix: pw
   

3. magg server CLI（下記を参照）

4. 設定を直接編集する：.magg/config.json を直接編集します

CLI からのサーバー管理

サーバーとキットの設定は、コマンドラインからすべて管理できます。MCP クライアントや実行中のサーバーは必要ありません。CLI は .magg/config.json を直接編集し、実行中の Magg インスタンスは設定の再読み込みによって変更を自動的に反映します。 （magg_search_servers、magg_check、magg_smart_configure など、稼働中のサーバーを必要とするツールは、mbro などの MCP クライアントから引き続き利用できます。）

# List servers (human-readable, or JSON on stdout for scripting)
magg server list
magg server list --json

# Add a server
magg server add playwright https://github.com/microsoft/playwright-mcp \
    --command "npx @playwright/mcp@latest" --prefix pw

# Add a server without enabling it, with transport options
magg server add web https://example.com/web --uri http://localhost:9000/mcp \
    --transport '{"keep_alive": false}' --disable

# Update an existing server (pass '' to clear an optional field)
magg server update playwright --prefix play --notes "Browser automation"
magg server update playwright --command "npx @playwright/mcp@next"
magg server update playwright --notes ""

# Enable / disable / inspect / remove
magg server enable playwright
magg server disable playwright
magg server info playwright --json
magg server remove playwright

MaggClient によるリアルタイム通知

MaggClient は、バックエンドの MCP サーバーからのリアルタイム通知をサポートするようになりました。

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()

カスタムメッセージハンドラーなどの高度な使い方については、メッセージングのドキュメントを参照してください。

キット管理

Magg では、関連する MCP サーバーを「キット」としてまとめ、グループ単位で読み込み・読み込み解除できます。

# 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

# Export the current configuration (or a loaded kit) as a kit file
magg kit export --name my-kit --output my-kit.json

キットの読み込みを解除すると、そのキットにのみ属するサーバーは削除され、ほかのキットと共有されているサーバーは保持されます。

MCP クライアント経由で接続している場合は、Magg のツールからキットをプログラムで管理することもできます。

• magg_list_kits - 利用可能なすべてのキットを一覧表示します
• magg_load_kit - キットとそのサーバーを読み込みます
• magg_unload_kit - キットの読み込みを解除します
• magg_kit_info - キットの詳細情報を取得します

キットは ~/.magg/kit.d/ または .magg/kit.d/ に保存される JSON ファイルで、関連するサーバーの集合を定義します。キットの作成と管理の詳細については、キットのドキュメントを参照してください。

MBro スクリプト

MBro スクリプトで、よく使うワークフローを自動化できます。

# 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

MCP 2026-07-28（ステートレス仕様）

MCP 2026-07-28 仕様では、プロトコルの中核がステートレスなリクエスト／レスポンス方式に移行します。Magg の見解は次のとおりです。長時間稼働する stdio サブプロセス、バックエンド接続、ツール一覧のキャッシュを管理するものは依然として必要であり、それこそがアグリゲーターの役割です。影響分析と移行計画については、Magg とステートレス MCP 仕様を参照してください。Magg が 2026 年以前のステートフルなバックエンドとステートレス時代のクライアントをどのように橋渡しするか、また階層型 Magg デプロイメントがどのように適合するかについても説明しています。

ドキュメント

詳しくは、docs/を参照してください。

掲載情報

Magg は複数の場所で紹介されています。以下にアルファベット順で掲載情報を追加するプルリクエストを歓迎します。

MCP サイトの一覧、インデックス、その他

• DeepWiki - AI が生成したドキュメント
• Glama.ai - MCP サーバーの一覧とホスティング

Magg は、公式 MCP Registry 向けの server.json マニフェスト（io.github.sitbon/magg として）を提供しており、magg_search_servers は Glama、GitHub、npm と並ぶ主要な検出元としてレジストリを検索します。公開手順については、MCP Registry のドキュメントを参照してください。

mcp-name: io.github.sitbon/magg

GitHub の MCP リスト

• @modelcontextprotocol/servers
• @punkpeye/awesome-mcp-servers
• @wong2/awesome-mcp-servers