for agents

Pokémon TCG MCP server

Seven 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.

npm

claude mcp add pokemontcgapi --env PTCG_API_KEY=$PTCG_API_KEY -- npx -y @pokemontcgapi/mcp

read-only@pokemontcgapi/mcp · MCP 2025-11-25 · Node 20+

configuration

Every client, verbatim.

Claude 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

The top-level key is `servers`, not `mcpServers`, and the `inputs` block is what keeps the key out of a file you commit.

.vscode/mcp.json

{
  "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

Eight, not one per endpoint.

tools/list sits in the model's context on every single turn, so the whole surface is kept under 8 KB. And 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.

MCP tools
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
`ptcg_get_cards`	Up to 100 ids in one call. Both id forms resolve, so an existing catalogue keeps working.	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 printed totals and release dates.	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.	image_base64, set, region, top_k

Nothing here can change anything

Every tool carries readOnlyHint: true and destructiveHint: false: none of them writes, deletes or cancels. Photo recognition is the one that costs real credits — 25 a call against 1 for a lookup — and it is the only one declared idempotentHint: false, so a client knows not to retry it for free.

a session

What it looks like in use.

Two real exchanges. The second one 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.

user

Which Japanese sets came out in 2024, and what did they print?

tool

ptcg_list_sets { region: "JP", released_from: "2024-01-01", released_to: "2024-12-31" }

agent

Nine, newest first: Terastal Fest ex (sv8a, 6 Dec, 237 cards), Generations Start Decks (svm, 22 Nov, 175), Scarlet & Violet Promos (sv-p, 18 Oct, 220), Super Electric Breaker (sv8, 18 Oct, 106), Paradise Dragona (sv7a, 13 Sep, 94)…

user

What is the Base Set Charizard worth in euros?

tool

ptcg_get_card_prices { id: "base1-4", currency: "EUR" }

agent

€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 regions

Western, 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, prices

Card names in six 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?

The SDK

@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 eight tools over 615 sets and 52337 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 that is the largest part of the catalogue: 379 Japanese sets against 176 international ones. ptcg_list_sets takes a region and a release window, and ptcg_search_cards returns Japanese card names when asked for the ja locale.
Which print regions does it cover?: Western, Japanese and Simplified Chinese sets, with card names in six locales. The ptcg_get_catalogue_status tool returns the live counts per region, 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 615 sets behind it.

Get a free API key Read the docs