Skip to content

Blunderbase

Blunderbase is a personal chess database. It imports your games from Lichess, Chess.com, FICS and PGN files, runs Stockfish over every one as it arrives, and optionally asks Maia what a human of your rating would have played instead. Everything lives in one SQLite file that you own: your games, the analysis, your notes, your saved lines and your statistics.

The same library is readable three ways. The web app is the board, the games list, the explorer and the statistics. Blunderbase includes no AI of its own, but it serves MCP, so the assistant you already use in your editor or chat client can read the identical data and answer from your games rather than from generalities. And the whole thing is one process on one port, which is why a deployment is a single container, a single desktop application, or a single command.

Guide

For everyday use.

One chapter per entry in the app's sidebar, in the sidebar's order.

  • Getting started — the first hour: connect an account, import, analyse.
  • Dashboard — ratings, worst recent moments, recent games, the analysis queue, the trends.
  • Games — the filter bar, saved cuts, sorting and paging, acting on several games, deleting.
  • Analysing a game — the board, the evaluation graph, engine lines, variations and move classifications.
  • Collections — the groups you keep, their records and rules, and putting games in and taking them out.
  • Explorer and repertoire — your own opening tree, the Lichess reference databases and the repertoire.
  • Statistics — what the numbers count and how to slice them.
  • Notes — notes on positions, games and variations.
  • Live — the board an MCP client drives, and saving a moment off it.
  • Correspondence — the games you are in the middle of: deadlines, the tree of candidate moves, finishing one. Off until you switch it on.
  • Library — importing from Lichess, Chess.com, FICS and PGN, syncing on a clock, exporting, backing up, resetting.
  • Analysis — coverage, the import pass and asking for more, Maia levels, what counts as a blunder.
  • Compute is the next entry in the sidebar, Engines and Machines; both are written up under Operate, in Engines and Machines.
  • Your AI assistant — connecting an MCP client and what it can ask.
  • Settings — the settings menu's language, appearance and keyboard shortcuts, the Hide engine switch, board preferences, the tour.

Operate

For whoever runs the installation.

  • Install — Docker, the desktop applications, first run, signing in.
  • Deploy — reverse proxy and TLS, the public URL, read-only mode.
  • Engines — Stockfish and Maia, the two roles, what a process costs.
  • Machines — how much runs at once, and engines on another machine.
  • Configuration — every environment variable.
  • Command line — every command and flag.
  • Backup and restore — PGN export, database backups, restoring.

Blunderbase is free software under the AGPL-3.0-or-later. The source, the sample compose files and the issue tracker are at github.com/philphilphil/blunderbase.