mcp-mlx-launcher MCP 服务说明文档
1. 服务概述
一句话简介：允许搜索Hugging Face上可用的MLX模型并在启动前将其下载到本地缓存
- 服务名称：mcp-mlx-launcher
- 版本号：最新版本
- 开发者/提供方：globalpocket
- 协议类型：MCP (Model Context Protocol)
2. 核心功能
列出该MCP服务提供的主要功能点：
- 系统环境检查：验证系统内存和架构（Apple Silicon）以确保就绪状态
- 模型搜索与下载：搜索Hugging Face上可用的MLX模型，并在启动前将其下载到本地缓存
- 启动和管理本地LLM：在后台启动、停止和重启mlx-lm服务器，支持任何支持的模型
- 状态检查：验证特定端口是否当前处于活动状态并正在监听
- Apple Silicon优化：专为管理基于MLX的本地模型而构建，充分利用Apple Silicon的性能优势
- 自动清理：当MCP服务器断开连接或关闭时，自动清理并关闭所有管理的LLM进程，防止资源泄漏
3. 使用场景
描述该服务适合在什么情况下使用：
- 本地LLM服务器管理：为AI代理（如Cline、Claude Desktop等）提供按需启动本地LLM服务器的能力
- 模型搜索和下载：在Hugging Face上搜索MLX格式的模型，并预先下载到本地缓存
- 资源管理和优化：在不需要时优雅地关闭LLM服务器，节省系统资源
- 开发和测试环境：为开发人员提供便捷的本地LLM环境管理工具
- Apple Silicon环境优化：充分利用Apple Silicon的统一内存架构，高效运行本地模型
- 自动化工作流：集成到AI代理工作流中，实现自动化的模型管理和部署
4. 接入方式
4.1 服务端点
mcp-mlx-launcher作为MCP服务器运行，通过stdio传输与MCP客户端通信：
- 传输协议：stdio（标准输入/输出）
- 运行环境：本地Python环境
- 目标平台：macOS（Apple Silicon M1/M2/M3/M4）
4.2 认证与权限
该服务不需要特殊的认证机制：
- 本地运行：在本地环境中运行，无需API密钥或认证
- Hugging Face访问：通过公开API访问Hugging Face模型库
- 系统权限：需要访问本地文件系统和网络（用于下载模型）
4.3 数据格式
服务支持以下数据格式：
- 模型格式：MLX格式的模型（专为Apple Silicon优化）
- 模型来源：Hugging Face模型库
- 响应格式：结构化的JSON数据，包含模型信息、服务器状态等
4.4 服务器配置
在MCP客户端配置中添加服务：
{ "mcpServers": { "mcp-mlx-launcher": { "command": "python", "args": [ "-m", "mcp_mlx_launcher.server" ] } } }5. 接口定义
mcp-mlx-launcher提供以下工具接口：
| 工具名称 | 功能描述 | 主要参数 |
|---|---|---|
check_system_environment | 诊断当前系统环境，返回可用统一内存（GB）和架构详情 | 无参数 |
check_llm_status | 检查指定端口上是否有服务器正在运行 | port: 端口号 |
list_running_servers | 检索当前在后台运行的所有本地LLM服务器列表（端口和模型） | 无参数 |
search_mlx_models | 在Hugging Face上搜索可用的MLX格式模型，列出详细信息（如下载次数和模型ID） | search_query: 搜索关键词, limit: 返回数量限制 |
download_model | 预先下载指定的MLX模型从Hugging Face并缓存到本地，适合在启动前准备大型模型 | model_name: 模型名称 |
launch_llm_server | 在后台启动mlx_lm.server实例，包含可选的内存需求检查以防止内存不足错误 | model_name: 模型名称, port: 端口号, memory_requirement_gb: 内存需求（GB） |
restart_llm_server | 优雅地停止给定端口上运行的服务器并重新启动，如果省略model_name则使用当前加载的模型 | port: 端口号, model_name: 模型名称（可选）, memory_requirement_gb: 内存需求（GB） |
shutdown_llm_server | 优雅地终止给定端口上运行的LLM服务器 | port: 端口号 |
6. 快速开始
6.1 环境要求
- 操作系统：macOS（Apple Silicon M1/M2/M3/M4）
- Python：版本 3.10 或更高
- mlx-lm：已安装在您的环境中（
pip install mlx-lm）
6.2 示例代码
安装步骤
# 克隆仓库 git clone https://github.com/YOUR_USERNAME/mcp-mlx-launcher.git cd mcp-mlx-launcher # 安装依赖 pip install -e .使用示例
# 1. 检查系统环境 result = check_system_environment() # 返回：可用内存（GB）和架构信息 # 2. 搜索MLX模型 models = search_mlx_models(search_query="llama", limit=10) # 返回：模型列表，包含下载次数和模型ID # 3. 下载模型（可选，提前准备） download_model("mlx-community/Llama-2-7b-chat-mlx") # 将模型下载到本地缓存 # 4. 启动LLM服务器 launch_llm_server( model_name="mlx-community/Llama-2-7b-chat-mlx", port=8080, memory_requirement_gb=8.0 ) # 在端口8080上启动服务器 # 5. 检查服务器状态 is_running = check_llm_status(port=8080) # 返回：True/False # 6. 列出所有运行的服务器 servers = list_running_servers() # 返回：所有运行中的服务器列表 # 7. 重启服务器 restart_llm_server(port=8080) # 重启指定端口的服务器 # 8. 关闭服务器 shutdown_llm_server(port=8080) # 优雅地关闭服务器与Claude Desktop集成
{ "mcpServers": { "mcp-mlx-launcher": { "command": "python", "args": ["-m", "mcp_mlx_launcher.server"] } } }7. 注意事项
重要提示
- 平台限制：仅支持macOS（Apple Silicon M1/M2/M3/M4），不支持Intel Mac或其他操作系统
- 内存管理：启动大型模型前，建议检查系统可用内存，避免内存不足错误
- 端口冲突：确保指定的端口未被其他服务占用
- 模型缓存：下载的模型会缓存在本地，首次下载可能需要较长时间
- 自动清理：MCP服务器断开时会自动关闭所有管理的LLM进程，无需手动清理
- 网络连接：搜索和下载模型需要网络连接到Hugging Face
- Python版本：确保使用Python 3.10或更高版本
- mlx-lm依赖：必须先安装mlx-lm包才能使用此服务
性能优化建议
为获得最佳性能，建议：
- 使用具有足够统一内存的Mac设备（建议16GB或更多）
- 在启动大型模型前使用
download_model预先下载 - 定期检查系统内存使用情况
- 在不使用时及时关闭LLM服务器以释放资源