Skip to main content
Glama

mcp-mlx-launcher

MCP-сервер (Model Context Protocol), предназначенный для автономного управления, запуска и остановки локальных экземпляров mlx-lm в средах Apple Silicon (Mac).

Этот инструмент позволяет ИИ-агентам (таким как Cline, Claude Desktop и др.) запускать локальные LLM-серверы по требованию, проверять их состояние, подготавливать окружение и корректно завершать их работу, когда они больше не нужны, что экономит системные ресурсы.

Функции

  • Проверка системного окружения: Проверка оперативной памяти и архитектуры (Apple Silicon) для обеспечения готовности.

  • Поиск и загрузка моделей: Поиск доступных моделей MLX на Hugging Face и их локальная загрузка в кэш перед запуском.

  • Запуск и управление локальными LLM: Запуск, остановка и перезапуск сервера mlx-lm с любой поддерживаемой моделью в фоновом режиме.

  • Проверка состояния: Проверка того, активен ли конкретный порт и ожидает ли он подключений.

  • Оптимизация под Apple Silicon: Разработан специально для управления локальными моделями на базе MLX.

  • Автоматическая очистка: Автоматически завершает работу всех управляемых процессов LLM при отключении или остановке MCP-сервера, предотвращая утечку ресурсов.

Related MCP server: Local AI MCP

Предварительные требования

  • macOS (Apple Silicon M1/M2/M3/M4)

  • Python 3.10 или выше

  • mlx-lm, установленный в вашем окружении (pip install mlx-lm)

Установка

