for agents
Pokémon TCG MCP server
11 read-only tools over the whole catalogue, in any MCP client. Paste one line, restart, and the model can look a card up instead of remembering it wrong.
claude mcp add pokemontcgapi --env PTCG_API_KEY=$PTCG_API_KEY -- npx -y @pokemontcgapi/mcpListed in the official MCP registry as com.pokemontcgapi/mcp, for clients that install servers by registry name instead of by npm package.
the key
One call, no dashboard and no card.
The trial starts at 80 credits. Confirming the address we email you raises it to 800, and it ends 30 days after signup.
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":"[email protected]"}'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 each command runs in a fresh shell, store the Idempotency-Key with the request body, privately: it is enough to fetch the secret again.
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. Put it in the client configuration below as PTCG_API_KEY. If you would rather click, the same key is here.
configuration
Every client, verbatim.
Claude Desktop
{
"mcpServers": {
"pokemontcgapi": {
"command": "npx",
"args": ["-y", "@pokemontcgapi/mcp"],
"env": { "PTCG_API_KEY": "your-key" }
}
}
}Cursor
{
"mcpServers": {
"pokemontcgapi": {
"command": "npx",
"args": ["-y", "@pokemontcgapi/mcp"],
"env": { "PTCG_API_KEY": "${env:PTCG_API_KEY}" }
}
}
}VS Code
The top-level key is `servers`, not `mcpServers`, and the `inputs` block is what keeps the key out of a file you commit.
{
"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}" }
}
}
}the tools
11, not one per endpoint.
tools/list sits in the model's context on every single turn, so every tool description uses context space. A tool per route forces the model to chain four calls to answer one question — each link a place it can go wrong. These are shaped like the questions instead.
| tool | answers | arguments |
|---|---|---|
ptcg_search_cards | Charizard cards from Japanese sets, cards by an illustrator, everything in a release window. | name, set, region, rarity, artist, released_from/to, lang, order_by, limit, cursor, q |
ptcg_get_cards | Up to 100 ids in one call. Canonical prefixes bind to their set; unresolved ids are reported with verified alternatives when the API provides them. | ids[1..100], lang, include_prices |
ptcg_get_card_prices | Every current observation for a card, each with its printing, grade, sample size and date. | id, currency |
ptcg_list_sets | Every Japanese set released in 2024, in one call, with release dates and card counts. | region, series, name, released_from/to, order_by, limit, cursor |
ptcg_get_reference | The exact strings for types, supertypes and rarities, so a filter is never guessed. | vocabulary |
ptcg_list_artists | Illustrators with a card count, deduplicated across thirty years of printings. | name, limit, cursor |
ptcg_get_catalogue_status | Live counts per print region and an explicit statement of what is NOT in the data, so an agent is told rather than left to infer. | none |
ptcg_identify_card_from_image | A photograph in, ranked candidates out — and an explicit refusal to pick when two printings share the illustration. 25 credits a call, and included from the Growth plan up. | image_base64, set, region, top_k |
ptcg_measure_centering | Card centering from a photo, with person-confirmed lines. 25 credits; Growth and higher. Returns ratios, uncertainty and geometry, normally needs-review with ceilings: null. A person reviews the lines in your app before confirm returns ceilings. This is a ceiling from centering alone, not a prediction of the final grade. | image_base64, face (front/back), card_size (standard/small), corners (TL, TR, BR, BL) |
ptcg_grade_centering | 1 credit; Growth and higher. Centering-only ceilings from known ratios, without guessing missing faces or axes. Photo-based ceilings follow a person reviewing the lines and confirm in your app. This is a ceiling from centering alone, not a prediction of the final grade. | front_lr, front_tb, back_lr, back_tb, front {lr, tb}, back {lr, tb}, house (PSA/BGS/CGC/SGC); at least one ratio, no duplicate flat/nested fields |
ptcg_get_centering_standards | 1 credit; Growth and higher. PSA, BGS, CGC and SGC thresholds, source status, source URLs and rounding rules. SGC has no published back table. | house (PSA/BGS/CGC/SGC), face (front/back), both optional |
Nothing here can change anything
Every tool carriesreadOnlyHint: true and destructiveHint: false: none of them writes, deletes or cancels. Photo recognition and centering measurement each cost 25 credits a call, against 1 for a lookup. Both and the other centering tools carry idempotentHint: false: each invocation consumes credits. Confirm is not exposed: an assistant cannot attest that a person reviewed the lines in your app.a session
What it looks like in use.
Two real exchanges, captured on 26 August 2026 and re-checked on 16 September. The prices are the ones the tool returned that day, and they carry their own date because an index moves. The second exchange is the interesting case: the honest answer to a price question is longer than a number, and the tool description is what makes the model give it.
Which Japanese sets came out in 2024, and what did they print?
ptcg_list_sets { region: "JP", released_from: "2024-01-01", released_to: "2024-12-31" }
Nineteen, newest first: Terastal Fest ex (sv8a, 6 Dec, 237 cards), Generations Start Decks (svm, 22 Nov, 175), Scarlet & Violet Promos (sv-p, 18 Oct, 218), Super Electric Breaker (sv8, 18 Oct, 106), Paradise Dragona (sv7a, 13 Sep, 94)…
What is the Base Set Charizard worth in euros?
ptcg_get_card_prices { id: "base1-4", currency: "EUR" }
€561.84 as a composite index for the holofoil printing, computed 26 Aug from 2 observations, and €458.75 across printings from 3. Both are derived indices rather than quotes — the underlying marketplace figures are in USD, and there is a PSA 10 median at $20,061 dated 24 Aug.
measured
The tool that says what is there.
An agent asked what this API covers will otherwise answer by inference — from a schema enum, from the product name, from nothing. So there is a tool whose whole job is to return the live counts.
three print regionsWestern, Japanese and Simplified Chinese sets, with the count of each read from the catalogue at call time, so an agent quotes the number that is true today.The coverage page.
names, images, pricesCard names in eight locales, front images in several sizes, illustrator credits, and daily price observations that carry their source, basis and capture date. The tools return these fields as they are, and the status tool says when each one was last refreshed.
Why this is in the tool descriptions and not only on this page
A tool description is read by the model on every session, before it acts. It is the one place where a fact about coverage arrives in time to change what the model does — a page can only correct it afterwards.also
Prefer to write the code yourself?
@pokemontcgapi/sdk is a zero-dependency TypeScript client with typed errors and pagination that follows itself. The MCP server is built on the same endpoints, and both are MIT and open — this server and the SDK.
questions
About pokemontcgapi
- What is an MCP server for the Pokémon TCG?
- It is a small program an AI client runs locally so the model can query the card catalogue directly instead of guessing. This one exposes 11 tools over 651 sets and 58,340 cards, and it runs with one command.
- Does it work with Claude, Cursor and VS Code?
- Yes. Claude Code takes one command; Claude Desktop, Cursor and VS Code take a short JSON block. All four configurations are on this page, and the VS Code one uses an input prompt so the key never lands in a committed file.
- Can an agent get Japanese card data through it?
- Yes, and the Japanese line is the largest of the three. ptcg_list_sets takes a region and a release window, ptcg_search_cards returns Japanese card names when asked for the ja locale, and ptcg_get_catalogue_status gives the count per region as it is today.
- Which print regions does it cover?
- Western, Japanese and Simplified Chinese sets, with card names in eight locales, filled very unevenly: English on almost every card, Portuguese and Chinese on a fraction. The ptcg_get_catalogue_status tool returns the live counts per region and the row count per locale, so an agent reads what is there instead of inferring it from a schema.
- Does it need an API key?
- Pass PTCG_API_KEY in the environment and the server sends it on every call. The install snippets on this page all wire it through.
Give your agent the catalogue.
One line to install, a free key, and 651 sets behind it.