STARWARCLOUD STARWAR.AI
返回市场
镁格

镁格

作者：sitbon108 星标更新：2025-08-07
安装使用来源：spider==github.com

项目介绍

🧲 Magg - MCP聚合器

Python 版本 PyPI 版本 GitHub 发布 DeepWiki 下载量

<!-- DeepWiki 徽章由 https://deepwiki.ryoppippi.com/ 生成 -->

测试 Docker

一个管理、聚合和代理其他 MCP 服务器的 模型上下文协议 服务器，使大语言模型能够动态扩展其自身能力。

Magg 是什么？

Magg 是一个作为多个 MCP 服务器管理中心的元 MCP 服务器。它提供了允许大语言模型进行以下操作的工具：

  • 搜索新的 MCP 服务器并发现设置说明
  • 动态添加和配置 MCP 服务器
  • 按需启用或禁用服务器
  • 将来自多个服务器的工具统一到一个前缀下
  • 在会话之间持久化配置

可以将 Magg 视为“LLM 工具的包管理器”——它让 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 安装

快速安装（推荐）

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

# 安装 Magg 作为工具
uv tool install magg

# 使用 stdio 传输运行（适用于 Claude Desktop、Cline 等）
magg serve

# 使用 HTTP 传输运行（系统范围访问）
magg serve --http

替代方案：直接从 GitHub 运行

您也可以不安装直接从 GitHub 运行 Magg：

# 使用 stdio 传输运行
uvx --from git+https://github.com/sitbon/magg.git magg

# 使用 HTTP 传输运行
uvx --from git+https://github.com/sitbon/magg.git magg serve --http

本地开发

对于开发，克隆仓库并以可编辑模式安装：

# 克隆仓库
git clone https://github.com/sitbon/magg.git
cd magg

# 以开发模式安装，包括开发依赖项
uv sync --dev

# 或者使用 poetry
poetry install --with dev

# 运行 CLI
magg --help

Docker

Magg 提供了预构建的 Docker 镜像，可以从 GitHub Container Registry 获取：

# 运行生产镜像（警告日志级别）
docker run -p 8000:8000 ghcr.io/sitbon/magg:latest

# 带认证运行（挂载或设置私钥）
docker run -p 8000:8000 \
  -v ~/.ssh/magg:/home/magg/.ssh/magg:ro \
  ghcr.io/sitbon/magg:latest

# 或者使用环境变量
docker run -p 8000:8000 \
  -e MAGG_PRIVATE_KEY="$(cat ~/.ssh/magg/magg.key)" \
  ghcr.io/sitbon/magg:latest

# 运行测试镜像（信息日志级别）
docker run -p 8000:8000 ghcr.io/sitbon/magg:beta

# 使用自定义配置目录运行
docker run -p 8000:8000 \
  -v /path/to/config:/home/magg/.magg \
  ghcr.io/sitbon/magg:latest

Docker 镜像策略

Magg 使用多阶段 Docker 构建，有三个目标阶段：

  • pro（生产）：最小镜像，警告日志级别，适合生产部署
  • pre（预生产）：与生产相同但信息日志级别，用于测试（可用但未发布）
  • dev（开发）：包含开发依赖项和调试日志，便于故障排除

镜像自动发布到 GitHub Container Registry，带有以下标签：

  • 版本标签（主分支）：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 等。

Docker Compose

为了更轻松地管理，使用 Docker Compose：

# 克隆仓库
git clone https://github.com/sitbon/magg.git
cd magg

# 运行生产版本
docker compose up magg

# 运行测试版本（端口 8001）
docker compose up magg-beta

# 运行开发版本（端口 8008）
# 这使用 ./.magg/config.json 进行配置
docker compose up magg-dev

# 使用自定义注册表构建和运行
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  # 自定义端口

    当您希望通过 MCP 客户端使用 Magg 并同时允许 HTTP 访问时，这特别有用。例如：

    与 Claude Code 结合使用：

    # 配置 Claude Code 使用混合模式的 Magg
claude mcp add magg -- magg serve --hybrid --port 42000

    与 mbro 结合使用：

    # mbro 主机 Magg 并通过 stdio 连接
mbro connect magg "magg serve --hybrid --port 8080"

# 其他 mbro 实例可以通过 HTTP 连接
mbro connect magg http://localhost:8080

可用工具

一旦 Magg 正在运行，它将向大语言模型提供以下工具：

  • 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 进行快速检查：

# 通过 stdio 连接 mbro 到 Magg 实例（不需要 HTTP 服务器）
mbro connect local-magg magg serve

# 现在从 MCP 客户端的角度检查您的 Magg 设置
mbro:local-magg> call magg_status
mbro:local-magg> call magg_list_servers

MBro 还支持：

  • 脚本：创建 .mbro 文件，包含命令以实现自动化
  • shell 样式的参数：使用 key=value 语法代替 JSON
  • 自动补全：连接后提供丰富的参数提示

详情见 MBro 文档。

认证

Magg 支持可选的 Bearer Token 认证来保护访问：

快速开始

  1. 初始化认证（生成 RSA 密钥对）：

    magg auth init

  2. 生成 JWT 令牌供客户端使用：

    # 生成令牌（显示在屏幕上）
magg auth token

# 导出为环境变量
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 支持无需重启即可自动重新加载配置：

  • 自动文件监视：检测 `