pgnify

pgnify converts chess books, PDF and EPUB, into PGN with the AI assistant you already use.

It is an MCP server. Your assistant reads the book and decides what it holds. pgnify gives it tools that read the book's pages and diagrams, check every move with python-chess, and write the PGN, along with instructions for a faithful conversion: every game, exercise and solution, the variations the book gives in its prose, and the book's commentary word for word. Afterwards, pgnify report tells you what it could verify and what a person should look at, without any model.

pgnify has no model of its own and needs no API key: your assistant brings the model.

pgnify is alpha software. It is not on PyPI yet, so you install it from this repository.

Install

You need uv.

uv tool install "pgnify @ git+https://github.com/dawsonbooth/pgnify"

That gives you the pgnify command, about 250 MB installed.

To read diagrams too, install the diagram reader instead, about 1.1 GB with PyTorch, and then fetch its weights once:

uv tool install "pgnify[diagrams] @ git+https://github.com/dawsonbooth/pgnify"
pgnify setup    # downloads 860 MB once, and keeps 310 MB in ~/.cache/pgnify

pgnify setup --from DIR copies the weights from a folder that already holds them, instead of downloading them. Either way, every file is checked against the SHA-256 pinned in pgnify. On Linux, PyTorch from PyPI also installs NVIDIA's CUDA libraries, a few more gigabytes; PyTorch's own installation guide shows how to install a CPU-only build instead.

Without the diagram reader, the other tools work as usual, and the assistant is told that the reader is missing whenever it tries to read a diagram.

Connect it to your assistant

Choose two folders:

• --books: a book, or a folder of books. pgnify reads nothing else.
• --out: a folder of its own for the PGN files. pgnify writes nothing anywhere else.

Claude Code:

claude mcp add --scope user pgnify -- pgnify serve --books ~/Chess/Books --out ~/Chess/PGN

Claude Desktop: add pgnify to claude_desktop_config.json, found under ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows. Use full paths, including the path to pgnify itself, which uv tool dir --bin prints:

{
  "mcpServers": {
    "pgnify": {
      "command": "/Users/you/.local/bin/pgnify",
      "args": ["serve", "--books", "/Users/you/Chess/Books", "--out", "/Users/you/Chess/PGN"]
    }
  }
}

Any other MCP client: add a stdio server whose command is pgnify serve --books BOOKS --out OUT.

If the client says the server failed to start, run the same command in a terminal: pgnify says why it stopped, for instance that there is no book at the path given. The MCP Inspector lets you try the tools by hand:

npx @modelcontextprotocol/inspector pgnify serve --books ~/Chess/Books --out ~/Chess/PGN

Give it the instructions

The conversion instructions matter as much as the tools. They are one text, which your assistant can get in three ways:

• As the server's prompt. pgnify offers the MCP prompt convert, which asks for the book and the part to convert. In Claude Code it is the command /mcp__pgnify__convert; other clients that support prompts list it among pgnify's.

• As a skill. In Claude Code:

  /plugin marketplace add dawsonbooth/pgnify
  /plugin install pgnify@pgnify
  

  The plugin holds only the skill, pgnify-convert. It does not register the server, so you always choose the folders yourself. For another assistant that reads skills, copy this repository's plugin/skills/pgnify-convert/ into its skills folder.

• As plain text. pgnify instructions prints them, to paste into any assistant.

Then ask for the part you want, for instance: "Convert Chapter 5 of Workbook.epub, the rook forks with their solutions, into PGN." You can also ask for an output convention, such as one game for each exercise with its solution's moves, or a numbering for the Round tag. Without one, the assistant follows the book's own structure and says in its notes which convention it chose.

Ask for one part at a time, such as a chapter or a section: that is how pgnify has been tried so far.

What you get

In the --out folder:

• NAME.pgn: the games. Unless the assistant gives another name, NAME is the book's.
• NAME.notes.md: the assistant's own account of what it could not resolve, what it left out and the conventions it chose, when it gave one.
• .pgnify/: the server's working folder. It holds a log of every tool call and, for each book apart, the pictures it extracted and the games it saved.

