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.
  • 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.
  • Library — importing from Lichess, Chess.com, FICS and PGN, syncing on a clock, exporting, backing up, resetting.
  • Analysis — coverage, quick and deep passes, Maia levels, what counts as a blunder.
  • Engines is the next entry in the sidebar; it is written up under Operate, in Engines.
  • Your AI assistant — connecting an MCP client and what it can ask.
  • Settings — language, theme, board preferences, shortcuts, 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 three roles, capacity.
  • Remote runners — running 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.