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.

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.

Related MCP server: chess-uci-mcp

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 <this-repo-url> leela-mcp-server
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 (or lc0-mcp --help is not provided; it's a stdio server — 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 a net at ./networks/*.pb.gz 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 (and other JSON-config clients)

Add to the client's config file (for Claude Desktop: claude_desktop_config.json):

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

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).

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.