Leela MCP Server (lc0-mcp)

An MCP (Model Context Protocol) server that exposes the Leela Chess Zero neural-network chess engine (lc0) to any MCP client. Once connected, a client (Claude, or any other MCP host) can analyze positions, get best moves, evaluate lines, and manipulate boards through a small set of tools.

Naming: lc0 is the binary name for Leela Chess Zero, hence the lc0-* command and tool names in this repo.

This package is just the MCP server. The engine binary (lc0) and a network weights file are external dependencies you provide — see Prerequisites.

Quick start

For the impatient — each step links to its detailed section below.

1. Install Python ≥ 3.10 and pipx (python3 -m pip install --user pipx && python3 -m pipx ensurepath).

2. Get the lc0 engine binary — build it or download a release. See 1. The lc0 engine. Note its path.

3. Get a network (*.pb.gz weights file) and note its path. See 2. A network (weights) file.

4. Install this server:

   git clone https://github.com/indulge/leela-mcp-server.git
   cd leela-mcp-server
   pipx install .

5. Connect it to your MCP client with the two paths from steps 2–3. For Claude Code:

   claude mcp add -s user lc0-chess lc0-mcp \
     -e LC0_PATH=/path/to/lc0 \
     -e LC0_WEIGHTS=/path/to/network.pb.gz

   See Use with an MCP client for Claude Desktop, Cursor, etc.

6. Verify: claude mcp list shows lc0-chess … ✔ Connected, or run the smoke test.

Related MCP server: chess-uci-mcp

Prerequisites

1. The lc0 engine

lc0 is a separate project (lczero.org · GitHub: LeelaChessZero/lc0).

• Official prebuilt binaries are Windows-only. On Linux/macOS, build from source with meson + ninja (see lc0's build instructions), or install via your package manager if it ships lc0.

• The build produces a binary, typically at build/release/lc0. Note that path — you'll point LC0_PATH at it.

2. A network (weights) file

A source build of lc0 does not bundle a network, and lc0 will not start without one.

• Download a .pb.gz network from the lc0 networks page or storage.lczero.org.

• Smaller nets (e.g. a distilled 256×10, ~37 MB) run acceptably on CPU; larger nets (768×15, 170–380 MB) are stronger but want a GPU backend.

• Note the file path — you'll point LC0_WEIGHTS at it.

Install

The server installs a lc0-mcp console command. Install it for the current user with pipx (recommended — isolates the dependencies and avoids PEP 668 "externally-managed environment" errors):

git clone https://github.com/indulge/leela-mcp-server.git
cd leela-mcp-server
pipx install .

This puts lc0-mcp on your PATH and pulls in its Python dependencies (mcp[cli], python-chess). Verify with which lc0-mcp — it should print a path like ~/.local/bin/lc0-mcp. (There's no --help; it's a stdio server that waits for an MCP client to connect — see Run / test.)

Alternatives:

pipx install -e .                 # editable: track the working tree (for development)
pip install --user .              # without pipx (may need a venv on PEP-668 systems)

To upgrade: pipx reinstall lc0-mcp. To remove: pipx uninstall lc0-mcp.

Configure (environment variables)

The server is configured entirely through environment variables. LC0_PATH and LC0_WEIGHTS are effectively required — set them to your engine binary and network from Prerequisites. (As a convenience, if you place the binary at ./lc0/build/release/lc0 and any *.pb.gz net in ./networks/ relative to the server source, the defaults below find them — but for an installed command you should set the paths explicitly.)

Use with an MCP client

lc0-mcp is a stdio MCP server: a client launches it as a subprocess and talks JSON-RPC over stdin/stdout. Every stdio MCP client configures the same three things — a command, optional args, and env vars:

command: lc0-mcp
args:    (none)
env:     LC0_PATH=/path/to/lc0
         LC0_WEIGHTS=/path/to/network.pb.gz

A ready-to-edit JSON example is in examples/mcp-config.json. Two concrete clients:

Claude Code (CLI)

claude mcp add -s user lc0-chess lc0-mcp \
  -e LC0_PATH=/path/to/lc0 \
  -e LC0_WEIGHTS=/path/to/network.pb.gz \
  -e LC0_DEFAULT_NODES=2000

Then claude mcp list should show lc0-chess: … ✔ Connected.

Claude Desktop, Cursor, and other JSON-config clients

Most MCP hosts (Claude Desktop, Cursor, Windsurf, Zed, …) take the same command / args / env shape in a JSON config file — only the file's location differs (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json). Add an entry under mcpServers:

{
  "mcpServers": {
    "lc0-chess": {
      "command": "lc0-mcp",
      "env": {
        "LC0_PATH": "/path/to/lc0",
        "LC0_WEIGHTS": "/path/to/network.pb.gz"
      }
    }
  }
}

Then restart (or reload) the client and it will launch lc0-mcp on demand.

If lc0-mcp isn't found: the client's launch environment may not include your user bin directory on PATH. Use the absolute path instead — find it with which lc0-mcp (e.g. ~/.local/bin/lc0-mcp) and put that in "command".

Tools

fen accepts a FEN string or the literal "startpos". The search budget defaults to LC0_DEFAULT_NODES; pass nodes, movetime_ms, or depth to override per call.

Run / test

# Run the installed server standalone (stdio; it waits for an MCP client — Ctrl-C to stop)
LC0_PATH=/path/to/lc0 LC0_WEIGHTS=/path/to/network.pb.gz lc0-mcp

# Smoke test: drives the server as a real MCP client end-to-end.
# Requires LC0_PATH / LC0_WEIGHTS in the environment (or the default paths populated).
pip install -r requirements.txt          # if running from source without installing
LC0_PATH=/path/to/lc0 LC0_WEIGHTS=/path/to/network.pb.gz python test_mcp.py

Project layout

leela-mcp-server/
├── lc0_mcp_server.py     # the MCP server (all tools)
├── pyproject.toml        # packaging — defines the `lc0-mcp` command + deps (source of truth)
├── requirements.txt      # convenience deps for running from source (mirrors pyproject)
├── test_mcp.py           # end-to-end MCP smoke test
├── examples/
│   └── mcp-config.json   # generic client config (placeholder paths)
├── LICENSE               # MIT
└── README.md

References

• MCP — protocol spec & SDKs: https://modelcontextprotocol.io

• Leela Chess Zero — project home: https://lczero.org

• lc0 — engine source & build guide: https://github.com/LeelaChessZero/lc0

• Networks — weights downloads: https://lczero.org/play/networks/bestnets/ · https://storage.lczero.org/

• python-chess — board/move/FEN library used here: https://python-chess.readthedocs.io

License

MIT — see LICENSE.