Check the result

pgnify report ~/Chess/PGN            # writes report.md and report.json there
pgnify report ~/Chess/PGN --images   # also each doubtful diagram beside its game's position
pgnify check games.pgn --book Workbook.epub

The report keeps three things apart:

• Verified problems: mechanical facts that need fixing, such as an illegal move, a FEN that is no legal position, a result the game contradicts, or text a PGN reader would drop.
• Possible issues, for a person to judge. These include squares marked uncertain, a diagram read with doubts or never read, a diagram whose position no game reaches, comment text not found word for word in the book, a passage given twice, a game the assistant built and never saved, and the tools' errors.
• The model's own account: its notes, quoted as it gave them and not verified.

A report without verified problems does not mean the conversion is complete or faithful. Without a reference, pgnify cannot tell whether every game, exercise, variation or passage of the book was found; it reports only what it can check. Absent or inaccurate notes from the assistant do not mean that either. Compare the PGN with the book where it matters.

pgnify check and pgnify report exit with status 1 when they find a verified problem.

Security considerations

• What pgnify reads. Only the PDF and EPUB files at --books, in that folder and its subfolders. It skips hidden files and folders, and any link that leads outside the folder, to a hidden file, or to anything but a PDF or EPUB. The assistant names a book by its name within the folder, never by a path.
• What it writes. Only into --out: PGN and notes files under plain file names, and its working folder .pgnify/. It never writes through a link, and never over a notes file it did not write. It never replaces a file it did not write in the same session from the same book, unless the assistant asks it to.
• Each book apart. A book's saved games, pictures and diagram readings stay in a working folder of that book's own, so that two books served together cannot mix them up.
• Errors. Error messages show <books> and <out> in place of your folders' paths.
• Network. The server makes no network connections. pgnify setup downloads the weights from GitHub only when you run it without --from.
• These are pgnify's own checks, not a sandbox. The server and its diagram reader run as you, with your rights. A flaw in pgnify, or in a library it uses to read a book, could reach anything you can. Point --books at a folder that holds only books, and --out at a folder for pgnify alone, and give it only files you would open in any other reader.
• What your assistant sees. Whatever the tools return goes to your assistant, and through it to its model provider: the pages the model reads and the text it searches for. pgnify's tools return no pictures, only the positions the diagram reader reads from them, though an assistant with file tools of its own could open the pictures pgnify extracts into --out.

Books and copyright

pgnify is meant for converting books you own, for your own study. A PGN made with it holds the book's commentary word for word, so treat it as you would a copy of the book, and don't share it unless you have the right to. pgnify never downloads, shares or publishes books. This repository holds none but its own small test book, written for the tests and dedicated to the public domain.

Experimental: source-backed spans

pgnify serve --spans lets build_pgn copy a comment from the book's text by its page and line, instead of the model retyping it. It is off by default until a run shows a model using it well. On a scanned book, it copies whatever misreadings the text layer has.

Commands

PGNIFY_CACHE changes where pgnify setup keeps the weights, by default ~/.cache/pgnify. PGNIFY_WEIGHTS names a folder that already holds them.

Development

git clone https://github.com/dawsonbooth/pgnify && cd pgnify
just sync      # install the package and the dev tools
just check     # ruff, ty and the tests
just models    # the diagram reader and its weights; just models --from DIR copies them
just test -m live    # the tests that read diagrams

• docs/package-design.md is this package's design.
• docs/poc.md records the proof of concept that led to it, and its findings.
• experiments/ holds the evaluation suite: it runs a client through the packaged server on parts of books, then scores the PGN against reference PGNs. The books and the references are kept out of this repository, and so are the runs.

Licence

pgnify is free software under the GNU Affero General Public License, version 3 or later, in LICENSE, because it uses PyMuPDF (AGPL-3.0) and python-chess (GPL-3.0-or-later). The diagram reader includes code from Chess_diagram_to_FEN, under the MIT licence. Its weights are downloaded from that project's release and never distributed with pgnify. NOTICE lists the third-party code and the dependencies with their licences.