mlx-mcp

MLX, MLX Data and MLX LM docs for Claude Code, Codex and other coding agents.

Install · Use it · Tools · Troubleshooting

mlx-mcp gives Claude Code, Codex and other coding agents the MLX, MLX Data and MLX LM docs, so your agent can check the docs before it writes MLX code instead of working from memory.

It runs on your Mac, needs no account or API key, and works offline after the first search.

An independent project, not affiliated with Apple or the MLX maintainers.

Install

You need an Apple silicon Mac with macOS 14 or later. Claude Desktop needs nothing else. The other clients need uv.

Add mlx-mcp to your agent below. Apart from Claude Desktop, every client runs the same command, uvx --python 3.13 mlx-mcp serve, so there's nothing else to install. uv downloads Python 3.13 if you don't have it.

Claude Desktop

Download mlx-mcp.mcpb, double-click it to open it in Claude Desktop, and install it. Claude Desktop sets up Python and everything mlx-mcp needs.

Claude Code

claude mcp add --scope user mlx-docs -- uvx --python 3.13 mlx-mcp serve

Codex

codex mcp add mlx-docs -- uvx --python 3.13 mlx-mcp serve

Cursor

Or add it by hand in ~/.cursor/mcp.json:

{
	"mcpServers": {
		"mlx-docs": {
			"command": "uvx",
			"args": ["--python", "3.13", "mlx-mcp", "serve"]
		}
	}
}

VS Code

Or add it by hand in .vscode/mcp.json:

{
	"servers": {
		"mlx-docs": {
			"type": "stdio",
			"command": "uvx",
			"args": ["--python", "3.13", "mlx-mcp", "serve"]
		}
	}
}

Other MCP clients

Add a stdio server named mlx-docs that runs this command:

{
	"command": "uvx",
	"args": ["--python", "3.13", "mlx-mcp", "serve"]
}

Related MCP server: context

Use it

Ask your agent, for example:

• "Use mlx-mcp to port this PyTorch code to MLX."

• "Check the MLX docs: does mx.compile handle inputs whose shape changes?"

• "This MLX inference is slow. Use mlx-mcp's performance workflow to find out why."

Your agent can also check which docs versions mlx-mcp has, and every page it reads says which version it's from.

Your agent starts mlx-mcp when it needs it. The first start downloads about 65 MB, mostly MLX, and the first search downloads the 90 MB search model. After that it works offline.

Tools

All four only read the docs stored on your Mac. Your agent runs and edits your code with its own tools.

Update

uvx --python 3.13 mlx-mcp@latest --version

Then start a new agent session. In Claude Desktop, download and install the latest mlx-mcp.mcpb again.

Uninstall

Remove mlx-docs from each agent you connected:

• Claude Code: claude mcp remove --scope user mlx-docs

• Codex: codex mcp remove mlx-docs

• Claude Desktop: remove mlx-mcp in its extension settings.

• Cursor, VS Code and other clients: delete the mlx-docs entry.

Then delete ~/.cache/mlx-mcp to free the space.

If something doesn't work

Run uvx --python 3.13 mlx-mcp prepare and start a new session. It downloads anything missing and checks that search and fetch work. If that doesn't fix it, open an issue with what the command printed.

If Cursor, VS Code or another app can't find uvx, run command -v uvx in a terminal and use the path it prints as the command.

Good to know

• The performance workflow points your agent to Apple's profiling tools: Instruments' Time Profiler and Metal System Trace through xctrace, gpucapture, gpudebug, footprint and Metal validation. When perfkit is installed, it maps each question to a perfkit command group: Metal System Trace summaries, kernel-level GPU time from captures, GPU telemetry, CPU call trees, static kernel analysis, paired benchmarks and capture diffs. The agent reads exact commands from perfkit contract describe --json and perfkit api describe --json rather than hard-coded flags. It returns guidance only and does not run your code.

• The bundled docs may not match the MLX version you have installed. uvx --python 3.13 mlx-mcp info shows the versions mlx-mcp has. uvx --python 3.13 mlx-mcp prepare --refresh downloads the latest MLX and MLX Data docs. MLX LM stays at its bundled version. Start a new session after refreshing.

• mlx-mcp has the published docs, not the MLX source code. The docs don't always say which kernel or device runs an operation. For that, read the MLX source or measure it.

• uvx --python 3.13 mlx-mcp --help lists the commands.

License

MIT. Includes text from the MLX, MLX Data and MLX LM projects, © Apple Inc., under the MIT License. See the third-party notices. To report a security problem, see Security.