omlx-mcp-server

Local stdio MCP server for oMLX.

Tools

• omlx_status: return the local oMLX model list and current power status in one call.
• omlx_run: unified execution tool for either chat or agent mode.

Battery Guard

omlx_run checks power status before using a model.

• On AC power: execute normally.
• On battery power: return status="needs_confirmation" unless allow_on_battery=true.

This is meant to force an explicit user decision before running heavy local inference on battery.

Compact Interface

The server is intentionally compressed to two tools to keep MCP schema overhead down.

• Use omlx_status() to fetch models + power_status.
• Use omlx_run(mode="chat" | "agent", prompt=...) for execution.

omlx_run picks a default model automatically:

• chat mode defaults to MLX-Qwen3.5-27B-Claude-4.6-Opus-Reasoning-Distilled-v2-4bit
• agent mode defaults to MLX-Qwen3.5-35B-A3B-Claude-4.6-Opus-Reasoning-Distilled-8bit

Defaults

• Default chat model: MLX-Qwen3.5-27B-Claude-4.6-Opus-Reasoning-Distilled-v2-4bit
• Default agent model: MLX-Qwen3.5-35B-A3B-Claude-4.6-Opus-Reasoning-Distilled-8bit
• Default base URL: http://127.0.0.1:8000/v1

Local Run

UV_CACHE_DIR=.uv-cache UV_PROJECT_ENVIRONMENT=.venv uv sync --dev
UV_CACHE_DIR=.uv-cache UV_PROJECT_ENVIRONMENT=.venv uv run omlx-mcp-server

Codex Config Snippet

Add this to your Codex config if you want future sessions to discover it automatically. Replace /path/to/omlx-mcp-server with your clone path and set your local oMLX key:

[mcp_servers.omlx]
command = "uv"
args = [
  "run",
  "--directory", "/path/to/omlx-mcp-server",
  "omlx-mcp-server",
]

[mcp_servers.omlx.env]
UV_CACHE_DIR = "/path/to/omlx-mcp-server/.uv-cache"
UV_PROJECT_ENVIRONMENT = "/path/to/omlx-mcp-server/.venv"
OMLX_BASE_URL = "http://127.0.0.1:8000/v1"
OMLX_API_KEY = "your-local-omlx-key"
OMLX_DEFAULT_MODEL = "MLX-Qwen3.5-27B-Claude-4.6-Opus-Reasoning-Distilled-v2-4bit"
OMLX_AGENT_MODEL = "MLX-Qwen3.5-35B-A3B-Claude-4.6-Opus-Reasoning-Distilled-8bit"