mgz-pkmn

🌐 Project site: https://mgz-pkmn.com · 🚀 Live demo: https://mgz-pkmn.onrender.com

A toolkit for prepping Pokemon card binders for a card show: take a list of cards, look each one up across three open data sources, download images, and write an .xlsx with embedded thumbnails, current market price, and 80 / 85 / 90 / 95 % negotiation comps. Optional PDF binder, condensed binder, set-completion checklist, and JSON report alongside.

Two ways to drive it:

• CLI — ./pkmn lookup cards.txt produces xlsx + (optional) PDF + JSON; ./pkmn set-cards emits printable set ID cutouts.
• Web UI — FastAPI backend in api/ and a React + Vite frontend in web/ put the same pipeline behind a live in-browser interface with streaming results and one-click export.

The tool tries sources in this order:

1. pokemontcg.io — primary. Best coverage of English / international English releases, with TCGPlayer (USD) + Cardmarket (EUR) prices.
2. TCGdex — multilingual fallback (en, ja, ko, zh-tw, zh-cn, de, fr, es, it, pt, …). Has Cardmarket prices for many cards.
3. PriceCharting — opt-in via an explicit URL on the line. Ideal for region-exclusive products neither aggregator indexes (Chinese Gem Pack, etc.). Returns USD loose / new / graded prices.

Install

Requires Python 3.11+ and uv.

brew install uv                                   # macOS
curl -LsSf https://astral.sh/uv/install.sh | sh   # any platform

make install-cli          # CLI only — fastest
# or
make install              # CLI + API + web + pre-commit hook

Run make help for the full target list.

Quickstart

./pkmn lookup input/ --no-images \
  -o output/cards.xlsx \
  --pdf output/binder.pdf \
  --condensed-pdf output/binder-condensed.pdf \
  --checklist output/checklist.pdf \
  --report-json output/summary.json

./pkmn set-cards -o output/set-cards.pdf   # printable set ID cutouts (no input needed)

The bundled input/ directory ships four small example lists that exercise every input syntax and lookup mode the tool supports — including example-url-overrides.txt, which walks through the "paste a PriceCharting URL once and forget it" workflow. The tracked files in output/ were generated by exactly the command above. See the CLI reference for the full breakdown.

API key (optional but recommended)

The pokemontcg.io API works without a key (~1000 requests/day, 30/min) but a free key raises that to 20k/day. Grab one at https://dev.pokemontcg.io, then set it as an env var:

export POKEMONTCG_IO_API_KEY=your-key-here          # current shell
echo 'export POKEMONTCG_IO_API_KEY=your-key-here' >> ~/.zshrc   # persistent

Prefer the env var over --api-key — flags get saved to shell history.

Environment variables

Every variable the tool reads, in one place:

Variable	Purpose
POKEMONTCG_IO_API_KEY	Raises pokemontcg.io rate limits from 1k/day to 20k/day. Free key at https://dev.pokemontcg.io.
MGZ_PKMN_NO_CACHE	Disables the disk cache for the current process. The CLI's --no-cache flag sets this internally.
MGZ_PKMN_CACHE_WARN_BYTES	Threshold for the cache-size soft-warn at startup (default 50 MB, 0 disables).
XDG_CACHE_HOME	Overrides the cache root ($XDG_CACHE_HOME/mgz-pkmn). Standard XDG semantics.

See docs/cache.md → Environment variables for the full behavior of the cache-related vars.

Web UI

make install         # one-time setup
make dev-api         # Terminal 1 — API on :8000
make dev-web         # Terminal 2 — Vite dev server on :5173

Open http://localhost:5173. The Vite dev server proxies /api/* to the FastAPI server. Swagger UI lives at http://localhost:8000/docs.

Prefer not to install anything? The same UI is hosted at https://mgz-pkmn.onrender.com.

Every matched result — both in the results table and the card detail view — carries a "Buy" affordance that links out to eBay and TCGPlayer searches for that exact printing, opening in a new tab. Both are affiliate-tagged (eBay via its Partner Network, TCGPlayer via an Impact tracking redirect) and fall back to plain searches when no code is configured, so they always work.

The hosted demo can sign users in with GitHub, Google, Discord, or an email magic link when auth is enabled. See Deployment for the provider credentials, callback URLs, and production session settings. Anonymous hosted-demo lookups run against the warmed cache only; sign in to let a cache miss query the live upstream API.

The Backpack library separates the collector workflow into wishlists (cards you want), collections (cards you have), and physical binders (cards you have organized). Opening a binder shows its ordered pocket spread using the saved 4-pocket, 9-pocket, or 12-pocket layout, with the same export menu available from collection and wishlist detail views.

This is the beginning of the README. Read the rest at the original. Read the full README ↗