retrorag
Allows locally hosted Ollama AI systems to search the RetroRAG documentation library for retro computer and console manuals, schematics, source trees, and binary information.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
RetroRAG
A Windows app (initially) for building a retrieval (RAG) library of retro computer & console documentation that Claude and other AI systems (including locally hosted ones such as Unsloth Studio, Ollama, LM Studio) can search.
Organise by system (C64, Amiga 500, ZX Spectrum, NES…) and category: user guides, programming reference, schematics, pinouts, chip datasheets, service & repair, books & magazines, emulator source, firmware & ROMs, disk & tape images.
Add PDF, GIF, JPG, PNG, TIFF, BMP, TXT, MD, HTML, RTF, Word (DOC/DOCX), Excel (XLS/XLSX), source code, ROMs, disk/tape images, ZIPs, or whole folders (e.g. an emulator's source tree). Drag & drop onto a system or category.
OCR (Tesseract) turns scans into editable Markdown. Words below a confidence threshold are marked
{?w0rd|42?}so you can find and fix them.Proofreading editor: scan on the left, text on the right. The current line and word are highlighted on the scan.
Binary files get an "info card": CRC32/MD5/SHA1, format, D64 directory listing, ZX TAP/TZX headers, Amiga ADF volume name, iNES/Game Boy/Mega Drive headers, and embedded text strings from ROMs. An AI can then answer "what's on this disk?" or "which Kickstart is this?".
Hybrid search: keyword (BM25, with hex-address normalisation so
$D020,0xD020andD020hall match) plus semantic (embeddings), merged by rank fusion.Connect AI: MCP for Claude Desktop / Claude Code (stdio); MCP over HTTP for Unsloth Studio, LM Studio, Open WebUI, Cursor and others; a REST API with OpenAPI spec; export as a Markdown corpus or JSONL.
Portable: the library is a self-contained folder using relative paths, and there's a portable mode plus a standalone
.exebuild.
Install on a PC
Option A: from source (needs Python 3.10+)
Copy this folder to the PC, but not the
.venvfolder: virtual environments only work on the PC that made them.Run
setup.bat. It creates.venv, installs packages (including the built-in embedder), checks for Tesseract, and asks whether to use portable mode.Start the app with
RetroRAG.bat.
Option B: standalone build (no Python needed on the target PC)
Run build_exe.bat on any PC that has the source set up. It produces dist\RetroRAG\ containing:
RetroRAG.exe: the app.retrorag-cli.exe: the console version, used by Claude Desktop / Claude Code and for scripting.portable.flag: settings and the default library live inside the folder.Optionally a bundled
Tesseract-OCR\folder, so OCR works without installing anything.
Copy or zip dist\RetroRAG to any Windows 10/11 PC or a USB drive and run RetroRAG.exe.
Tesseract OCR
winget install UB-Mannheim.TesseractOCR. You can also set the path in Settings → OCR, or put a Tesseract-OCR
folder next to the app. For other languages, add them in the Tesseract installer and set e.g. eng+deu in Settings.
Related MCP server: LibraryMCP
Look and feel
Windows 11-style light and dark themes using the Segoe Fluent icon set. View → Theme: Follow Windows (the default, which switches with your Windows setting), Light, Dark or Retro.
Retro turns the app into a monochrome CRT:
Everything is drawn in an 8-bit pixel font, with simulated scan lines and a screen vignette.
Scans are shown as glowing phosphor on a dark screen, and low-confidence words appear in inverse video.
Settings → Appearance picks the phosphor (green PET, amber or white), turns scan lines on or off, and can use a different font file.
The built-in font, RetroRAG Phosphor, is an original design rather than a copy of any machine's character ROM. To use a PET / VIC-20 style font you've downloaded instead (for example Kreative Software's free "Pet Me" family), choose its
.ttfthere.The font is generated by
tools/make_pixel_font.py, which needspip install fonttools. Edit the glyphs there and re-run it to change the font.
Workflow
➕ System: name, aliases (
C64, CBM 64, used for search filters), manufacturer, year, CPU, notes.Add files / Add folder (or drag & drop). Choose the category. Copy into library (the default) keeps the library self-contained. For folders you can choose which file types to include; for emulator source the default is text and code only.
Variants: a system can be a variant of another (Variant of in the system dialog, Add variant… on a system's right-click menu, or drag one system onto another). Put shared documentation on the family (e.g. ZX Spectrum) and only the extra material on each variant (48K, 128K, +3). Variants can nest, e.g. ZX Spectrum → 128K → +3.
Searching a variant (in Search test or by the AI) returns its own documents plus everything common from its family. Searching the family returns all of them.
Removing a family keeps its variants; they move up a level.
Moving a misfiled document: right-click → Move to system…, drag it onto another system or category in the tree, or change System on the Document tab and click Save details. The file moves on disk together with its OCR text, corrections and links.
🔤 Run OCR on scanned PDFs and images. PDFs with a text layer are extracted directly; only pages without text are OCR'd, and Force OCR re-does every page.
Proofread (double-click a document):
Key
Action
F3 / Shift+F3
next / previous flagged word, which is selected so you can type the fix over it
Ctrl+Enter
accept the word at the cursor (removes the marker) and jump to the next one
Ctrl+Del
delete the flagged word at the cursor (junk from a drawing) and jump to the next one
Ctrl+S
save
Ctrl+H
find / replace (with regex). Good for systematic errors, e.g.
0→Oin wordsCtrl+wheel, Ctrl+= / Ctrl+-
zoom the scan
click on the scan
jump to that line in the text
Seeing what to fix: the magnifier strip above the text shows the current line from the scan, enlarged, with the word boxed. On the page, the word flashes when you move to it, and Spotlight dims everything except the current line.
Flagged "words" in drawings: in schematics, Tesseract sometimes reads part of the drawing (a chip outline, a wire, a pin box) as a short word, e.g.
{?Fs|46?}with a box covering a whole IC. That's not text, so delete it: Ctrl+Del removes the flagged word at the cursor and jumps to the next one. More → Remove drawing shapes read as words clears a whole page. New OCR runs skip these shapes automatically (Settings → OCR → Ignore drawing shapes…). The rule of thumb: if it's real text, fix it and press Ctrl+Enter; if it's part of a drawing, Ctrl+Del.Diagram noise: More → Delete garbage lines on this page removes lines that are mostly OCR junk from diagrams and schematics. Ctrl+Z undoes it.
A ● on the editor tab means unsaved changes. Save (Ctrl+S) shows ✓ Saved.
Re-OCR page retries one page with another layout mode (11 - Sparse text suits schematics and pinouts) or another cleanup level.
Mark reviewed records that the text is proofread.
The confidence threshold (default 70%) is in Settings → OCR.
Preview pane (Document tab, right of the form). Scans with OCR or extracted text switch between Original (the page image, with page navigation) and Processed (the text the AI sees, flagged words highlighted). Plain text, source files and pictures not yet OCR'd show the original only. There's no preview for firmware/ROMs, disk and tape images, or files inside an emulator or firmware source tree.
Related documents (Document tab). Link a document to others with Link…. The available link types are: related to, pinout / schematic for, datasheet for, implements (source code), errata for, newer revision of, and part / chapter of. You can add a note to any link.
Suggest links proposes links for one document, and Index → Suggest links across library… proposes them for everything. Suggestions come from shared chip names and part numbers (SID, 6581, Z80…), register addresses (
$D400and54272count as the same), and very similar content. Tick the ones to keep; dismissed suggestions don't come back.Links matter most for documents search can't connect on its own: schematics and pinouts with little text (give them notes and tags too), emulator source vs. prose manuals, and errata or newer revisions.
⚙ Build index (F5). This runs automatically after changes unless you turn it off in the Index menu.
Try queries in Search test. You see exactly what the AI receives.
🔌 Connect AI shows ready-to-copy settings for this PC.
Marker format. {?word|NN?} means Tesseract read word with NN% confidence. Markers are always
stripped before indexing or export, so a missed one never pollutes the RAG. Each scan also gets a .ocr.json
sidecar holding every word's position on the page, which the editor uses for highlighting.
Scan cleanup. Auto (the default) OCRs each page as-is. If mean confidence is below 80%, it retries with a strong median denoise and keeps the better result. This helps a lot with speckled photocopies.
Connecting AI systems
Start the HTTP servers with ▶ Start servers in the toolbar. You can make them start with the app
(AI menu), or run them without the GUI: retrorag-cli api.
Client | How |
Claude Desktop | Connect AI → Add to Claude Desktop (edits |
Claude Code | Connect AI → copy the |
Unsloth Studio | Chat → MCP → Add custom MCP: URL |
LM Studio, Open WebUI, Cursor, Continue, Jan… | MCP over HTTP: |
Open WebUI (OpenAPI tools), scripts | REST: |
Anything else / offline | Export → Markdown corpus (YAML front matter per doc) or JSONL chunks |
MCP tools: search_docs(query, system?, category?, limit, mode), list_systems, list_documents,
read_document(doc_id, page_from?, page_to?), get_related(doc_id), get_context(chunk_id).
Each search hit carries a short related list (title, relationship, doc id), so the AI can tell the SID
chapter has a datasheet, a pinout and an emulator implementation, and fetch them only if needed.
Links also appear in each document's indexed header, in read_document output, at
/documents/{id}/related in the REST API, and in the Markdown export's front matter.
AI on a different PC (e.g. Unsloth on a GPU box): Settings → Servers → Listen on 0.0.0.0, click
Generate for an access token, restart the servers, and use this PC's IP address in the URL.
Embeddings
RetroRAG embeds text itself by default, so no Ollama, Unsloth Studio or other AI server is needed.
Built-in nomic-embed-text (the default). This is the same model Ollama serves, run inside RetroRAG on your CPU (ONNX Runtime) on Windows, macOS, Linux and Raspberry Pi.
The model (137 MB) downloads once, the first time you build an index. After that it works offline.
To prepare a machine that will be offline, run
retrorag-cli download-model. The standalone builds (build_exe.bat,build_app.sh) include the model automatically.
Other presets in Settings → Embeddings, for when you'd rather use a server:
Built-in bge-small: 34 MB, about 3× faster, but noticeably less accurate on paraphrased questions.
Ollama: nomic-embed-text, mxbai-embed-large or embeddinggemma. Run
ollama pull <model>first.Unsloth Studio: OpenAI-compatible
/v1/embeddingsathttp://localhost:8888/v1, modeldefault. Create an API key in Studio (Settings → API).LM Studio or a llama.cpp server: any OpenAI-compatible endpoint.
None: keyword search only. This still works well for register names and addresses.
If a library is set to Ollama but Ollama isn't running and nothing has been embedded yet, RetroRAG switches that library to the built-in model automatically, rather than quietly falling back to keyword-only search.
Benchmark on a laptop CPU: 317 chunks, and 10 plainly-worded questions such as "read the fire button on a game controller":
Model | Indexing speed | Right document first | Query time |
Built-in nomic-embed-text (default) | 11.6 chunks/s | 9 of 10 | 22 ms |
Built-in bge-small | 37 chunks/s | 6 of 10 | 5 ms |
Ollama nomic-embed-text (CPU) | 6.6 chunks/s | 9 of 10 | 262 ms |
Indexing speed. Embedding is nearly all of the indexing time. Chunking and keyword indexing take a fraction of a second, even for a 300-page manual.
Re-indexing after edits is quick. Unchanged chunks keep their embeddings, so saving a proofreading fix re-embeds only the chunk you changed: about 0.6 s instead of re-embedding the whole manual.
Source code is keyword-only by default. That suits identifiers and keeps big emulator trees fast. Turn on Embed source code in Settings → Embeddings if you want semantic search over code.
Progress shows chunks/s and the time remaining. For a much faster first index of a huge library, point the embeddings at a GPU machine (its Ollama or Unsloth Studio).
The model used for indexing must also be available wherever queries are answered, because RetroRAG embeds the question too. The built-in model makes that easy, since it travels with the app. Changing the model re-embeds everything on the next build.
Library layout and portability
<library>\
library.json settings (OCR, embeddings, servers) - travel with the library
retrorag.db SQLite: systems, documents, chunks, full-text index, embeddings
systems\commodore-64\
user-guides-manuals\c64_users_guide.pdf
user-guides-manuals\c64_users_guide.pdf.md editable text (OCR / extracted)
user-guides-manuals\c64_users_guide.pdf.ocr.json OCR word boxes for the editor
disk-tape-images\demo.d64 + demo.d64.md info card
emulator-source\vice-3.8\src\...
system.json manifest written when a system is removed with "keep files"All paths in the database are relative, so you can move or copy the whole library folder to another PC and open it with File → Open library folder.
Linked in place files (added with "copy" unticked) are absolute paths. Use File → Copy linked files into library before moving the library.
Portable mode (
portable.flagnext to the app) keeps app settings in.\settingsand the default library in.\Library, so the app folder plus library can live on a USB drive.After moving to a new PC or path, open Connect AI again and re-add to Claude Desktop, since the paths differ.
Removing a system
System → Remove selected system… offers:
Keep the files on disk. Originals, OCR text and your corrections stay in
systems\<name>\, with asystem.jsonmanifest of titles, tags, notes and categories. Adding a system with the same name later, or using File → Import system folder…, brings everything back, including proofread text.Delete the files too. Removes the system's folder. Linked-in-place originals outside the library are never deleted.
Import system folder also works for a system folder copied from another RetroRAG library.
Command line
Use retrorag-cli on Windows and ./retrorag-cli.sh on Linux, macOS or a Pi.
retrorag-cli stats
retrorag-cli add --system "Commodore 64" --category "Schematics" C:\scans\c64_schematic.gif
retrorag-cli ocr # OCR everything that needs it
retrorag-cli index [--all]
retrorag-cli search "raster interrupt" --system C64
retrorag-cli api # REST :8765 + MCP HTTP :8766
retrorag-cli mcp [--http] # MCP on stdio (what Claude Desktop runs) or HTTP
retrorag-cli export --markdown D:\out | --jsonl chunks.jsonl [--embeddings]
retrorag-cli settings # show library settings
retrorag-cli settings api_host=0.0.0.0 # change them (handy on a headless server)Add --library <folder> to any command to use a library other than the last-opened one.
Notes and limits
OCR quality depends on the scan. Schematics and pinout diagrams are mostly graphics, so add notes and tags to those documents: they're indexed and searchable.
Semantic search loads all vectors into memory. That's fine for hundreds of thousands of chunks. Indexing a very large source tree (e.g. all of MAME) is slow to embed, so consider adding just the relevant drivers and devices.
Read-only servers; the REST API allows any origin (CORS) so browser-based tools can call it. Keep it on 127.0.0.1 or set an access token.
Platforms
Desktop app | Headless server (MCP / REST) | Tested | |
Windows 10/11 | yes | yes | fully: GUI, OCR, embeddings, MCP, REST, standalone .exe build |
Linux x86-64 | yes | yes | server, CLI, MCP and REST tested on Debian; GUI needs Qt's system libraries (below) |
Raspberry Pi 4/5, 64-bit Pi OS | yes (slow) | yes (recommended) | all dependencies have ARM64 builds for Pi OS Bookworm |
macOS (Apple Silicon / Intel) | yes | yes | all dependencies have macOS builds; not yet run on a Mac |
32-bit Raspberry Pi OS isn't supported, because Qt and PyMuPDF don't publish builds for it.
Linux and macOS
git clone https://github.com/feralCheese/RetroRAG && cd RetroRAG
./setup.sh # creates .venv, installs packages, checks Tesseract
./retrorag.sh # starts the app
./retrorag-cli.sh --help # command line, MCP and REST serverPrerequisites:
Debian, Ubuntu or Pi OS:
sudo apt install python3 python3-venv tesseract-ocr libegl1 libxcb-cursor0.Fedora:
sudo dnf install python3 tesseract.macOS:
brew install python tesseract.
./build_app.sh makes a standalone copy in dist/RetroRAG for the machine it runs on. PyInstaller
doesn't cross-compile, so build on a Mac for Macs and on a Pi for Pis. On macOS this produces a folder with
the program inside, not a signed .app bundle.
Settings live in %APPDATA%\RetroRAG on Windows, ~/Library/Application Support/RetroRAG on macOS, and
~/.config/RetroRAG on Linux, unless you use portable mode. "Show in folder" uses Explorer, Finder, or
your Linux file manager. Without the Windows icon font, icons come from your Linux icon theme or Qt's
built-in set.
Raspberry Pi as an always-on RAG server
The best way to use a Pi is as the always-on server: do OCR, proofreading and indexing on your PC, then let the Pi answer the AI.
On the Pi (64-bit Raspberry Pi OS, Pi 4 or 5 with 4 GB or more), install the prerequisites:
sudo apt install python3-venv tesseract-ocrThen install without the GUI:
git clone https://github.com/feralCheese/RetroRAG && cd RetroRAG && ./setup.sh --serverCopy your library folder from the PC, e.g. with
rsync -a "RetroRAG Library/" pi@retropi:~/RetroRAG-Library/. The embeddings are stored inside it.The Pi only has to embed each question, using the same model the library was indexed with.
To use Ollama on the Pi:
curl -fsSL https://ollama.com/install.sh | sh, thenollama pull nomic-embed-text.Or point it at your PC's Ollama:
./retrorag-cli.sh -l ~/RetroRAG-Library settings embed_url=http://my-pc:11434.
Turn on access from the network and set a token:
./retrorag-cli.sh -l ~/RetroRAG-Library settings api_host=0.0.0.0 api_token=choose-a-long-secretThen start the server:
./retrorag-cli.sh -l ~/RetroRAG-Library apiThat serves REST on
:8765and MCP on:8766/mcp.Point Unsloth Studio, Claude Code, LM Studio and other clients at
http://retropi:8766/mcpwith the headerAuthorization: Bearer <token>.
To start it automatically at boot, save the following as /etc/systemd/system/retrorag.service, then run
sudo systemctl enable --now retrorag:
[Unit]
Description=RetroRAG server
After=network-online.target
[Service]
User=pi
WorkingDirectory=/home/pi/RetroRAG
ExecStart=/home/pi/RetroRAG/retrorag-cli.sh -l /home/pi/RetroRAG-Library api
Restart=on-failure
[Install]
WantedBy=multi-user.targetOCR and indexing on the Pi work, but they're much slower than on a PC. After adding documents on the PC,
copy the library across again (rsync) and restart the service.
Licence
RetroRAG is licensed under the GNU Affero General Public License v3.0 (see LICENSE). This matches PyMuPDF,
which RetroRAG uses for PDFs and bundles in the standalone build. The built-in RetroRAG Phosphor pixel font
is an original design and is part of this project.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Versioned documentation registry and semantic search for AI tools and coding assistants.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
Your personal library, readable by AI agents: durable snapshots, hybrid search, 46 MCP tools.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants like Claude to search and retrieve technical documentation from a local DevDocs instance for hundreds of programming languages and frameworks.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables semantic and keyword search across locally indexed PDF shelves—device manuals, meeting minutes, and scientific papers—with date, device, and author filters, returning structured citations and neighbouring passage context for a speech assistant. It also exposes shelf and document metadata, plus a reindex signal, over streamable HTTP backed by Postgres with pgvector.Apache 2.0
- FlicenseNot gradedqualityAmaintenanceExposes a local hybrid (vector + BM25) index of scattered notes, docs, PDFs, and chat logs to AI hosts like Claude Desktop, Cursor, and Cline, letting agents search and get cited answers. It publishes a set of tools, resources, and prompts so any MCP-compatible client can query that knowledge base with section-level citations.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP hosts to run hybrid vector + BM25 retrieval over a locally indexed second brain of scattered notes, docs, PDFs, chat logs, and wiki pages, returning section-level citations. It exposes 8 tools plus resources and prompts so hosts like Claude Desktop, Cursor, Cline, and Claude Code can search and ask questions of your own files.-