mlx-serve-mcp

MCP-сервер, который превращает удалённый экземпляр mlx-serve в вызываемые инструменты — так что любой MCP-клиент (Claude Code, Claude Desktop, Cline, ...) на любом устройстве может генерировать изображения, речь, музыку, видео и 3D-сетки через ip:port вашего Mac.

mlx-serve запускает модели нативно на Apple Silicon; этот мост говорит на MCP с одной стороны и на OpenAI-совместимом медиа-API mlx-serve (/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 или полный URL вида http(s)://....

Конфигурация

Флаги 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 имеет аналогичную проблему с загрузкой.

Итог: используйте Runpod/FLUX.2-klein-4B-mflux-4bit и для generate_image, и для edit_image — это единственная модель из этой группы, которая и загружается стабильно, и даёт хорошие результаты (включая лица).

Укажите их в конфигурации вашего 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), а не закодированным файлом. Этот мост мультиплексирует их в H.264/AAC MP4 через ffmpeg — предпочитая системный ffmpeg, с откатом на статический бинарник из зависимости imageio-ffmpeg, так что отдельная установка не требуется.

• Изображения возвращаются и inline (MCP image content, мгновенный предпросмотр), и как сохранённые 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