tcg-mcp
Planned integration for eBay sold comps via the eBay Browse API and scraping, enabling historical sold price lookup for cards.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tcg-mcp look up PSA cert 12345678"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tcg-mcp
A Pokemon TCG MCP server. Looks up graded cards (PSA today, CGC/BGS stubbed), manages your owned collection in a local SQLite DB, queries pricing providers (Pokemon TCG API + PriceCharting), tracks a watchlist with target prices, and snapshots PSA pop counts so you can see trends over time.
tcg-mcp is a Model Context Protocol
server. Install it once, wire it into Claude Desktop / Claude Code / Cursor /
any MCP client, and your assistant gains 25 tools for working with PSA cert
data, your personal collection, and live market prices.
What it does — 25 tools, namespaced
PSA grading (tcg_psa_*) — cert lookup, front/back images, snapshot pop
data over time, plus a workflow tool that looks up a cert and records it as
owned in one call.
CGC / BGS (tcg_cgc_*, tcg_bgs_*) — stubs in v0.2; no public API exists
for either grader. Listed for routing parity; will route cleanly if either
grader publishes an API.
Collection (tcg_collection_*) — add raw or graded cards (or sealed
products: ETBs, booster boxes, UPCs, tins), list with filters, update cost
basis, soft-delete (mark sold) or hard-delete, attach a card to a pricing
listing, get a cost-basis summary or a live market valuation that joins
against the most recent pricing snapshots.
Pricing (tcg_pricing_*) — search a provider, get a full price quote
(top-level market/low/high plus per-variant breakdown for Pokemon TCG API,
plus per-grade levels for PriceCharting), persist snapshots into the local
DB, bulk-snapshot every attached card in one call with per-provider
rate-limit awareness, and query historical snapshots as a time series
for trend analysis.
Watchlist (tcg_watchlist_*) — add target buy prices with thesis text,
list by horizon (flip / hold / sealed), update, and close with a reason
(bought / thesis_invalidated / manual).
Meta (tcg_list_providers) — discovery tool that shows which grading +
pricing providers are enabled, what env var each needs, and what tools are
in the namespace.
For the full tool list run tcg_list_providers after install or read the
architecture doc.
Related MCP server: pokeapi-mcp-server
Prerequisites
Python 3.10 or newer (3.13 recommended).
An MCP client — Claude Desktop, Claude Code, Cursor, Continue, etc.
(Optional, for PSA tools only) A PSA Public API token — free, sign up at psacard.com/publicapi.
The server works without any tokens — Pokemon TCG API queries, collection, and watchlist tools all function on a fresh install with zero credentials.
Install
Option A — uvx (recommended, zero install)
# install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
# run the server (auto-installs the package on first use)
uvx tcg-mcp --helpOption B — pipx
pipx install tcg-mcp
tcg-mcp --helpOption C — pip
python3 -m pip install tcg-mcpOption D — from source (for contributors)
git clone https://github.com/seanlok/tcg-mcp.git
cd tcg-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest # run the test suiteConfigure
Copy .env.example to .env and fill in any tokens you have:
cp .env.example .env
$EDITOR .envOr set the env vars however your client supports it (most clients let you
specify env per MCP server in the config).
Env var | Required for | Notes |
| PSA tools | Get one — free |
| Higher Pokemon TCG API rate limit (optional) | Get one — free |
| PriceCharting tools | Paid subscription required |
| Local DB location | Default |
Wire it into your MCP client
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS),
%APPDATA%\Claude\claude_desktop_config.json (Windows), or
~/.config/Claude/claude_desktop_config.json (Linux):
{
"mcpServers": {
"tcg-mcp": {
"command": "uvx",
"args": ["tcg-mcp"],
"env": {
"PSA_API_TOKEN": "your-token-here",
"TCG_DB_PATH": "~/Documents/tcg-mcp.db"
}
}
}
}Quit Claude Desktop fully (⌘Q on macOS — closing the window isn't enough) and relaunch.
Claude Code
claude mcp add tcg-mcp -- uvx tcg-mcpThen export the tokens you have in the shell that runs claude.
Cursor / Continue / etc.
Same shape — point the client at:
command: uvx
args: ["tcg-mcp"]
env: PSA_API_TOKEN=... # optionalSmoke-test it
After wiring up the client, ask it:
"Use tcg-mcp to list providers."
You should see pokemontcg enabled, plus psa enabled if your token is
set, and stubs for the others.
Then try a real lookup:
"Search Pokemon TCG API for Charizard ex from Obsidian Flames."
"Add a 1999 Pokemon Base Set Charizard #4 (raw) to my collection — paid $250 on 2026-04-15."
"Add Charizard ex Surging Sparks to my watchlist with a target buy price of $180."
"What's my collection cost basis?"
Architecture, briefly
+----------------------+
| MCP client | Claude Desktop, Cursor, etc.
+----------+-----------+
| stdio (JSON-RPC)
+----------v-----------+
| server.py | FastMCP — tool registration, validation
+----------+-----------+
|
+-------+-------+----------------+
| | |
+--v--+ +--v--+ +----v----+
| psa | ... |pricing| | storage | SQLite — collection,
+--+--+ +--+----+ +----+----+ watchlist, pop trends,
| httpx | httpx | pricing snapshots
+--v---------------v----+ +----v----+
| PSA / Pokemon TCG | | tcg.db |
| API / PriceCharting | +---------+
+-----------------------+Provider abstractions (providers/base.py,
pricing/base.py) make adding a new grader
or pricing source a single-file change. See
docs/adding-a-provider.md.
Local SQLite database
All your personal data — collection, watchlist, pricing snapshots, pop
snapshots — lives in a single SQLite file. Default location is
~/.tcg-mcp/tcg.db. Point TCG_DB_PATH at any path you prefer.
The file format is plain SQLite, so you can inspect or back up the data directly:
sqlite3 ~/.tcg-mcp/tcg.db
.tables
SELECT subject, grade, acquisition_price FROM owned_cards WHERE status='owned';Schema is in src/tcg_mcp/storage/schema.sql.
Migrations are forward-only and idempotent (safe to run on every startup).
Known limits
PSA images only exist for cards graded after October 2021. Older slabs return an empty image list — that's the upstream API, not a bug.
PSA's
Brandfield is the closest thing to a clean "set name" in their schema. We surface it asset_name; for finer-grained set parsing, reach into the raw payload.CGC / BGS providers are stubs in v0.2. They're listed for discovery but raise
NotSupportedErrorif called. Implementation depends on either grader publishing a public API or an explicit decision to support polite scraping.Rate limits on the PSA free tier aren't publicly documented. If you see "PSA API rate limit exceeded", wait or upgrade your plan.
PriceCharting is paid-only. Without a
PRICECHARTING_TOKENthe provider is registered asdisabledand graded-card prices aren't available — but Pokemon TCG API still gives you raw market prices.
Roadmap
Standing constraint: every milestone below has a free path as the default. Paid providers (GemRate, eBay Marketplace Insights, etc.) stay optional add-ons that activate only when their key is configured.
✅ v0.3 — shipped:
tcg_pricing_snapshot_collection,tcg_pricing_get_history, rounded per-item valuation, clearer PSA 429 error message,CHANGELOG.md.✅ v0.4 — shipped: Catalog tools (
tcg_catalog_*) backed by Pokemon TCG API,tcg_collection_set_completionwith watchlist intersection, richertcg_collection_search, smart-routedtcg_pricing_get_card.v0.5 — CGC support (free path: polite scraping; optional paid GemRate).
v0.6 — BGS support (free path: polite scraping; optional paid GemRate).
v0.7 — eBay sold comps (free path: eBay Browse API + scraping; optional paid Marketplace Insights API).
See CHANGELOG.md for the full version history.
Contributing
Contributions welcome. To add a new grading or pricing provider, see
docs/adding-a-provider.md. The contract is
intentionally small: implement a Protocol method, register it conditionally
based on credentials, write a mock-httpx test.
# Run tests + lint locally
pytest
ruff check .Disclaimers
This project is independent. It is not affiliated with PSA, CGC, Beckett, The Pokemon Company, Nintendo, TCGPlayer, Cardmarket, PriceCharting, or any other organization. Each external API call is subject to that provider's Terms of Service.
License
MIT — see LICENSE.
Sources / further reading
Model Context Protocol — official site
MCP Registry — discovery
Pokemon TCG API — pricing + catalog
Available Tools
33 toolstcg_bgs_get_certARead-onlyIdempotent
BGS cert lookup — stubbed. Beckett has no official public API.
Returns a clear "not supported" error. Implementation deferred.
Inputs: params (required). Returns: result
tcg_catalog_get_setARead-onlyIdempotent
Fetch a Pokemon TCG set's metadata (name, total cards, release date, …).
Free — no API key required (Pokemon TCG API).
Inputs: params (required). Returns: result
tcg_catalog_list_cards_in_setARead-onlyIdempotent
List every card in a set (optionally filtered by rarity), with TCGPlayer market price where available. Useful for set-completion analysis and rarity-tier breakdowns.
Inputs: params (required). Returns: result
tcg_catalog_search_setBRead-onlyIdempotent
Search Pokemon TCG sets. Returns set IDs, names, release dates, totals.
Inputs: params (required). Returns: result
tcg_cgc_get_certBRead-onlyIdempotent
CGC cert lookup — stubbed. CGC has no official public API.
Returns a clear "not supported" error. Implementation deferred.
Inputs: params (required). Returns: result
tcg_collection_add_cardA
Record a card as owned in the local SQLite DB.
Returns the new card_id (a UUID) on success.
Inputs: params (required). Returns: result
tcg_collection_add_sealedA
Record sealed product as owned.
Behind the scenes, sealed product lives in the same owned_cards table
as singles, distinguished by product_type != 'single'. We insert one
row per quantity unit so cost basis and disposition track per-unit.
Returns a list of new card_ids (one per unit).
Inputs: params (required). Returns: result
tcg_collection_attach_pricingAIdempotent
Map an owned card to a pricing listing for live valuation.
After attaching, tcg_pricing_snapshot calls (using the same listing_id)
will let tcg_collection_value_with_market compute live market value
for this card.
Inputs: params (required). Returns: result
tcg_collection_getARead-onlyIdempotent
Fetch a single owned card by its card_id.
Inputs: params (required). Returns: result
tcg_collection_listCRead-onlyIdempotent
List cards in the local collection, with optional filters and pagination.
Inputs: params (required). Returns: result
tcg_collection_removeADestructiveIdempotent
Remove a card. Default is a soft-delete: status -> 'sold' and the row stays.
Pair with sold_price + sold_date to capture the disposition.
Inputs: params (required). Returns: result
tcg_collection_searchARead-onlyIdempotent
Search owned cards across subject, set_name, brand, variety, notes,
and tags — richer than tcg_collection_list's subject-only filter.
Inputs: params (required). Returns: result
tcg_collection_set_completionARead-onlyIdempotent
Compute set-completion progress for a Pokemon TCG set.
For each card in the set (optionally filtered by rarity):
Owned? Match owned_cards either by attached
pricing_listing_idequal to the catalog card'sid(precise), or as a fallback by case-insensitive subject match + card_number exact match.Watchlist hit? Cross-reference
watchlist.card_descriptorfor substring matches against the card name + set name.Missing? Sum current Pokemon TCG API market price for the gap.
Returns owned/missing counts, completion percentage, gap cost in USD, and per-card breakdown.
Inputs: params (required). Returns: result
tcg_collection_updateA
Update mutable fields on a collection card (cost basis, notes, status, ...).
Inputs: params (required). Returns: result
tcg_collection_valueARead-onlyIdempotent
Cost-basis summary across the collection.
Returns counts (owned / graded / raw / sold) and total cost basis.
For live market valuation that joins against pricing snapshots, see
tcg_collection_value_with_market.
Inputs: params (required). Returns: result
tcg_collection_value_with_marketARead-onlyIdempotent
Cost basis + live market value across the collection.
For each owned card with an attached pricing listing, we look up the
most recent pricing snapshot (matching the card's grade for graded
cards). Cards without an attachment or without a snapshot land in
unpriced_count so you know what's missing.
Run tcg_pricing_snapshot periodically to keep the join fresh.
Inputs: params (required). Returns: result
tcg_list_providersARead-onlyIdempotent
Show which grading / pricing providers are enabled in this process.
Useful as a first call when introspecting the server's capabilities.
Inputs: params (required). Returns: result
tcg_pricing_getARead-onlyIdempotent
Fetch the full PriceQuote for one listing on the chosen provider.
Returns top-level market/low/high (USD or EUR depending on provider),
a variants map (Pokemon TCG API), and a graded_levels list
(PriceCharting). The full provider payload lives in raw.
Inputs: params (required). Returns: result
tcg_pricing_get_cardARead-onlyIdempotent
Smart-routed price lookup. One call, the right provider(s) under the hood.
Strategy:
Always queries Pokemon TCG API (free) — gives raw/ungraded market.
If
gradeis provided AND PriceCharting is enabled (token set), ALSO queries PriceCharting for the graded price level.prefer_provideroverrides routing entirely.
Designed so an agent can ask "what's Charizard ex Surging Sparks worth" without knowing which provider to call first.
Inputs: params (required). Returns: result
tcg_pricing_get_historyARead-onlyIdempotent
Return the time series of pricing snapshots saved for one listing.
Useful for answering "is PSA 10 trending up?" or "what was Charizard ex
SIR worth a month ago?" — but only works for listings you've snapshotted
via tcg_pricing_snapshot or tcg_pricing_snapshot_collection.
Returned snapshots are oldest-first.
Inputs: params (required). Returns: result
tcg_pricing_searchARead-onlyIdempotent
Search a pricing provider for matching products.
Returns a list of CardListing rows. Use tcg_pricing_get afterward with
one of the listing_ids to fetch full price data.
Inputs: params (required). Returns: result
tcg_pricing_snapshotB
Fetch a price quote and write it as a row in the pricing_snapshots table.
For graded providers (PriceCharting), every graded_level becomes its own snapshot row (so you can later track PSA 10 vs PSA 9 separately). The raw provider payload is stored on the FIRST row only to avoid bloat.
Inputs: params (required). Returns: result
tcg_pricing_snapshot_collectionA
Walk the collection and snapshot every owned card with an attached pricing listing, respecting per-provider rate limits.
Skips cards whose most recent snapshot is younger than max_age_hours
so repeated calls don't burn API quota redundantly. One card failing
does not abort the rest — failures are reported per-card.
Returns a summary with counts (snapshotted / skipped_recent / failed) and a per-provider breakdown.
Inputs: params (required). Returns: result
tcg_psa_add_to_collectionA
Look up a PSA cert AND record it in your local collection in one step.
Workflow tool — combines tcg_psa_get_cert with tcg_collection_add_card.
Looks up the cert at PSA, normalizes the response, and writes a row into
the local SQLite DB with your cost basis. Returns the new card_id.
If you've already added this exact cert, returns an error rather than
duplicating — use tcg_collection_update to change cost basis.
Inputs: params (required). Returns: result
tcg_psa_get_certARead-onlyIdempotent
Look up a single graded card by its PSA cert number.
Returns card metadata (year, brand, set, card number, subject, variety), grade (label + numeric), and population data (count at this grade, count graded higher) when PSA exposes them.
Inputs: params (required). Returns: result
tcg_psa_get_imagesARead-onlyIdempotent
Fetch front/back image URLs for a PSA graded card.
NOTE: PSA only attaches images to cards graded after October 2021 — older slabs return an empty list with no error.
Inputs: params (required). Returns: result
tcg_psa_pop_trendARead-onlyIdempotent
Return the time series of pop snapshots we've captured for a card spec.
Useful for answering "Has PSA 10 pop for this card grown a lot?" — but
only works for specs you've snapshotted via tcg_psa_snapshot_pop.
Inputs: params (required). Returns: result
tcg_psa_snapshot_popA
Capture today's PSA pop data for the spec backing this cert.
Looks up the cert via PSA, extracts (SpecID, grade, total_at_grade,
population_higher), and inserts a row into pop_snapshots. Repeat over
time and tcg_psa_pop_trend will surface the trajectory.
Inputs: params (required). Returns: result
tcg_watchlist_addB
Add a card to the watchlist with a target buy price + thesis.
Returns the new watchlist_id.
Inputs: params (required). Returns: result
tcg_watchlist_closeADestructiveIdempotent
Mark a watchlist entry closed (bought / thesis_invalidated / manual).
Inputs: params (required). Returns: result
tcg_watchlist_getARead-onlyIdempotent
Fetch a single watchlist entry by id.
Inputs: params (required). Returns: result
tcg_watchlist_listCRead-onlyIdempotent
List watchlist entries with optional horizon filter.
Inputs: params (required). Returns: result
tcg_watchlist_updateC
Update mutable fields on a watchlist entry.
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Each tool has a clear, distinct purpose grouped by domain (catalog, collection, pricing, PSA, watchlist). For example, tcg_collection_list and tcg_collection_search are differentiated by filter scope. Stubbed tools are explicitly marked as not implemented, avoiding confusion.
All tools follow a consistent tcg_<category>_<action> pattern in snake_case (e.g., tcg_catalog_get_set, tcg_collection_add_card). Even combined tools like tcg_psa_add_to_collection adhere to the convention. The naming is predictable and uniform.
33 tools cover a broad domain (catalog, collection, pricing, grading, watchlist) without being excessive. While some specialization exists (e.g., separate value vs value_with_market), the count is reasonable for the feature set and not overwhelming.
The tool surface covers the full lifecycle: catalog search, collection CRUD, pricing with history and snapshots, PSA grading lookup and population trend, and watchlist management. Gaps like BGS/CGC are acknowledged via stubbed tools. No dead ends hinder an agent's workflow.
Maintenance
Related MCP Connectors
Connect to your CollectHolo Pokémon card collection. Check your portfolio value, look up card, sealed and graded (PSA/BGS/CGC) prices from Cardmarket, TCGplayer, eBay, Goldin and Fanatics, search the catalog in six languages, import a whole collection from a spreadsheet, and add or update holdings in plain language. Every change asks for confirmation.
Values graded sports cards and Pokémon/TCG slabs by grade from real sales. Free, read-only.
Unlock the power of real-time cryptocurrency data with our Crypto Price Insights MCP server.
Remote MCP server for saving, searching, syncing, and managing Teak cards.
Related MCP Servers
- AlicenseAqualityBmaintenanceTCG oracle as an MCP server: 22 focused tools. Search 455K+ trading cards, live market snapshots, AI grading and grade-or-not decisions, conformal-calibrated price forecasts with a public accuracy scorecard, card-collateral loan terms, fantasy and sports souls leagues. Every root proven on-chain. Same tools as the hosted endpoint at mcp.the-undesirables.com, over stdio; no keys.2230 PyPI4Business Source 1.1
- FlicenseNot gradedqualityDmaintenanceMCP server providing tools to look up Pokémon, moves, abilities, items, locations, evolutions, and more from the PokéAPI via natural language.2-
- AlicenseNot gradedqualityBmaintenanceUnified MCP server for Magic: The Gathering, combining Scryfall card search and pricing, EDHRec commander recommendations, Archidekt deck reading, and decklist validation into a single service.MIT
- AlicenseAqualityCmaintenanceMCP server for Magic: The Gathering card prices, deck analysis, sealed product EV calculations, and investment insights, powered by live data from 5 vendors covering 99K+ cards.2152 PyPIMIT