🧲 马格 - *MCP聚合器*
](https://pypi.org/project/magg/) ](https://pypi.org/project/magg/) ](https://github.com/sitbon/magg/releases)  ](https://pypistats.org/packages/magg)
 ](https://github.com/sitbon/magg/actions/workflows/docker-publish.yml)
A. *模型上下文协议* 管理、聚合和代理其他MCP服务器的服务器，使LLM能够动态扩展自己的功能。
Magg是什么？
Magg是一个元MCP服务器，作为管理多个MCP服务器的中心枢纽。它提供了允许LLM执行以下操作的工具：
- 搜索新的MCP服务器并发现设置说明
- 动态添加和配置MCP服务器
- 按需启用/禁用服务器
- 在统一前缀下聚合来自多个服务器的工具
- 跨会话持久化配置
将Magg视为“LLM工具的包管理器”——它允许AI助手在运行时安装和管理自己的功能。
特性
- 自助工具管理：LLM可以在没有人为干预的情况下搜索和添加新的MCP服务器。
- 动态配置重新加载：自动检测并应用配置更改，而无需重新启动。
- 自动工具代理：添加的服务器中的工具会自动以可配置的前缀公开。
- ProxyMCP工具：一个内置工具，将MCP协议代理给自己，用于不支持通知或动态工具更新的客户端（目前大多数客户端都不支持）。
- 智能配置：使用MCP采样仅从URL智能配置服务器。
- 持久配置：维护中的服务器配置
.magg/config.json. - 多种运输支持：适用于stdio、HTTP和内存传输。
- 承载令牌身份验证：可选的基于RSA的JWT身份验证，用于安全的HTTP访问。
- Docker支持：用于生产、暂存和开发工作流程的预构建图像。
- 健康监测：内置
magg_status和magg_check服务器健康检查工具。 - 实时消息：完全支持MCP通知和消息-从后端服务器接收工具/资源更新和进度通知。
- Python 3.12+支持与Python 3.12和3.13完全兼容。
- 套件管理：将相关的MCP服务器捆绑成套件，以便作为一个组轻松装载/卸载。
- MBro命令行界面：包括在内 MCP浏览器 用于MCP服务器的交互式探索和管理，并支持自动化脚本。
安装
先决条件
- Python 3.12或更高版本（推荐3.13以上版本）
uv（推荐）-从安装 星光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码头工人
Magg可以从GitHub容器注册表中作为预构建的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:latestDocker镜像策略
Magg使用多阶段Docker构建，有三个目标阶段：
pro（生产）：具有警告日志级别的最小映像，适用于生产部署pre（预生产）：与生产相同，但具有用于暂存/测试的INFO日志级别（可用但未发布）dev（发展）：包括用于故障排除的开发依赖关系和DEBUG日志记录
图像会自动发布到GitHub容器注册表，并带有以下标签：
- 版本标签 （来自主要分支机构）：
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：
# 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可以在三种模式下运行：
- 标准模式 （默认）-用于与Claude Desktop、Cline、Cursor等集成：
magg serve- HTTP模式 -对于全系统访问或web集成：
magg serve --http --port 8000- 混合模式 -同时使用stdio和HTTP：
magg serve --hybrid
magg serve --hybrid --port 8080 # Custom port当您想通过MCP客户端使用Magg，同时允许HTTP访问时，这尤其有用。例如：
使用克劳德代码：
# 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_serversMBro还支持：
- 脚本：创建
.mbro带有自动化命令的文件 - 外壳式参数：使用
key=value语法而不是JSON - 选项卡完成：连接后丰富的参数提示
请参阅 MBro文件 了解详情。
认证
Magg支持可选的承载令牌身份验证以确保访问安全：
快速开始
- 初始化身份验证 （创建RSA密钥对）：
magg auth init- 生成JWT令牌 对于客户：
# Generate token (displays on screen)
magg auth token
# Export as environment variable
export MAGG_JWT=$(magg auth token -q)- 通过身份验证连接:
- 使用 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环境变量 - 要禁用身份验证，请删除密钥或设置为不存在
key_path在.magg/auth.json
身份验证命令
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并自动重新加载（在可用时使用看门狗） - SIGHUP信号：发送 `kill -HUP
` 触发立即重新加载（类Unix系统）
- MCP工具：使用
magg_reload_config来自任何MCP客户端的工具 - 智能过渡：在重新加载过程中，只有受影响的服务器会重新启动
默认情况下启用配置重新加载。您可以通过以下方式控制它：
MAGG_AUTO_RELOAD=false-禁用自动重新加载MAGG_RELOAD_POLL_INTERVAL=5.0-设置轮询间隔（秒）（监视器不可用时）
看 配置重新加载文档 了解详细信息。
环境变量
Magg支持多种环境变量进行配置：
MAGG_CONFIG_PATH-配置文件的路径（默认：.magg/config.json)MAGG_LOG_LEVEL-日志记录级别：调试、信息、警告、错误、严重（默认值：信息）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-前缀和工具名称之间的分隔符（默认值：“\_”）
配置示例：
{
"servers": {
"calculator": {
"name": "calculator",
"source": "https://github.com/executeautomation/calculator-mcp",
"command": "npx @executeautomation/calculator-mcp",
"prefix": "calc",
"enabled": true
}
}
}添加服务器
服务器可以通过多种方式添加：
- 使用LLM （推荐）：
"Add the Playwright MCP server"
"Search for and add a calculator tool"- 手动配置 通过
magg_add_server:
name: playwright
url: https://github.com/microsoft/playwright-mcp
command: npx @playwright/mcp@latest
prefix: pw- 直接配置编辑：编辑
.magg/config.json直接
使用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当通过MCP客户端连接时，您还可以通过Magg的工具以编程方式管理套件：
magg_list_kits-列出所有可用套件magg_load_kit-加载套件及其服务器magg_unload_kit-卸载套件magg_kit_info-获取详细的套件信息
套件是存储在中的JSON文件 ~/.magg/kit.d/ 或 .magg/kit.d/ 它们定义了一组相关的服务器。看 套件文档 有关创建和管理工具包的详细信息。
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文档
有关更多文档，请参阅 docs/.
外表
Magg出现在多个位置。请随时提交PR，以便按字母顺序在下面添加更多露面。