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.

Swipe is a Tinder-style deck for browsing the catalog one card at a time — drag or use the arrow keys to pass, save, or say "more like this," which shapes the taste-weighted deck that follows. Signed-in users get a Taste/Ownership toggle above the deck: switching to Ownership mode changes what the same three gestures do — right adds the card to your default collection, up adds it to your default wishlist, and left is "not interested" (a no-op beyond the usual no-repeat exclusion) — so a swipe session can catalog what you own instead of tuning taste. The choice is session-local; a fresh visit always starts back in Taste mode.

For deeper docs (endpoint reference, troubleshooting, architecture), see api/README.md and web/README.md.

License

Released under the MIT License.

Documentation

Reference docs live under docs/ and are mirrored to the GitHub Wiki on every push to main.

Topic	Page
Every flag and pkmn invocation pattern	CLI reference
Single-card + bulk top:N / All … syntax	Input format
pokemontcg.io / TCGdex / PriceCharting layering	Sources & coverage
Non-English / regional handling	Languages
Spreadsheet + JSON report shape	Outputs
Standard 3×3 + condensed 6×4 layouts	PDF binder
Front-of-binder set checklist	Checklist PDF
Disk cache + URL overrides	Cache
Extending pkmn with plugin subcommands + writers	Plugins
Render / Docker / production recipe	Deployment
Marketing site (Astro + Tailwind, Cloudflare Pages)	site/README.md

AI-assisted development

mgz-pkmn uses a lightweight multi-agent workflow inspired by @bobbylough's ai-pit-crew project. GitHub itself is the active-work board — issues, milestones, branches, PRs, and agent:* labels carry every piece of state. docs/roadmap.md is the planning navigator.

Agents should start with AGENTS.md, follow the shared loop in .agent-workflow.md, and expect cross-agent review before human approval.

Community

Questions, ideas, or want to share what you built? Open a thread in GitHub Discussions.

Support the project

mgz-pkmn is free and MIT-licensed. If it's saved you time at a card show and you'd like to chip in, the Buy Me a Coffee page takes one-off "buy me a pizza 🍕" tips and runs three recurring membership tiers:

	Tier	What you get
	Common$3 / month	Supporters listing, ~24h early peek at release notes, personal thank-you
	Uncommon$8 / month	Everything in Common, plus members-only Discussions, one monthly roadmap vote, name in the README Supporters section
	Holo Rare$20 / month	Everything in Uncommon, plus your logo on the marketing-site supporters strip, priority bug triage (best-effort), early-access booth in the virtual card-show pilot