Magg

🧲 Magg - MCP 聚合器

一个 Model Context Protocol 服务，用于管理、聚合和代理其他 MCP 服务，让大模型能够动态扩展自身能力。

Magg 是什么？

Magg 是一个元 MCP 服务，充当管理多个 MCP 服务的中心枢纽。它提供的工具让大模型能够：

• 搜索新的 MCP 服务并查找设置说明
• 动态添加和配置 MCP 服务
• 按需启用或禁用服务
• 在统一前缀下聚合来自多个服务的工具
• 在不同会话间保留配置

可以把 Magg 想成“大模型工具的包管理器”——它让 AI 助手能够在运行时安装和管理自己的能力。

功能

• 自助式工具管理：大模型无需人工干预，即可搜索并添加新的 MCP 服务。
• 动态重新加载配置：自动检测并应用配置更改，无需重启。
• 自动代理工具：新增服务中的工具会自动对外提供，并可配置前缀。
• ProxyMCP 工具：内置工具，可将 MCP 协议代理给自身，供不支持通知或动态工具更新的客户端使用（目前大多数客户端都不支持）。
• 智能配置：使用 MCP 采样，仅凭 URL 即可智能配置服务。
• 持久化配置：在 .magg/config.json 中保存服务配置。
• 支持多种传输方式：支持 stdio、HTTP 和内存传输方式。
• Bearer Token 身份验证：可选的基于 RSA 的 JWT 身份验证，确保 HTTP 访问安全。
• 支持 Docker：为生产、预发布和开发工作流提供预构建镜像。
• 运行状况监控：内置 magg_status 和 magg_check 工具，用于检查服务运行状况。
• 实时消息传递：全面支持 MCP 通知和消息，可接收后端服务发送的工具／资源更新和进度通知。
• 支持 Python 3.12+：完全兼容 Python 3.12 和 3.13。
• 套件管理：将相关 MCP 服务打包为套件，方便成组加载／卸载。
• MBro CLI：内含 MCP 浏览器，可交互式探索和管理 MCP 服务，并支持通过脚本实现自动化。

安装

前提条件

• Python 3.12 或更高版本（推荐 3.13+）
• uv（推荐）——从 astral.sh/uv 安装

快速安装（推荐）

使用 uv 将 Magg 作为工具安装是最简单的方法：

# 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 使用多阶段 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 可通过以下三种模式运行：

1. Stdio 模式（默认）——用于与 Claude Desktop、Cline、Cursor 等集成：

   magg serve
   

2. HTTP 模式——用于系统范围访问或 Web 集成：

   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 运行后，会向大模型提供以下工具：

• magg_list_servers - 列出所有已配置的 MCP 服务
• magg_add_server - 添加新的 MCP 服务
• magg_remove_server - 移除 MCP 服务
• 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 Browser）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 文件
• Shell 风格的参数：使用 key=value 语法代替 JSON
• Tab 补全：连接后提供丰富的参数提示

详情请参阅 MBro 文档。

身份验证

Magg 支持可选的 bearer token 身份验证，以保护访问安全：

快速入门

1. 初始化身份验证（创建 RSA 密钥对）：

   magg auth init
   

2. 为客户端生成 JWT token：

   # 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 和显式 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()
     

密钥管理

• 密钥默认存储在 ~/.ssh/magg/
• 可通过 MAGG_PRIVATE_KEY 环境变量设置私钥
• 若要禁用身份验证，请移除密钥，或在 .magg/auth.json 中将 key_path 设为不存在的路径

身份验证命令

• magg auth init - 初始化身份验证（生成 RSA 密钥对）
• magg auth status - 检查身份验证配置
• magg auth token - 生成 JWT token
• 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. 使用大模型（推荐）：

   "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 命令行工具（见下文）

4. 直接编辑配置：直接编辑 .magg/config.json

通过命令行管理服务

完全可以通过命令行管理服务和套件配置——无需 MCP 客户端或运行中的服务。命令行工具会直接编辑 .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 出现在多个地方。欢迎提交 PR，按字母顺序在下方添加更多展示。

列表、索引及其他 MCP 站点

• DeepWiki - AI 生成的文档
• Glama.ai - MCP 服务列表和托管

Magg 提供了一个 server.json 清单，用于 官方 MCP Registry（名称为 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