mlx-serve-mcp

Servidor MCP que convierte una instancia remota de mlx-serve en herramientas invocables — para que cualquier cliente MCP (Claude Code, Claude Desktop, Cline, ...) en cualquier dispositivo pueda generar imágenes, voz, música, vídeo y mallas 3D a través del ip:port de tu Mac.

mlx-serve ejecuta los modelos de forma nativa en Apple Silicon; este puente se comunica mediante MCP por un lado y con la API de medios estilo OpenAI de mlx-serve (/v1/images, /v1/audio, /v1/video, /v1/3d) por el otro. Nada se genera localmente: tu máquina solo se comunica por HTTP con el servidor.

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

Instalación y ejecución

Requiere Python ≥ 3.10. Con uv instalado:

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

La URL acepta ip:port sin más (se asume http), host:port, o una URL completa http(s)://....

Configuración

Las opciones de CLI anulan las variables de entorno:

Modelos por defecto

Cada herramienta multimedia acepta un argumento model opcional. Cuando se omite, la herramienta recurre a un valor predeterminado configurable (variable de entorno → integrado):

Recomendación de modelos (basada en pruebas reales con mlx-serve):

• ddalcu/Mage-Flow-Turbo-MLX-Serve-8bit es rápido, pero su calidad está por debajo de Runpod/FLUX.2-klein-4B-mflux-4bit — en particular, la generación de rostros tiende a salir distorsionada. Sin embargo, es mucho más fiable que mlx-community/flux2-klein-9b-4bit a la hora de renderizar texto en imágenes, así que para arte centrado en texto (pósters, tipografía, letreros) en lugar de retratos, ddalcu/Mage-Flow-Turbo-MLX-Serve-8bit es la opción recomendada.

• ddalcu/Mage-Flow-Edit-Turbo-MLX-Serve-8bit puede dar un error de peso/parámetro en mlx-serve (Model load failed: MissingMageFlowWeight), lo que hace que el modelo no se pueda usar.

• mlx-community/flux2-klein-9b-4bit tiene un problema similar de fallo al cargar.

En resumen: usa Runpod/FLUX.2-klein-4B-mflux-4bit tanto para generate_image como para edit_image — es el único modelo de imagen de este grupo que carga de forma fiable y produce buenos resultados (incluidos los rostros).

Defínelas en la configuración de tu cliente MCP para fijar los modelos que realmente tienes instalados en el servidor:

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

Integración con tu cliente 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) usa la misma estructura command/args. Añade "env": {"MLX_SERVE_API_KEY": "..."} si el servidor requiere una clave.

Herramientas

Los archivos de salida se guardan en <output-dir>/{images,audio,video,mesh}/ con nombres con marca de tiempo; cada herramienta informa de rutas absolutas en su texto de resultado.

Indicaciones

Plantillas de indicaciones de un clic expuestas a través de prompts/list / prompts/get:

Recursos

Fuentes de datos en vivo expuestas a través de resources/list / resources/read:

LobeHub Marketplace

Este paquete está publicado en el LobeHub MCP Marketplace con un manifiesto completo lhm.plugin.json y un skill.md para el descubrimiento por parte de agentes.

Notas de diseño

• Vídeo: mlx-serve responde con bytes de fotogramas RGB8 crudos (+ pista PCM s16le opcional), no con un archivo codificado. Este puente los multiplexa en MP4 H.264/AAC mediante ffmpeg — prefiriendo el ffmpeg del sistema y recurriendo al binario estático incluido con la dependencia imageio-ffmpeg, por lo que no se necesita instalación adicional.

• Imágenes: se devuelven tanto en línea (contenido de imagen MCP, vista previa instantánea) como archivos PNG guardados.

• Errores: los mensajes de error 400 con nombre de mlx-serve (p. ej. 'speed' must be in (0, 5]) se muestran tal cual para que el LLM que llama pueda autocorregirse.

• Campos LoRA: no se exponen a propósito: requieren rutas .safetensors en el disco del servidor, lo que rara vez tiene sentido para llamadas remotas.

• Las generaciones largas son simplemente peticiones HTTP lentas; aumenta --timeout si tus clips son ambiciosos.

Desarrollo

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