@pokemontcgapi/mcp
OfficialThis MCP server lets an agent query the Pokémon TCG catalogue, prices, reference data, sets, artists, catalogue coverage, and identify cards from photos.
Search cards by name, set, print region, rarity, artist, or release window; returns one row per printing with set, rarity, illustrator, and euro price index.
Fetch 1–100 cards by printed or legacy ID in one call, optionally with localized names and full price lists.
Get every current price observation for a card, including source, basis, printing, condition, grading,
as_of, and sample size; optionally filter by currency.List sets with code, series, region, release date, and total; filter by name, region, series, or release dates.
Retrieve exact closed vocabularies for types, supertypes, subtypes, and rarities before filtering.
List illustrators and how many cards each has drawn; filter by artist name.
Check live catalogue coverage/status, including which data is explicitly missing, such as deck legalities.
Identify a Pokémon card from a base64 photo and return ranked candidates; optional set/region restriction resolves reprint ties.
All exposed tools are read-only; most require
PTCG_API_KEY, and image identification is non-idempotent and credit-consuming.
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., "@@pokemontcgapi/mcp Show me Charizard cards from Japanese sets with prices"
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.
@pokemontcgapi/mcp
An MCP server for the Pokémon TCG API at pokemontcgapi.com. It gives an agent thirteen tools over the whole catalogue: international, Japanese and Simplified Chinese print lines, card names in eight locales, illustrators, images, and prices that carry their source, basis, grade and sample size. The current counts are live at /v1/status and broken down on coverage.json.
Unofficial. Not produced, endorsed, supported by or affiliated with Nintendo, Creatures Inc., GAME FREAK inc. or The Pokémon Company International. Pokémon and all related marks are trademarks of their respective owners.
Get a key
Generate the Idempotency-Key once per signup and keep it with the request body:
IDEM=$(uuidgen)curl -s -X POST "https://api.pokemontcgapi.com/v1/accounts/free" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEM" \
-d '{"email":"you@example.com"}'Lost the response? Repeat the exact same request (same Idempotency-Key, same body byte for byte, same network: same public IPv4 or the same IPv6 /64) within 24 hours and the response comes back, if stored, secret included; it is the original response, so a key rotated or revoked since then is not revived. A new Idempotency-Key for the same email returns 409 ACCOUNT_EXISTS; the same key with a different body returns 409 IDEMPOTENCY_CONFLICT.
We store only a hash of the key; the signup response is kept for 24 hours so the same request can be replayed. Save data.key.secret now.
If replay is unavailable, sign in and rotate the key, or use /v1/accounts/recover with an already verified email to get a new secret.
The key comes back in data.key.secret. Confirming the address we email raises the trial from
80 to 800 credits, and the trial ends 30 days after signup. Paid plans start at 29 EUR a month:
pricing.
Related MCP server: Pokemon MCP Server
Install
Claude Code, as a plugin. It asks for the key once, keeps it in secure storage, and adds a skill that tells Claude how to read the price rows:
/plugin install pokemontcgapi --marketplace pokemontcgapi/mcp-serverClaude Code, the server alone:
claude mcp add pokemontcgapi --env PTCG_API_KEY=your-key -- npx -y @pokemontcgapi/mcpClaude Desktop — claude_desktop_config.json:
{
"mcpServers": {
"pokemontcgapi": {
"command": "npx",
"args": ["-y", "@pokemontcgapi/mcp"],
"env": { "PTCG_API_KEY": "your-key" }
}
}
}Cursor — .cursor/mcp.json:
{
"mcpServers": {
"pokemontcgapi": {
"command": "npx",
"args": ["-y", "@pokemontcgapi/mcp"],
"env": { "PTCG_API_KEY": "${env:PTCG_API_KEY}" }
}
}
}VS Code — .vscode/mcp.json. Note the top-level key is servers, not mcpServers, and inputs
keeps the key out of the committed file:
{
"inputs": [
{ "id": "ptcg-key", "type": "promptString", "description": "pokemontcgapi key", "password": true }
],
"servers": {
"pokemontcgapi": {
"command": "npx",
"args": ["-y", "@pokemontcgapi/mcp"],
"env": { "PTCG_API_KEY": "${input:ptcg-key}" }
}
}
}Environment: PTCG_API_KEY, needed by twelve of the thirteen tools, and PTCG_BASE_URL (defaults to
https://api.pokemontcgapi.com). Node ≥ 20. The exception is ptcg_get_reference, which reads a
public route. ptcg_get_catalogue_status is not an exception: it starts on the public /v1/status
and then reads one set per print region, which needs the key. Without it the server starts and lists
its tools, then those twelve calls come back asking for it.
The tools
Thirteen tools, not one per endpoint. tools/list sits in the model's context on every turn, so the
whole surface is about 13 KB, and each tool is shaped like a question rather than like a route —
the model does not have to chain four calls to answer one thing.
Tool | Answers |
| "Charizard cards from Japanese sets", by name, set, region, rarity, artist or release window |
| Up to 100 ids in one call; |
| Every current observation for a card, with printing, grade, |
| "Every Japanese set released in 2024" |
| The exact strings for types, supertypes and rarities, so filters are not guessed |
| Illustrators and how many cards each drew |
| What the catalogue does and does not contain, measured live |
| Booster boxes, packs, ETBs, tins, blisters and collections by name, set, kind or language, with the languages each exists in and its euro index. 1 credit per 50 rows |
| Every current observation for one sealed product, with the language the box is printed in and its |
| Photo of one face to ratios, uncertainty and geometry. 25 credits; needs-review without ceilings is expected |
| Centering-only ceilings from known face/axis ratios. 1 credit |
| PSA/BGS/CGC/SGC thresholds, source status and URLs. 1 credit |
| "Which card is this a photo of?" — ranked candidates, and an explicit refusal when reprints share the artwork. 25 credits a call, and included from the Growth plan up |
Every tool is annotated readOnlyHint: true and destructiveHint: false. Nothing here writes.
ptcg_identify_card_from_image and the three centering tools are marked idempotentHint: false:
each invocation consumes credits. Do not retry paid work automatically.
Centering is included on Growth and higher; Developer is excluded. A verified Free trial includes 5 measure and 5 confirm calls, independently. Grade and standards have no separate trial call counter. Measure accepts base64 image bytes, explicit front/back face, optional standard/small card_size and corrected corners (TL, TR, BR, BL in EXIF-oriented pixels reduced to longest edge <=2560 px). It returns ratios, uncertainty and editable geometry; needs-review with null ceilings is expected. After correcting corners with another measure, a person checks or moves cut and print lines in the app. Grade ceilings arrive after that app calls confirm, or from known ratios through grade.
There is deliberately no confirm tool. An assistant cannot assert that a person reviewed the lines. Only the app collecting that person's explicit acceptance may send confirmed_by: person. Always display ceiling from centering alone, not a prediction of the final grade. Never label a result verified or certified. Keep source status, incomplete flags and uncertainty visible. See the two-step guide.
Commercial refusals put next_step.handoff on the first line of the tool result, followed by the API message and complete details. Show that sentence and its URL to the account owner verbatim and do not retry. The owner completes checkout, email verification or the contact step. CARD_ALLOWANCE_EXCEEDED is one of them: the period has retrieved its distinct-card allowance (1,000 for the trial, 30,000 a month on Developer); cards already retrieved keep answering, new ones need the next period or Growth.
Importing a card catalogue
For a complete card import, use the REST API directly:
GET /v1/cards?limit=250&orderBy=id, then follow links.next verbatim. The flat list fills pages
across set boundaries and uses fewer requests than a separate card loop for every set.
Add include=translations for names at the plain catalogue cost. Priced includes have separate tariffs.
For a single print region, add q=set.region:JP or q=set.region:CN; lang only selects a name translation.
Use /v1/sets/{code}/cards when you need a particular set and /v1/sets?region=JP to browse set metadata.
The quickstart contains both
paging loops and dated measurements. The
migration guide explains how to capture
a change feed watermark before importing and maintain the replica afterwards.
The MCP search tool is intended for bounded interactive searches; its region argument is sent to
the API as set.region:JP (or CN, WEST), so a Japanese search reads Japanese rows only. Use REST
for a complete import.
What this API does not have
The last tool exists because of this section, and it returns these facts from a live call rather than leaving a model to infer them:
No Korean cards. Zero
KRsets and zerokotranslations. The print region and the locale are modelled in the schema and carry no data, so filtering on them returns an empty result, not an error.Card game text is English, and uneven.
attacks,abilities,weaknesses,resistances,subtypes,retreat_cost,rulesandflavor_textcarry rows since 3 September 2026, on the 20,725 Western printings. Measured on 16 September 2026 against 57,450 cards:attackson 29.9% of the whole catalogue and 82.9% of the Western part,subtypes35.0%,weaknesses28.0%,flavor_text17.9%,abilities7.0%,rules5.1%. Japanese and Chinese printings carry none, so a nullattacksmeans we do not hold it, never that the card has no attack.No format legalities. The card object carries no
legalitiesfield, andlevelis empty. If the question is about deck legality, this API cannot answer it.
All three are measured, dated in the source, and repeated verbatim in the tool descriptions, so an agent is told before it calls rather than after.
Reading prices correctly
There is no printing filter. First Edition, Unlimited, holofoil, reverse holofoil and graded rows all
come back together, so read printing, condition and grading on each row rather than taking the
first number. basis separates GUIDE (published upstream) from DERIVED (computed by us);
PTCG_INDEX is our own composite in EUR and carries sample_n. Every observation has an as_of
date and is delayed by at least a day — never quote a price without it.
What the plan withholds is named rather than hidden: graded and non_english_locales for a trial
key, graded on Developer, nothing from Growth up. The API says so in meta.withheld on the prices
route, in the X-Plan-Withheld header when prices ride on a card, and in a top-level withheld
field on the batch. So a card with no graded rows may be the plan speaking, not the catalogue.
For ptcg_get_cards, the API's missing field is authoritative when present, including its
suggested_id values. The tool keeps its existing missing array of strings and adds
missing_details, an array of { id, suggested_id? }; the text also shows each suggestion.
If the API omits missing, the tool falls back to comparing requested ids with returned id
and legacy_id, ignoring case and repeated ids. This supports older API versions without
another request, but cannot discover their unreported canonical-set collisions or suggestions.
The current API omits missing when every id resolves, so that fallback then returns an empty array.
ptcg_get_card_prices reads a card with its prices, so the exclusions arrive in that header.
Sealed products
/v1/sealed carries booster boxes, booster packs, elite trainer boxes, tins, blisters and
collections across the international, Japanese and Simplified Chinese lines. Each product carries
languages, the languages it physically exists in; the Simplified Chinese line, 273 products added
on 30 October 2026 in the cn- sets, carries ["zh"]. The API has no language filter on that list,
so ptcg_search_sealed with language scans pages of 100 at 2 credits each, keeps the rows whose
languages contain it, and says when it stopped before the end of the catalogue. Without language
it is one page, 1 credit per 50 rows, cursor included.
ptcg_get_sealed_prices reads the product (1 credit) and then its quotes (2 credits). Sealed rows
carry no condition, printing or grading; locale is the language the box is printed in, and the
Chinese line carries Cardmarket LOW and TREND under zh. index is the catalogue price of the
product in euro with its date, the same index_eur as on the product row, with sample_n null and
by_locale empty, because the composite is computed for cards only. Rows under a locale other than
en follow the plan rules of the cards, and the tool names them in the same withheld line.
Context discipline
Results are capped at 50 rows regardless of what the API allows, sent as aligned tables rather than JSON, with a compact field projection. A table is shorter than the same rows as JSON because the keys are not repeated on every row; we do not publish a percentage, because we have no reproducible measurement to show next to it. Truncation is always announced along with the cursor to continue. Price rows are the one thing never truncated.
Protocol
Built on @modelcontextprotocol/server v2, which negotiates the
2025-11-25 revision and accepts clients
down to 2024-10-07. stdio transport.
The revision is the library's, not a claim of our own: SUPPORTED_PROTOCOL_VERSIONS in
@modelcontextprotocol/server@2.0.0 tops out at 2025-11-25, so a client that asks for anything
newer is answered with that. Verified against the published package, not read off a changelog.
Also available
TypeScript SDK, zero runtime dependencies:
@pokemontcgapi/sdk— sourceDocs: pokemontcgapi.com/docs
Coverage, measured live: pokemontcgapi.com/coverage
Build from source
npm ci
npm run typecheck
npm run buildNode >= 20. npm test runs the unit tests in tests/. What CI enforces is that the package
typechecks and builds on both Node 20 and Node 22, and that npm pack produces
the file list the registry is meant to receive.
This package is developed inside the private monorepo that runs pokemontcgapi.com and mirrored here on each release, so a merged pull request travels back by hand rather than by merge button. That is not a reason to send patches elsewhere — open the issue or the PR here, it is the address that gets read.
Licence
MIT. Data served by the API carries per-source redistribution terms — see pokemontcgapi.com/legal/attribution.
Available Tools
8 toolsptcg_get_card_pricesGet prices for a Pokémon cardARead-onlyIdempotent
Every current price observation for one card, each with its source, basis, printing, grade, sample size and the day it is for. There is no printing filter: 1st Edition, Unlimited, holofoil, reverse holofoil and graded rows all come back together, so you must read printing, condition and grading on each row rather than taking the first price. basis distinguishes GUIDE (a figure published upstream) from DERIVED (computed by us). PTCG_INDEX is our own composite in EUR and carries sample_n. Every observation carries as_of and is delayed by at least a day — never quote a price without its as_of date and its source.
Inputs: id (required), currency.
ptcg_get_cardsGet Pokémon cards by idARead-onlyIdempotent
Fetch one or many cards by id, in a single call. Ids are the printed coordinate — set code, dash, collector number, e.g. "bs-4" — and the alternate legacy id ("base1-4") resolves on the same route. Ids that do not exist are omitted from the result; compare requested against found. Card game text is present since 2026-09-03, in English, and unevenly: attacks on 33% of the catalogue, subtypes on 38%, weaknesses on 31%, flavor_text on 20%, abilities on 8%, rules on 6%. It sits on the 20,725 Western printings, so read against those alone attacks is on 83% of them, while Japanese and Chinese printings carry none. Check the field on the card in hand rather than assuming: a null attacks means we do not hold it, never that the card has no attack. Still empty for every card: level, and legalities — deck legality is a question this API cannot answer, so say so rather than inferring it.
Inputs: ids (required), lang, include_prices.
ptcg_get_catalogue_statusWhat this catalogue actually coversARead-onlyIdempotent
Live counts and coverage for the catalogue: sets per print region, card total, which locales carry card names, and which data is explicitly NOT present. Call this before telling a user what the API can and cannot answer.
Inputs: no named parameters.
ptcg_get_referenceList the closed vocabulariesARead-onlyIdempotent
The exact strings the catalogue uses for types, supertypes, subtypes and rarities. Call this before filtering on a rarity or a type rather than guessing the wording — "Rare Rainbow" and "Rainbow Rare" are not the same string, and only one of them matches.
Inputs: vocabulary (required).
ptcg_identify_card_from_imageIdentify a card from a photoARead-only
Recognise a Pokemon card from a photograph and return ranked candidates. Use this instead of guessing from what you see in an image: reprints share their artwork, so visual identification alone cannot name a printing, and this tool says so when it cannot. Costs 25 credits per call against 1 for a lookup — do not call it in a loop. Pass set or region when the user has told you either.
Inputs: image_base64 (required), set, top_k, region.
ptcg_list_artistsList card illustratorsARead-onlyIdempotent
Illustrators with the number of cards each has drawn, deduplicated across 30 years of printings. Use the returned name with the artist argument of ptcg_search_cards to get their cards.
Inputs: name, limit, cursor.
ptcg_list_setsList Pokémon TCG setsARead-onlyIdempotent
Every set with its code, series, print region, release date and printed total. One call answers questions like "every Japanese set released in 2024". Print regions are WEST (176 sets), JP (379 sets) and CN (60 sets, Simplified Chinese), measured 2026-08-27. Japanese sets are not translations of Western ones: they have their own boundaries, their own numbering and their own release dates, so a Japanese set and its international counterpart are two different rows.
Inputs: name, limit, cursor, region, +4 more.
ptcg_search_cardsSearch Pokémon cardsARead-onlyIdempotent
Search the Pokémon TCG card catalogue by name, set, print region, rarity, artist or release window. Returns one row per printing with its set, rarity, illustrator and euro price index. Print regions are WEST (176 sets), JP (379 sets) and CN (60 sets, Simplified Chinese), measured 2026-08-27. Japanese sets are not translations of Western ones: they have their own boundaries, their own numbering and their own release dates, so a Japanese set and its international counterpart are two different rows. Card names exist in six locales: en, ja, fr, de, es, it. Passing lang= replaces the name field itself and falls back to English when a translation is missing. Set names are not translated. Card game text is present since 2026-09-03, in English, and unevenly: attacks on 33% of the catalogue, subtypes on 38%, weaknesses on 31%, flavor_text on 20%, abilities on 8%, rules on 6%. It sits on the 20,725 Western printings, so read against those alone attacks is on 83% of them, while Japanese and Chinese printings carry none. Check the field on the card in hand rather than assuming: a null attacks means we do not hold it, never that the card has no attack. Still empty for every card: level, and legalities — deck legality is a question this API cannot answer, so say so rather than inferring it.
Inputs: q, set, lang, name, +8 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a clearly distinct operation: search, lookup by ID, price observations, set listing, reference strings, artists, catalogue status, and image recognition. Potential overlap between search results and price data is resolved by explicit descriptions of what each returns.
All tools follow the ptcg_ prefix with a consistent verb_noun structure: search_cards, get_cards, list_sets, get_reference, list_artists. The one longer name, identify_card_from_image, still follows the same pattern and fits naturally.
Eight tools is well-scoped for a Pokémon TCG catalogue and pricing API. Each tool covers a distinct functional area without redundancy or excessive granularity.
The set covers search, ID-based retrieval, pricing, set metadata, reference values, artist lists, catalogue health, and image identification. The catalogue status tool explicitly addresses unsupported data like legalities, closing what would otherwise be a gap.
Maintenance
Related MCP Connectors
Access Pollinations models and API capabilities through agent tools.
SEC filings — 13F, Form 4, 8-K, 13D, IPO and short-interest data — as 17 agent tools.
Live crypto + IDX stock market intelligence for AI agents — 19 tools, no API key.
Agent tools for discovery, payment safety, data extraction, and DeFi.
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables AI agents to access comprehensive Pokémon data through PokeAPI, including detailed Pokémon information, type effectiveness charts, encounter locations, and search capabilities. Provides a complete toolkit for retrieving stats, abilities, sprites, battle mechanics, and wild encounter data for all Pokémon.41-
- FlicenseNot gradedqualityDmaintenanceEnables LLMs to fetch Pokémon data, list popular Pokémon, and build tournament squads via the PokéAPI.34-
- AlicenseBqualityDmaintenanceEmpowers AI assistants to fetch and explore comprehensive Pokémon data from PokeAPI via 47 tools covering Pokémon, moves, items, game mechanics, and more.4781 npm2ISC

satorntcg-mcp-serverofficial
AlicenseAqualityBmaintenanceEnables LLM clients to query live TCG inventory, pricing, alerts, profit and loss, and eBay listings directly through natural language tool calls.11MIT