# 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

```bash
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:

```toml
[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"
```