Apuntar Claude Code a oMLX y conectar oMLX por MCP no son la misma operación. La primera sustituye el modelo que hay detrás del cliente; la segunda convierte tu servidor local en un conjunto de herramientas que el cliente puede invocar. Este artículo cubre la segunda: qué expone el puente mcp_omlx, cómo se instala, cómo se configura en Claude Desktop y qué límites tiene hoy.

Puntos clave

  • El puente mcp_omlx expone siete herramientas MCP sobre las API de oMLX: dos de catálogo, tres de inferencia y dos de gestión de memoria.
  • Es un paquete de Python independiente del propio oMLX, con licencia MIT y versión 0.1.1 publicada el 3 de junio de 2026.
  • La configuración vive en claude_desktop_config.json y solo necesita una ruta al ejecutable y la variable OMLX_BASE_URL.
  • Sirve para gestionar el ciclo de vida de los modelos, no para reemplazar el endpoint del cliente. Para eso está la guía de instalación y ajuste de oMLX.
  • Es software joven y de un solo mantenedor: conviene tratarlo como una herramienta de laboratorio, no como una pieza de producción.

Qué resuelve el puente que no resuelve ANTHROPIC_BASE_URL

Cuando exportas ANTHROPIC_BASE_URL y apuntas Claude Code a http://127.0.0.1:8000, estás haciendo una sustitución: el cliente deja de hablar con la API de Anthropic y habla con tu Mac. El modelo local pasa a ser el modelo. Es la vía que cubre la guía de instalación y no ha cambiado.

El puente MCP hace algo distinto. Claude sigue siendo Claude, y tu servidor local aparece como un conjunto de herramientas que el asistente puede llamar cuando le convenga. Eso habilita un patrón que la sustitución no permite: preguntarle al asistente qué modelos tienes cargados, pedirle que libere uno que ocupa memoria y que cargue otro, o que lance una inferencia contra un modelo pequeño para una tarea concreta, todo dentro de la misma conversación.

Dicho de otro modo, la sustitución cambia quién responde y el puente añade qué puede hacer el que responde. Son complementarios, no alternativos.

Las siete herramientas que expone mcp_omlx

El paquete envuelve endpoints de las tres API de oMLX (la compatible con OpenAI, la de administración y la de embeddings) en siete herramientas MCP:

Herramienta Endpoint de oMLX Para qué sirve
omlx_list_models GET /v1/models Lista los modelos disponibles por identificador o alias
omlx_model_status GET /admin/api/models Informa del estado de carga, la memoria ocupada y la ventana de contexto
omlx_chat POST /v1/chat/completions Genera una respuesta de chat
omlx_completion POST /v1/completions Genera una compleción de texto
omlx_embeddings POST /v1/embeddings Genera embeddings
omlx_load_model POST /admin/api/models/{id}/load Carga un modelo en memoria
omlx_unload_model POST /admin/api/models/{id}/unload Descarga un modelo de la memoria

Las dos últimas son las que justifican el montaje. En un Mac con memoria unificada, decidir qué modelo ocupa RAM en cada momento es la restricción real, y hacerlo desde la conversación evita saltar al panel de administración.

Requisitos previos

El puente pide Python 3.10 o superior y un servidor de oMLX accesible por HTTP. Las dependencias (mcp, httpx y pydantic) se instalan solas.

Por su parte, oMLX exige macOS 15.0 o superior y Python 3.11 a 3.13, y escucha en el puerto 8000 por defecto. El proyecto se describe a sí mismo como "Continuous batching and tiered KV caching, managed directly from your menu bar" (README de oMLX), es decir, batching continuo y caché KV por niveles gestionados desde la barra de menús. Con 18.800 estrellas y 2.306 commits en la rama principal, es un proyecto activo, cosa que no se puede decir todavía del puente.

Debajo de todo esto está MLX, el marco de trabajo de Apple para aprendizaje automático en Apple Silicon. Su rasgo distintivo, y la razón por la que la gestión de memoria importa tanto aquí, es el modelo de memoria unificada: según la documentación de Apple, "Arrays in MLX live in shared memory", los arrays viven en memoria compartida entre CPU y GPU. No hay copia entre dispositivos, pero tampoco hay una VRAM separada donde aparcar un modelo: lo que carga oMLX sale del mismo presupuesto de RAM que usa el resto del Mac.

Instalación del puente

Dos comandos, en un entorno virtual propio para no ensuciar el Python del sistema:

python3 -m venv ~/mcp-omlx
~/mcp-omlx/bin/pip install git+https://github.com/William12556/mcp_omlx.git

No hay paquete en PyPI: la instalación va contra el repositorio. Eso implica que estás fijando el estado de la rama en el momento de instalar, sin versión reproducible. Si te importa la reproducibilidad, clona el repositorio, fija el commit y usa pip install -e . desde el clon.

Configurar el cliente de escritorio

La configuración de clientes MCP vive, en macOS, en ~/Library/Application Support/Claude/claude_desktop_config.json. Se llega desde el menú Claude de la barra del sistema, en Settings, pestaña Developer, botón Edit Config.

