MLX Player

What it does

• One-click setup. Installs uv, a private Python 3.12 and mlx-lm under ~/Library/Application Support/MLX Player/. No admin rights, nothing global.
• Discover and download MLX models from Hugging Face, with filters (size, quantization, capability, family, Standard / Uncensored / Abliterated) and a fit badge for your Mac.
• Advisor. Tells you what will actually run: fit (comfortable, tight, won't fit), a safe context size, estimated and measured tokens/s.
• Local server at http://127.0.0.1:8080/v1. A lazy proxy loads the model on the first request, unloads it when idle, enforces the context limit, streams SSE and meters usage.
• Memory aware. Live memory, GPU, VRAM and CPU view, GPU wired limit control, automatic responses to memory pressure.
• Library, Usage, Logs, Chat screens, plus a Hugging Face token kept in the Keychain.
• Agent access through an MCP server, so tools like Claude Code can manage models for you (see below).

Install with your AI agent

Paste this into your agent (Claude Code, Cursor, Codex, etc.). If you are an agent, follow it. It installs MLX Player and connects it over MCP.

Install MLX Player (https://github.com/kalahroudi/mlxplayer) on this Mac and connect it to me.

1. Check prerequisites: `uname -m` must print `arm64` and `sw_vers -productVersion` must be 14 or newer.
2. Install the latest release (no Xcode needed):
   cd "$(mktemp -d)" && gh release download --repo kalahroudi/mlxplayer --pattern 'MLX-Player-*.dmg' --pattern SHA256SUMS
   (or curl the DMG and SHA256SUMS from https://github.com/kalahroudi/mlxplayer/releases/latest)
   Verify with `shasum -a 256 -c SHA256SUMS`, then `hdiutil attach` the DMG and copy "MLX Player.app" to /Applications.
   If there is no release or the download fails, build from source instead: `xcode-select -p` must succeed
   (otherwise tell me to run `xcode-select --install` and wait), then
   git clone https://github.com/kalahroudi/mlxplayer.git ~/mlxplayer && cd ~/mlxplayer && scripts/bundle.sh
   and copy dist/"MLX Player.app" to /Applications.
3. Launch it with `open "/Applications/MLX Player.app"`. Tell me to right-click > Open if macOS blocks it.
4. First run: the app's Setup screen installs uv, Python and mlx-lm. Ask me to click through it,
   or tell me it is already done if Settings shows mlx-lm installed.
5. Register the MCP server for yourself:
   claude mcp add -s user mlxplayer -- "/Applications/MLX Player.app/Contents/MacOS/mlxplayer-mcp"
   (For other agents, add a stdio MCP server named `mlxplayer` with that command.)
   Then restart or reload so the tools appear.
6. Verify by calling `get_hardware` and `get_status`. Report the chip, memory and server state.
7. Do not download or load a model, or change settings, until I approve. Use `recommend_models` and show me the options first.

Requirements

• Apple Silicon Mac, macOS 14 or newer
• Xcode command line tools (xcode-select --install) to build from source
• Git

Install manually

Download the DMG from Releases, or build from source:

git clone https://github.com/kalahroudi/mlxplayer.git
cd mlxplayer
scripts/bundle.sh            # builds dist/MLX Player.app
open "dist/MLX Player.app"

Optional: copy it to /Applications. The build is ad-hoc signed, so on first launch right-click the app and choose Open once. The app can update itself from this repo (Settings > Updates).

To build a disk image: scripts/make-dmg.sh VERSION. Tagging vX.Y.Z runs .github/workflows/release.yml, which builds, tests and publishes the DMG.

Use the endpoint

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"default","messages":[{"role":"user","content":"Hello"}]}'

Point any OpenAI-compatible client at http://127.0.0.1:8080/v1 (any API key value works). The model loads on the first request.

Use it from other computers

Run the model on one Mac and call it from another computer, a phone or an app on your network. Open Server > Network > Host and pick how far the endpoint reaches. The app works out the address for you and copies it, so there is nothing to look up or configure by hand.

Host	Who can connect	URL the app copies
This Mac only (default)	Only this Mac	http://127.0.0.1:8080/v1
Local network	Any device on the same Wi-Fi or Ethernet	http://192.168.1.42:8080/v1 (this Mac's LAN address)
Tailscale	Only your own Tailscale devices, from anywhere	https://your-mac.your-tailnet.ts.net/v1

The copied URL appears in the Server screen, the menu bar popover (Copy URL), the sidebar and the cURL, Python and environment snippets. Use it as the base URL of any OpenAI-compatible client, from the other computer:

curl https://your-mac.your-tailnet.ts.net/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"default","messages":[{"role":"user","content":"Hello"}]}'

Model names the server does not know, like default, are sent to the loaded model, so most clients work without an exact model ID. The model loads on the first request, as usual.

Local network

• The proxy listens on all interfaces, so other devices on the network can connect. The model server itself stays on loopback.
• The app picks the address a neighbour would use: private ranges (192.168.x.x, 10.x.x.x, 172.16-31.x.x) on Wi-Fi or Ethernet first, VPN and virtual interfaces after. If the Mac has several networks, only one is shown. Its <computer-name>.local name works too.
• macOS may ask to allow incoming connections for MLX Player the first time. Click Allow, or other devices will time out.
• There is no authentication: anyone on the network can use the endpoint and the memory it loads. Only turn this on for networks you trust. Prefer Tailscale otherwise.

Tailscale

Needs the Tailscale app on this Mac, signed in. Nothing else to set up.

• The app reads Tailscale's status, finds this Mac's MagicDNS name and publishes https://<name>.ts.net through tailscale serve, which forwards to the proxy. Tailscale issues the certificate, so clients get real HTTPS with no warnings.
• Only devices on your tailnet can connect. Other devices on the Wi-Fi cannot, unlike Local network.
• If Tailscale is off, the Tailscale URL row says so and the URL works once it is on again. The Tailscale option only shows in the list when Tailscale is installed.
• One-time setup in your tailnet: HTTPS needs "HTTPS Certificates" turned on in the Tailscale admin console. Until then the app copies the plain http://<name>.ts.net:8080/v1 URL (still encrypted by Tailscale) and shows a link to enable it. It retries by itself.
• If something else already uses HTTPS port 443 in tailscale serve, the app leaves it alone and keeps the HTTP URL.
• The HTTPS entry is removed when you switch the host back or quit the app. Entries you created yourself are never touched.

Switch models

Only one model is loaded at a time. You can switch from the sidebar, the menu bar popover or the Library screen.

• A switch waits for running requests to finish (up to 60 s) so no reply is cut off.
• If the new model fails to load, the previous one is brought back, so the endpoint is not left empty.
• Clients can switch too: with Switch by request on (Memory > Loading), the model field of a request loads that installed model. Turn it off and every request uses the loaded model.

Agent access (MCP)

Once installed (see above), agents drive MLX Player over MCP.

MCP tools

The MCP server is mlxplayer-mcp (stdio), bundled at MLX Player.app/Contents/MacOS/mlxplayer-mcp. The app must be running for the control tools.

Tool	What it does	Asks you first
get_hardware	Chip, memory, GPU memory limit, bandwidth, usable memory for a model	No
search_models	Search MLX models on Hugging Face	No
analyze_model	Fit, context size, speed estimate and memory breakdown for a model	No
recommend_models	Best overall, highest quality and fastest model for a job	No
get_status	Server state, loaded model, endpoint, memory and speed	No
download_model	Download a model into the Hugging Face cache	Yes
start_server	Load a model and start the server (optional context_length, thinking)	Yes
update_settings	Change saved settings for a model	Yes
stop_server	Stop the server and free memory	Yes
delete_model	Delete a downloaded model	Always

The app detects Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI and Codex CLI and connects or disconnects each with one click: Settings > Agents (MCP). It uses the agent's own CLI where it has one and otherwise edits its config file (keeping a one-time backup). Control calls go through a loopback API protected by a bearer token (control.json, mode 0600), and actions that change state show an approval dialog.

Development

swift build        # core, MCP server and the macOS app
swift test         # 94 tests (the proxy streaming tests need python3)
swift run mlxplayer-mcp
MLXPlayer --snapshot DIR [dark] [collapsed] [screen]   # render screens to PNG (used for the images above)

Layout:

Path	Contents
Sources/MLXPlayerCore	UI-free logic: hardware, advisor, installer, server supervisor, lazy proxy, usage, memory policy, Hugging Face client, MCP, agent integrations
Sources/MLXPlayer	The macOS app (SwiftUI + AppKit)
Sources/mlxplayer-mcp	Stdio MCP server
scripts/	Bundle, DMG and notarization scripts
design/	Approved mockups (open the *.dc.html files in a browser)

Notes: the sandbox must stay off because the app spawns processes. mlx_lm.server has no --max-kv-size in 0.32.2, so the proxy enforces context limits by estimating tokens.

Roadmap

See ROADMAP.md.

License

Apache License 2.0. See LICENSE.