mlx-serve-mcp

MCP-Server, der eine entfernte mlx-serve-Instanz in aufrufbare Tools verwandelt — sodass jeder MCP-Client (Claude Code, Claude Desktop, Cline, ...) auf jedem Gerät Bilder, Sprache, Musik, Videos und 3D-Meshes über die ip:port deines Macs erzeugen kann.

mlx-serve führt die Modelle nativ auf Apple Silicon aus; diese Brücke spricht auf der einen Seite MCP und auf der anderen Seite die OpenAI-artige Medien-API von mlx-serve (/v1/images, /v1/audio, /v1/video, /v1/3d). Lokal wird nichts erzeugt — dein Rechner kommuniziert nur per HTTP mit dem Server.

┌──────────────┐  stdio/MCP   ┌────────────────┐    HTTP     ┌──────────────────┐
│ MCP client   │ ◄──────────► │  mlx-serve-mcp │ ──────────► │ mlx-serve server │
│ (any device) │              │  (this package)│  ip:port    │  (Apple Silicon) │
└──────────────┘              └────────────────┘             └──────────────────┘

Installation & Ausführung

Erfordert Python ≥ 3.10. Mit installiertem uv:

cd mlx-serve-mcp
uv sync                 # create venv + install deps
uv run mlx-serve-mcp --url 192.168.1.10:11234

Die URL akzeptiert eine reine ip:port (http wird angenommen), host:port oder eine vollständige http(s)://...-URL.

Konfiguration

CLI-Flags überschreiben Umgebungsvariablen:

Standardmodelle

Jedes Medien-Tool akzeptiert ein optionales model-Argument. Wenn es weggelassen wird, verwendet das Tool einen konfigurierbaren Standard (Env-Variable → eingebaut):

Modellempfehlung (basierend auf realen Tests auf mlx-serve):

• ddalcu/Mage-Flow-Turbo-MLX-Serve-8bit ist schnell, aber seine Qualität liegt unter Runpod/FLUX.2-klein-4B-mflux-4bit — insbesondere die Gesichtserzeugung neigt dazu, verzerrt zu wirken. Allerdings ist es weitaus zuverlässiger als mlx-community/flux2-klein-9b-4bit beim Rendern von Text in Bildern. Für textlastige Kunst (Poster, Typografie, Schilder) statt Porträts ist ddalcu/Mage-Flow-Turbo-MLX-Serve-8bit die empfohlene Wahl.

• ddalcu/Mage-Flow-Edit-Turbo-MLX-Serve-8bit kann auf mlx-serve einen Gewichts-/Parameterfehler auslösen (Model load failed: MissingMageFlowWeight), was das Modell unbrauchbar macht.

• mlx-community/flux2-klein-9b-4bit hat ein ähnliches Ladefehlerproblem.

Fazit: Verwende Runpod/FLUX.2-klein-4B-mflux-4bit für generate_image und edit_image — es ist das einzige Bildmodell in dieser Gruppe, das sowohl zuverlässig lädt als auch gute Ergebnisse (einschließlich Gesichtern) liefert.

Setze sie in der Konfiguration deines MCP-Clients, um die Modelle festzulegen, die du tatsächlich auf dem Server installiert hast:

{
  "mcpServers": {
    "mlx-serve": {
      "command": "uv",
      "args": ["--directory", "/path/to/mlx-serve-mcp", "run", "mlx-serve-mcp", "--url", "192.168.1.10:11234"],
      "env": {
        "MLX_SERVE_API_KEY": "private",
        "MLX_SERVE_IMAGE_MODEL": "ddalcu/Mage-Flow-Turbo-MLX-Serve-8bit",
        "MLX_SERVE_TTS_MODEL": "mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16"
      }
    }
  }
}

Related MCP server: imagine-mcp

In deinen MCP-Client einbinden

Claude Code (.mcp.json / claude mcp add):

{
  "mcpServers": {
    "mlx-serve": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/mlx-serve-mcp",
        "run", "mlx-serve-mcp",
        "--url", "192.168.1.10:11234"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json) verwendet dieselbe command/args-Struktur. Füge "env": {"MLX_SERVE_API_KEY": "..."} hinzu, wenn der Server einen Schlüssel erfordert.

Tools

Ausgabedateien landen unter <output-dir>/{images,audio,video,mesh}/ mit Zeitstempelnamen; jedes Tool meldet absolute Pfade in seinem Ergebnistext.

Prompts

Ein-Klick-Prompt-Vorlagen, die über prompts/list / prompts/get bereitgestellt werden:

Ressourcen

Live-Datenquellen, die über resources/list / resources/read bereitgestellt werden:

LobeHub Marketplace

Dieses Paket ist im LobeHub MCP Marketplace mit einem vollständigen lhm.plugin.json-Manifest und einer skill.md für die Agentenermittlung veröffentlicht.

Designhinweise

• Video: mlx-serve antwortet mit rohen RGB8-Framebytes (+ optionaler PCM-s16le-Spur), nicht mit einer kodierten Datei. Diese Brücke führt sie per ffmpeg zu H.264/AAC-MP4 zusammen — bevorzugt wird das System-ffmpeg, andernfalls die statische Binärdatei, die mit der imageio-ffmpeg-Abhängigkeit gebündelt ist, sodass keine separate Installation nötig ist.

• Bilder werden sowohl inline (MCP-Bildinhalt, sofortige Vorschau) als auch als gespeicherte PNG-Dateien zurückgegeben.

• Fehler: Die benannten 400-Meldungen von mlx-serve (z. B. 'speed' must be in (0, 5]) werden wörtlich ausgegeben, damit das aufrufende LLM sich selbst korrigieren kann.

• LoRA-Felder werden absichtlich nicht bereitgestellt: Sie erfordern .safetensors-Pfade auf der Festplatte des Servers, was für entfernte Aufrufer selten sinnvoll ist.

• Lange Generierungen sind hier nur langsame HTTP-Anfragen; erhöhe --timeout, wenn deine Clips ambitioniert sind.

Entwicklung

uv sync
uv run pytest          # unit tests (mocked HTTP, no server required)
uv run mlx-serve-mcp --help