# omlx-mcp

English | [日本語](README.ja.md)

A minimal stdio MCP server that lets Claude (or any MCP client) run prompts on a local [oMLX](https://github.com/jundot/omlx) instance through its OpenAI-compatible API.

## Tools

| Tool | Purpose |
|---|---|
| `omlx_status` | Loaded models, default model, power state, and recent jobs |
| `omlx_run` | Run a prompt. Waits up to `wait_seconds` (max 50); if not finished, returns a `job_id` |
| `omlx_result` | Fetch a job's result, waiting up to 50 seconds if it is still running |
| `omlx_cancel` | Cancel a running job |

Design notes:

- Waits are capped at 50 seconds so calls stay inside the 60-second timeout that some MCP bridges enforce. Longer generations keep running as jobs and can be polled with `omlx_result`.
- `thinking=false` (the default) sends `chat_template_kwargs.enable_thinking=false`. If `enable_thinking` is pinned in oMLX's per-model settings, that setting wins.
- Responses contain only the answer text, `finish_reason`, and a usage summary. Reasoning is included only with `include_reasoning=true`.
- `context` is placed before the prompt, so repeated calls over the same material reuse oMLX's prefix cache.
- On battery power, runs are refused unless `allow_on_battery=true`.
- Jobs are stored as `~/.omlx-mcp/jobs/*.json`. Jobs that were running when the server restarted are marked `lost`. The latest 100 jobs are kept.
- No tool calling (web search etc.). Plain generation only.

## Environment variables

| Variable | Default |
|---|---|
| `OMLX_BASE_URL` | `http://127.0.0.1:8000/v1` |
| `OMLX_API_KEY` | none |
| `OMLX_DEFAULT_MODEL` | first entry of `/v1/models` |
| `OMLX_JOB_DIR` | `~/.omlx-mcp/jobs` |

## Setup

```sh
git clone https://github.com/chsh/omlx-mcp.git
cd omlx-mcp
uv sync --dev
uv run pytest -q
```

## Registering with Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "omlx": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "--directory", "/absolute/path/to/omlx-mcp", "omlx-mcp"],
      "env": {
        "OMLX_BASE_URL": "http://127.0.0.1:8000/v1",
        "OMLX_API_KEY": ""
      }
    }
  }
}
```

Use absolute paths for both `uv` and the repository (check with `which uv` and `pwd`). Processes launched by Claude Desktop get a minimal `PATH`.

## License

[0BSD](LICENSE)