# Clone the repository
git clone [https://github.com/YOUR_USERNAME/mcp-mlx-launcher.git](https://github.com/YOUR_USERNAME/mcp-mlx-launcher.git)
cd mcp-mlx-launcher

# Install dependencies
pip install -e .

Использование (конфигурация MCP)

Чтобы использовать этот сервер с вашим MCP-клиентом (например, Claude Desktop или Cline), добавьте следующее в файл конфигурации MCP:

{
  "mcpServers": {
    "mcp-mlx-launcher": {
      "command": "python",
      "args": [
        "-m",
        "mcp_mlx_launcher.server"
      ]
    }
  }
}

Доступные инструменты

После подключения MCP-сервер предоставляет ИИ-агенту следующие инструменты:

  1. check_system_environment(): Диагностирует текущее системное окружение, возвращая объем доступной объединенной памяти (ГБ) и сведения об архитектуре.

  2. check_llm_status(port: int): Возвращает true, если сервер в данный момент запущен на указанном порту.

  3. list_running_servers(): Получает список всех локальных LLM-серверов (порты и модели), работающих в фоновом режиме.

  4. search_mlx_models(search_query: str = "", limit: int = 10): Ищет доступные модели в формате MLX на Hugging Face и выводит их детали (например, количество загрузок и ID модели).

  5. download_model(model_name: str): Предварительно загружает указанную модель MLX с Hugging Face и кэширует её локально. Полезно для подготовки больших моделей перед запуском.

  6. launch_llm_server(model_name: str, port: int, memory_requirement_gb: float = 4.0): Запускает экземпляр mlx_lm.server в фоновом режиме. Включает необязательную проверку требований к памяти для предотвращения ошибок нехватки памяти.

  7. restart_llm_server(port: int, model_name: str = None, memory_requirement_gb: float = 4.0): Корректно останавливает работающий сервер на заданном порту и перезапускает его. Если model_name не указано, сервер перезапускается с текущей загруженной моделью.

  8. shutdown_llm_server(port: int): Корректно завершает работу LLM-сервера на заданном порту.

Available Tools

8 tools
check_llm_statusB

指定されたポートでサーバーがリッスンしているか(稼働中か)を確認します。

ParametersJSON Schema
NameRequiredDescriptionDefault
portYes確認するポート番号

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description does not disclose what the tool returns (e.g., boolean, status message) or any side effects. Without annotations, the agent lacks behavioral context beyond the basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no unnecessary words, perfectly front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool with one parameter and no output schema, the description is adequate but lacks mention of return format or how it differs from list_running_servers. It could be more complete for optimal agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Parameter schema coverage is 100%, and the description adds minimal value beyond the schema's parameter description. The baseline of 3 applies since the schema already documents the port parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it checks if a server is listening on a specified port, using a specific verb and resource. It distinguishes from sibling tools like launch_llm_server or shutdown_llm_server by focusing on status checking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as list_running_servers or check_system_environment. There is no mention of prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_system_environmentA

現在のシステム環境(Apple Siliconか、空きメモリが何GBあるかなど)を診断します。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses the tool's purpose (diagnose system environment) but does not mention side effects, permissions, or whether it is destructive. The diagnostic nature implies a read-only operation, but this is not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the main action ('診断します'). It is concise and contains no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description adequately conveys the tool's purpose for a simple diagnostic tool. However, it does not explain the output format or return value, which is a gap given the lack of an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema coverage is 100% trivially. Per guidelines, baseline score is 4. The description adds context about the type of diagnostic information, which is helpful.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it diagnoses the current system environment, specifically mentioning Apple Silicon and free memory. This clearly distinguishes it from sibling tools that deal with LLM status, servers, and models.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or alternatives are provided. However, the context of sibling tools and the description implies it should be used to check system hardware before running models. This is adequate but lacks explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

download_modelA

Hugging Faceから指定されたMLXモデルを事前にダウンロードし、ローカルにキャッシュします。大きなモデルの起動前の準備に利用します。

ParametersJSON Schema
NameRequiredDescriptionDefault
model_nameYesダウンロードするモデル名 (例: mlx-community/Llama-3-8B-Instruct-4bit)

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided; the description discloses caching but fails to mention overwrite behavior, authentication needs, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with clear front-loading of the action and purpose, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter tool, the description covers the core action and context, though additional details on caching behavior would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the description adds no extra meaning beyond the schema's parameter description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool downloads MLX models from Hugging Face and caches locally, distinguishing it from sibling tools like launch_llm_server or search_mlx_models.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It mentions 'use to prepare before launching large models' which implies when to use, but no explicit exclusions or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

launch_llm_serverB

mlx_lm.server をサブプロセスとしてバックグラウンドで起動します。空きメモリが少ない場合は起動が拒否されます。

ParametersJSON Schema
NameRequiredDescriptionDefault
model_nameYes起動するモデル名 (例: mlx-community/Llama-3-8B-Instruct-4bit)
portYesサーバーを起動するポート番号
memory_requirement_gbNo起動に必要な空きメモリの目安(GB)。未指定時はデフォルトで 4.0GB。

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions background subprocess and memory rejection, but lacks details on return behavior, readiness confirmation, error handling, or side effects. This is insufficient for a launch tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, front-loaded sentences with no unnecessary words. Each sentence provides essential information concisely.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description should explain return values or status. It only describes the action and a rejection condition, but not success behavior, how to check status, or how to interact with the launched server. Incomplete for a start operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all parameters. The description adds no extra parameter meaning beyond what is in the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it launches mlx_lm.server as a background subprocess, a specific verb+resource. It also mentions a condition for rejection (low memory). This distinguishes it from siblings like check_llm_status or list_running_servers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for initial server launch, but does not explicitly state when to use vs alternatives (e.g., restart_llm_server for restarting). No explicit exclusions or prerequisites beyond memory.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_running_serversA

現在バックグラウンドで稼働しているすべてのローカルLLMサーバー(ポート番号とモデル名)の一覧を取得します。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It confirms the tool is read-only but does not disclose potential behavioral traits like empty list behavior, authentication needs, or performance aspects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise, front-loaded, and contains no unnecessary information. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and lack of output schema, the description provides adequate context: what is returned (port and model name). It could mention handling of no servers running, but overall it is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the description does not need to add parameter information. A baseline of 4 is appropriate as the description is clear about the lack of parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the action (retrieve list), resource (running local LLM servers), and output details (port numbers and model names). It distinguishes itself from sibling tools like launch_llm_server or shutdown_llm_server by focusing on listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance is provided. The use case is implied by the tool name and description, but no alternatives or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

restart_llm_serverB

指定されたポートで稼働しているサーバーを一度停止し、再起動します。モデルの切り替えなどにも使用できます。

ParametersJSON Schema
NameRequiredDescriptionDefault
portYes再起動するサーバーのポート番号
model_nameNo(オプション)新しく起動するモデル名。省略した場合は現在そのポートで稼働しているモデルをそのまま再起動します。
memory_requirement_gbNo(オプション)起動に必要な空きメモリの目安(GB)。未指定時はデフォルトで 4.0GB。

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as service disruption, session handling, or error states. For a destructive operation, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that gets to the point. However, it could be more informative without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and annotations, the description should provide more context about what happens during restart, prerequisites (e.g., server must be running), and potential impacts. It falls short.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameters with clear descriptions. The tool's description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that it stops and restarts a server on a specified port, and mentions it can be used for switching models. This aligns with the name and distinguishes it from siblings like 'shutdown_llm_server' and 'launch_llm_server'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for model switching but does not explicitly state when to use versus alternatives. No guidance on when not to use or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_mlx_modelsC

Hugging Faceからダウンロード可能なMLXフォーマットのLLMモデルを検索・リストアップします。

ParametersJSON Schema
NameRequiredDescriptionDefault
search_queryNo検索キーワード(例: 'llama', 'qwen')。未指定の場合は人気のMLXモデルを返します。
limitNo取得する最大件数。デフォルトは10。

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, rate limits, pagination, or result format. The minimal description leaves substantial gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence with no irrelevant information, achieving conciseness. However, it may be slightly under-specified for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and full schema coverage, the description is adequate but could mention that the search is read-only and limited to MLX format. It does not explain return values or pagination.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and already documents both parameters. The description adds minimal extra value by providing an example for search_query and stating the default for limit, but does not go beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches and lists MLX format LLM models from Hugging Face, which distinguishes it from sibling tools focused on server management and model downloading.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool over alternatives like download_model, or any prerequisites. Usage context is implied but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

shutdown_llm_serverA

指定されたポートで稼働しているローカル LLM サーバープロセスを安全に終了させます。

ParametersJSON Schema
NameRequiredDescriptionDefault
portYes終了させるサーバーのポート番号

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions 'safe termination' but lacks detail on side effects (e.g., data loss), required permissions, or confirmation feedback. No annotations are provided, so the description partially covers behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with action and target. No superfluous words, highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool, the description is mostly adequate but omits what happens after termination (e.g., response, confirmation) and any prerequisites. With no output schema, more detail would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the parameter description already explains the port number. The tool description adds no additional semantic value beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (terminate), the target (local LLM server process), and the condition (running on specified port). It distinguishes well from sibling tools like launch_llm_server (start) and restart_llm_server (stop+start).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the tool name and description, but no explicit when-to-use or when-not-to-use guidance is provided. Sibling tools exist for related actions (e.g., restart), but no alternatives are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv0.2.1
    • First observedcheck_llm_status
    • First observedcheck_system_environment
    • First observeddownload_model
    • First observedlaunch_llm_server
    • First observedlist_running_servers
    • First observedrestart_llm_server
    • First observedsearch_mlx_models
    • First observedshutdown_llm_server

TDQS

A3.7/5.0

Scored across 8 tools

Disambiguation5/5

Each tool targets a distinct operation: system check, model download, server launch, list, restart, search, shutdown, and status check. No two tools have overlapping purposes.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., check_llm_status, launch_llm_server, shutdown_llm_server). No mixing of conventions.

Tool Count5/5

8 tools is well-scoped for an LLM server launcher covering environment check, model management, and server lifecycle. Neither too few nor too many.

Completeness4/5

Covers the full lifecycle: system check, model search/download, launch, list, restart, shutdown. Minor gap in lacking detailed server logs or configuration updates, but core operations are complete.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    A
    maintenance
    Unified MCP server for managing local model runtimes (Ollama, LM Studio, etc.), enabling provider-agnostic discovery, lifecycle management, hardware-fit checks, and delegated inference.
    16
    30 npm
    Creative Commons Attribution Non Commercial No Derivatives 4.0 International
  • A
    license
    Not graded
    quality
    C
    maintenance
    Text-to-speech MCP server using the Kokoro-82M model accelerated with MLX on Apple Silicon, enabling local Claude and Codex clients to speak text aloud and convert text to audio.
    4
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that enables local Apple on-device Foundation Model access via any MCP client, supporting text generation, structured output, and multi-turn chat on macOS.
    2
    MIT