Skip to main content
Glama
Sign In
omlx-mcp

omlx-mcp

by chsh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

omlx-mcp

English | 日本語

A minimal stdio MCP server that lets Claude (or any MCP client) run prompts on a local 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.

Related MCP server: CascadeGateway

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

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:

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • CascadeGateway

      jadberro
      A
      license
      A
      quality
      B
      maintenance
      Provides an MCP endpoint that lets clients like Google Antigravity and Claude Desktop dispatch LLM tasks to local GPU models with automatic hardware-adaptive routing and cloud fallback, enabling near-zero token cost execution.
      3
      4
      MIT

    • glm-orchestrator

      RiasJ1Dar
      A
      license
      B
      quality
      C
      maintenance
      Enables orchestration of OpenAI-compatible GLM and other model endpoints via MCP, supporting streaming, background runs, cancellation, and local run history, with an optional bridge to other MCP servers.
      20
      ISC