El bloque que hay que añadir es corto:

{
  "mcpServers": {
    "omlx": {
      "command": "~/mcp-omlx/bin/omlx-mcp",
      "env": {
        "OMLX_BASE_URL": "http://127.0.0.1:8000"
      }
    }
  }
}

Tres variables de entorno gobiernan el comportamiento:

Variable Valor por defecto Qué controla
OMLX_BASE_URL http://127.0.0.1:8000 Raíz del servidor; acepta un /v1 final
OMLX_API_KEY sin definir Token Bearer, opcional
OMLX_TIMEOUT 300 Tiempo de espera por petición, en segundos

Los 300 segundos de espera por defecto son generosos a propósito: una primera carga de modelo grande desde disco puede tardar bastante, y un tiempo de espera corto abortaría la llamada justo cuando el modelo estaba a punto de quedar disponible.

Un aviso sobre la ruta: la documentación del proyecto usa ~ en command, pero los clientes MCP no siempre expanden la virgulilla. Si el servidor no arranca, sustitúyela por la ruta absoluta (/Users/tuusuario/mcp-omlx/bin/omlx-mcp). La guía oficial de MCP insiste en el mismo punto: las rutas del fichero de configuración deben ser absolutas, no relativas.

Después de guardar hay que cerrar Claude Desktop del todo y volver a abrirlo. No basta con cerrar la ventana.

Comprobar que el puente responde

Antes de culpar al puente, comprueba que oMLX está sirviendo:

curl -s http://127.0.0.1:8000/v1/models | head -c 400

Si eso devuelve un JSON con la lista de modelos, el servidor está bien y el problema, si lo hay, está en el cliente. Dentro de Claude Desktop, el indicador de conectores de la caja de entrada debe mostrar omlx con sus siete herramientas al desplegar la gestión de conectores.

Qué mirar cuando no aparece el servidor

La documentación oficial de MCP describe el procedimiento de diagnóstico, y aquí aplica igual. Los registros del cliente están en ~/Library/Logs/Claude: mcp.log recoge las conexiones y sus fallos, y cada servidor tiene su propio mcp-server-omlx.log con la salida de error del proceso.

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Si el registro no aclara nada, lanza el ejecutable a mano desde el terminal. Un fallo de importación de Python o una ruta mal escrita se ven ahí de inmediato y no siempre llegan al registro del cliente.

Límites que conviene conocer

Esta es la parte que suele faltar en las guías de integración, así que conviene decirlo claro.

mcp_omlx es un proyecto creado el 3 de junio de 2026, cuya última versión publicada es la 0.1.1 de esa misma fecha, con licencia MIT y un único mantenedor. Un número de versión 0.1.1 y un repositorio nacido el mismo día de su última entrega describen software en fase temprana, no una dependencia estable.

Además, las herramientas omlx_load_model y omlx_unload_model operan contra la API de administración. Cualquier cosa capaz de hablar con esa API puede desalojar modelos de la memoria. Mientras OMLX_BASE_URL apunte a 127.0.0.1 el riesgo es local, pero si expones oMLX a la red (por ejemplo con el reenvío de puertos por SSH que describe la guía de instalación), define OMLX_API_KEY y arranca oMLX con --api-key.

Por último, el puente no sustituye a la integración nativa. Si lo que quieres es que Claude Code razone con un modelo local, la vía sigue siendo ANTHROPIC_BASE_URL, y si lo que buscas es escribir tus propias herramientas, es más sólido construir un servidor MCP propio que depender de un envoltorio de terceros.

Preguntas frecuentes

¿Puedo usar el puente y ANTHROPIC_BASE_URL a la vez? Sí, porque actúan en capas distintas. Puedes tener Claude Code apuntando a oMLX como modelo y, en paralelo, Claude Desktop con el puente MCP para gestionar qué modelos están cargados.

¿Funciona con otros clientes MCP además de Claude Desktop? El bloque mcpServers es el formato común de configuración de servidores locales, así que cualquier cliente que lo admita debería poder arrancarlo. La documentación del puente solo acredita Claude Desktop.

¿Necesito reiniciar oMLX al instalar el puente? No. El puente es un proceso aparte que habla con oMLX por HTTP; oMLX no se entera de que existe.

Conclusión

El puente MCP para oMLX resuelve un problema concreto y acotado: gestionar el ciclo de vida de los modelos locales desde la misma conversación en la que trabajas, en lugar de alternar con el panel de administración. Siete herramientas, dos comandos de instalación y un bloque JSON. A cambio, aceptas una dependencia en versión 0.1.1 mantenida por una sola persona, lo que la sitúa en el terreno de la herramienta de laboratorio. Si tu objetivo es rendimiento y no gestión, empieza por la guía de instalación y ajuste de oMLX y deja el puente para después. La versión en inglés de este artículo está en oMLX as an MCP server.

Fuentes

  1. mcp_omlx, repositorio del puente MCP
  2. oMLX, servidor de inferencia para Apple Silicon
  3. Model Context Protocol: conectar servidores MCP locales
  4. MLX, documentación oficial de Apple