mlx-serve-mcp

リモートの mlx-serve インスタンスを呼び出し可能なツールに変える MCP サーバー — これにより、あらゆるデバイスの MCP クライアント（Claude Code、Claude Desktop、Cline、...）が、Mac の ip:port を通じて画像、音声、音楽、動画、3D メッシュを生成できます。

mlx-serve は Apple Silicon 上でモデルをネイティブに実行します。このブリッジは、片側で MCP を話し、もう片側で mlx-serve の OpenAI スタイルのメディア API（/v1/images、/v1/audio、/v1/video、/v1/3d）を話します。ローカルでは何も生成されません — あなたのマシンはサーバーと HTTP で通信するだけです。

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

インストールと実行

Python ≥ 3.10 が必要です。uv がインストールされている場合:

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

URL はベアの ip:port（http とみなされます）、host:port、または完全な http(s)://... URL を受け付けます。

設定

CLI フラグは環境変数を上書きします:

デフォルトモデル

各メディアツールはオプションの model 引数を受け付けます。省略した場合、ツールは設定可能なデフォルト（環境変数 → 組み込み）にフォールバックします:

モデル推奨（mlx-serve での実機テストに基づく）:

• ddalcu/Mage-Flow-Turbo-MLX-Serve-8bit は高速ですが、品質は Runpod/FLUX.2-klein-4B-mflux-4bit に及びません — 特に顔の生成は歪みがちです。ただし、画像内のテキスト描画では mlx-community/flux2-klein-9b-4bit よりもはるかに信頼性が高いため、肖像画ではなくテキスト中心のアート（ポスター、タイポグラフィ、看板）には ddalcu/Mage-Flow-Turbo-MLX-Serve-8bit が推奨されます。

• ddalcu/Mage-Flow-Edit-Turbo-MLX-Serve-8bit は mlx-serve で重み/パラメータエラー（Model load failed: MissingMageFlowWeight）が発生することがあり、モデルが使用できなくなります。

• mlx-community/flux2-klein-9b-4bit にも同様のロード失敗の問題があります。

結論: generate_image と edit_image の両方に Runpod/FLUX.2-klein-4B-mflux-4bit を使用してください — このグループの中で、信頼性の高いロードと良好な結果（顔を含む）の両方を実現する唯一の画像モデルです。

サーバーに実際にインストールしているモデルを固定するには、MCP クライアントの設定でこれらを設定してください:

{
  "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

MCP クライアントへの組み込み

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）も同じ command/args 形式を使用します。サーバーがキーを必要とする場合は "env": {"MLX_SERVE_API_KEY": "..."} を追加してください。

ツール

出力ファイルは <output-dir>/{images,audio,video,mesh}/ の下にタイムスタンプ付きの名前で保存されます。すべてのツールは結果テキストで絶対パスを報告します。

プロンプト

prompts/list / prompts/get で公開されるワンクリックのプロンプトテンプレート:

リソース

resources/list / resources/read で公開されるライブデータソース:

LobeHub Marketplace

このパッケージは LobeHub MCP Marketplace に公開されており、完全な lhm.plugin.json マニフェストと、エージェントによる発見のための skill.md が含まれています。

設計メモ

• 動画: mlx-serve はエンコード済みファイルではなく生の RGB8 フレームバイト（+ オプションの PCM s16le トラック）で応答します。このブリッジは ffmpeg 経由でそれらを H.264/AAC MP4 に多重化します — システムの ffmpeg を優先し、imageio-ffmpeg 依存関係に同梱された静的バイナリにフォールバックするため、別途インストールは不要です。

• 画像はインライン（MCP 画像コンテンツ、即時プレビュー）と保存された PNG ファイルの両方で返されます。

• エラー: mlx-serve の名前付き 400 メッセージ（例: 'speed' must be in (0, 5]）はそのまま表示されるため、呼び出し元の LLM が自己修正できます。

• LoRA フィールドは意図的に公開されていません。これらはサーバーのディスク上の .safetensors パスを必要とするため、リモートの呼び出し元にはほとんど意味がありません。

• 長時間の生成はここでは単に遅い HTTP リクエストです。凝ったクリップを生成する場合は --timeout を上げてください。

開発

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