Skip to main content
Glama

mcp-mlx-launcher

An MCP (Model Context Protocol) server designed to autonomously manage, launch, and shutdown local mlx-lm instances on Apple Silicon (Mac) environments.

This tool empowers AI agents (like Cline, Claude Desktop, etc.) to start local LLM servers on demand, check their status, prepare environments, and gracefully shut them down when no longer needed, saving system resources.

💡 Proven in Production: This server was extracted as a general-purpose, reusable module from the cingulater project, where it is actively used and running in production.

Features

  • System Environment Check: Verify system memory and architecture (Apple Silicon) to ensure readiness.

  • Model Search & Download: Search Hugging Face for available MLX models and download them locally to cache before launching.

  • Launch & Manage Local LLMs: Start, stop, and restart an mlx-lm server with any supported model in the background.

  • Status Check: Verify if a specific port is currently active and listening.

  • Apple Silicon Optimized: Built specifically to manage MLX-based local models.

  • Auto Cleanup: Automatically cleans up and shuts down all managed LLM processes when the MCP server disconnects or shuts down, preventing resource leaks.

Related MCP server: Local AI MCP

Prerequisites

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

  • Python 3.10 or higher

  • mlx-lm installed in your environment (pip install mlx-lm)

Installation

# 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 .

Usage (MCP Configuration)

To use this server with your MCP client (e.g., Claude Desktop or Cline), add the following to your MCP configuration file:

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

Available Tools

Once connected, the MCP server provides the following tools to the AI agent:

  1. check_system_environment(): Diagnoses the current system environment, returning available unified memory (GB) and architecture details.

  2. check_llm_status(port: int): Returns true if a server is currently running on the specified port.

  3. list_running_servers(): Retrieves a list of all local LLM servers (ports and models) currently running in the background.

  4. search_mlx_models(search_query: str = "", limit: int = 10): Searches Hugging Face for available MLX format models and lists their details (like download count and model ID).

  5. download_model(model_name: str): Pre-downloads a specified MLX model from Hugging Face and caches it locally. Useful for preparing large models before launching.

  6. launch_llm_server(model_name: str, port: int, memory_requirement_gb: float = 4.0): Launches an mlx_lm.server instance in the background. Includes an optional memory requirement check to prevent out-of-memory errors.

  7. restart_llm_server(port: int, model_name: str = None, memory_requirement_gb: float = 4.0): Gracefully stops the running server on the given port and restarts it. If model_name is omitted, it restarts with the currently loaded model.

  8. shutdown_llm_server(port: int): Gracefully terminates the running LLM server on the given port.

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