MTG Card Analyzer is a Node.js CLI that identifies Magic: The Gathering cards from images. It combines OCR, fuzzy name matching, and perceptual image hashes to find the likely card and printing.
It is local-first: the card-name index, image-hash cache, scan history, and optional collection data are stored on your machine by default. No MySQL server is needed for the normal workflow.
- Scans one card image at a time from the command line.
- Extracts and normalizes the card name with Tesseract OCR.
- Fuzzy-matches imperfect OCR against a local card-name index.
- Compares card or set-symbol image hashes to distinguish printings.
- Prints candidates by default, with opt-in local collection tracking.
- Records a local operations log to help diagnose difficult scans.
Scans are dry runs by default: they print results without adding anything to your collection. The local caches and operations log still update unless you disable the local cache.
You need:
- Node.js 20 or newer
- pnpm 8 or newer (the repository pins pnpm 10.13.1)
- Git and a network connection for installation and the initial Scryfall card-name seed
git clone https://github.com/dills122/MTG-Card-Analyzer.git
cd MTG-Card-Analyzer
node scripts/setup.mjs
node index.mjs scan ./test-images/PlatinumAngel.jpgThe setup script installs dependencies, creates local configuration files, and seeds the card-name
index. It is safe to run again and does not start MySQL unless you explicitly pass --with-mysql.
If the scan does not complete, check the environment before digging into individual settings:
node scripts/verify-env.mjsSee the local setup guide for setup flags and troubleshooting.
node index.mjs scan ./path/to/card.jpgYou can also omit the scan word for backward compatibility:
node index.mjs ./path/to/card.jpgCollection tracking and writes are separate opt-ins. Set both once in mtg.config.json through the
CLI:
node index.mjs config set collectionEnabled true
node index.mjs config set queryingEnabled true
node index.mjs scan ./path/to/card.jpgOr enable both for only one run:
node index.mjs scan ./path/to/card.jpg --enable-collection --querynode index.mjs log dump --limit 20
node index.mjs log stats
node index.mjs diagnosticsRun node index.mjs --help for the command list or see the
CLI reference for every command and flag.
- The image is validated and likely title regions are cropped and enhanced.
- Tesseract extracts text from several variants; the best result is normalized.
- The result is fuzzy-matched against the local card-name index.
- Candidate printings come from Scryfall and are ranked with cached or downloaded image hashes.
- Results are printed and, only when enabled, written to the selected collection backend.
OCR quality varies with lighting, focus, rotation, framing, and card layout. Images smaller than 360 by 500 pixels are currently rejected. Setup and printing lookup use Scryfall, so the scanner is local-first rather than fully offline.
| If you want to... | Read... |
|---|---|
| Install the project or fix a local setup problem | Local development setup |
| Look up commands, flags, logging, migration, or collection edits | CLI reference |
| Change settings or understand local database files | Configuration and local data |
| Understand the scan pipeline and module boundaries | Architecture |
| Add or evaluate OCR and matching fixtures | Regression testing |
| Prepare a change or pull request | Contributing |
The default NeDB backend is the recommended path. A legacy MySQL/RDS adapter remains available for existing users; its setup and migration instructions live in the local development guide and CLI reference.
After setup, run the standard local gate:
pnpm checkThat runs formatting checks, linting, type checking, and unit tests. Changes to OCR preprocessing, fuzzy matching, hashing, or print selection should also run:
pnpm test:regressionThe unit suite is deterministic and does not require live Scryfall or MySQL access. See CONTRIBUTING.md before opening a pull request.
MTG Card Analyzer is available under the MIT License.