TCGdex MCP Server
An MCP (Model Context Protocol) server that exposes the TCGdex Pokémon TCG API as tools for LLMs and AI applications.
This is an independent, unofficial project. It is not affiliated with, endorsed by or sponsored by
TCGdex, Nintendo, The Pokémon Company, Creatures, Game Freak, Cardmarket, TCGplayer, the European
Central Bank or Frankfurter — see Affiliation and trademarks.
Installation
No global installation is required. MCP clients can run the package directly with npx:
{
"mcpServers": {
"tcgdex": {
"command": "npx",
"args": ["-y", "@leewinder/mcp-tcgdex"]
}
}
}
The -y flag allows npx to install the package without asking for confirmation.
If you prefer to install the server globally you can run the following
npm install -g @leewinder/mcp-tcgdex
The package provides the tcgdex command, which can then be used directly:
{
"mcpServers": {
"tcgdex": {
"command": "tcgdex"
}
}
}
From a local checkout, point at the built entry point instead:
{
"mcpServers": {
"tcgdex": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/PARENT/FOLDER/tcgdex-mcp-server/build/index.js"]
}
}
}
Every tool takes an optional language (one of en, fr, es, es-mx, it, pt, pt-br,
de, nl, pl, ru, ja, ko, zh-tw, id, th, zh-cn, defaulting to en) and echoes it
back. Names and field values are localised, catalogues hold different sets — the Asian ones hold sets
of their own under ids of their own, such as the Japanese SV1a — and prices are the same in every
language. Tools that return a page of a list also take page (zero-indexed, defaulting to 0) and size
(1–100, defaulting to 20), and return hasMore alongside the echoed page and size — there is no
total count, so read everything by incrementing page while hasMore is true. The two pricing tools
are not paged: get_card_pricing answers every line it was given at once, and rank_card_prices
returns a limit of rows and says how much of the match it covered.
A request TCGdex fails transiently (a server error, a rate limit or no response) is retried a few
times with backoff, for under two seconds in all. One that still fails is reported with advice to
retry the call shortly; a card or set that does not exist is reported without it, because retrying
will not find it.
Values are localised, so look a value up in the language you intend to search in: Fire finds nothing
in French, where Feu does. A value differing from the catalogue's only in letter case is corrected to
the catalogue's spelling (Special Illustration Rare finds Special illustration rare), except where
two values differ only in case — suffixes EX and ex are different mechanics, so give one exactly. Sets are the exception — every tool
accepts a set's id or printed name ignoring case, and a set it cannot find is reported with up to five
sets of a similar id or name as candidates.
list_card_field_values
Lists the values the TCGdex API accepts for a given card field.
| Argument | Type | Description |
|---|
field | enum, required | Which field to list: type, energy, category, trainer, stage, rarity, illustrator, variant, suffix, regulation, hp, retreat, pokedex |
contains | string, optional | Case-insensitive substring filter, applied across the whole field before paging |
Returns values, one page of them. They are upstream's list as-is, with two corrections: retreat
adds 0, the free retreat upstream's list omits, and regulation leaves out the None and the
lower-case j upstream lists, which are a placeholder and a typo rather than marks.
list_sets
Lists the sets a language's catalogue holds, which is how a set you know by name becomes the id the
other tools take — an id is not derived from the name in any predictable way (Paldean Fates is
sv04.5).
| Argument | Type | Description |
|---|
contains | string, optional | Case-insensitive substring filter over both id and name, applied across the whole catalogue before paging |
platform | enum, optional | TCG for physically printed sets, TCG Pocket for digital-only ones. Omit for both |
sort | enum, optional | releaseDate (the default), name or id |
order | enum, optional | asc (the default) or desc — desc on releaseDate puts the newest set first |
Returns sets, each with id, name, platform, releaseDate, serie and cardCount, plus the
sort and order used.
search_cards
Searches the catalogue. Every filter is optional and they combine with AND, so a call with none
walks the whole catalogue. A text value the catalogue does not use is reported as an error naming
the tool that lists the real ones, so an empty page means the values were real and nothing matched.
| Argument | Type | Description |
|---|
name | string, optional | Case-insensitive substring match on the card's name — the one filter that is not exact |
pokemon | string, optional | A Pokémon's name in the requested language, resolved to its National Pokédex number and echoed back as pokemon, so pikachu finds every card depicting Pikachu whatever the card is called |
set | string, optional | The set's id or printed name, matched whole but ignoring case |
platform | enum, optional | TCG or TCG Pocket, as in list_sets |
effect | string, optional | Case-insensitive substring match on a Trainer or Energy card's effect text |
attack, ability | string, optional | Case-insensitive substring match on a Pokémon's attack or ability names and text. Upstream cannot search these, so they are checked over the first 300 cards matching the other filters — at least one of which is required — and textSearch reports how many were read and whether more matched |
type, energy, category, trainer, stage, rarity, illustrator, variant, suffix, regulation | string, optional | Exact matches on the card field of that name, with letter case corrected to the catalogue's where only one value matches ignoring case |
hp, retreat | { min?, max? }, optional | Inclusive bounds; either may be given alone. A retreat max of 0 finds the cards that retreat for free |
pokedex | integer, optional | Matches when the number is among those the card depicts |
sort | enum, optional | id (the default) or name, in alphabetical order ignoring case. Release order is not available upstream |
order | enum, optional | asc (the default) or desc |
detail | enum, optional | summary (the default) or full |
Returns cards, one page of them, in a fixed order, plus the sort, order and detail used. A summary carries id, localId,
name, set, platform, rarity and images; full adds every searchable field, the card's
rules text, weaknesses, resistances and tournament legality. Market prices are not part of either —
use get_card_pricing or rank_card_prices. Per-variant
print details, physical attributes and flavour text are omitted from both. An attack's damage is
always text as printed ("30", "30×"), a missing cost may be a gap in upstream's data rather
than a free attack, and a rarity of null means the card was printed with no rarity symbol.
get_set
Reads one set: what it is, plus a page of its cards as a checklist.
| Argument | Type | Description |
|---|
set | string, required | The set's id or printed name, matched case-insensitively |
Returns set — id, name, serie, releaseDate, platform and a cardCount broken down by
numbering and by printing — and cards, one page of { id, localId, name, rarity } in printed order.
The set's details repeat on every page. Tournament legality is not given per set: upstream's
set-level flag reports no current set as standard-legal, and legality belongs to each card anyway, so
read it from get_card.
get_card
Reads one whole card, named either way a card is named.
| Argument | Type | Description |
|---|
id | string, optional | The card's globally unique id, e.g. swsh3-136. Give this on its own |
set | string, optional | The set's id or printed name, matched case-insensitively. Give with localId |
localId | string, optional | The number printed on the card, e.g. 105. Leading zeros are optional |
Give either id, or both set and localId — not both forms at once. Returns card, in the same
shape search_cards returns at its full detail level.
get_card_pricing
Prices up to 50 cards from Cardmarket's and TCGplayer's market data, in the currency asked for, with
a separate total for each market.
| Argument | Type | Description |
|---|
cards | array of 1–50, required | Each line names one card the way get_card does — id, or set and localId — plus an optional variant and a quantity (default 1) |
cards[].variant | enum, optional | normal, holo, reverse, 1st-edition, 1st-edition-holo, unlimited, unlimited-holo. Name the edition of a card printed in editions: from Jungle to Neo TCGplayer prices 1st Edition and Unlimited separately, while Base Set's only priced printing is unlimited-holo (or unlimited) and a bare holo there is priced only approximately |
currency | enum, required | EUR, USD or GBP |
basis | enum, optional | market (the default: TCGplayer's market price, Cardmarket's trend), low, or Cardmarket's day averages avg_1d, avg_7d, avg_30d |
Returns lines, one per request in the order asked, and totals with one entry per market. Each line
has a status:
priced — counted towards the totals.
ambiguous — no variant was named and the price could not be pinned to the copy held: the card has
more than one priced printing, has printings sold as products of their own
(separatelyListedPrintings), or has its one printing priced only approximately. Every printing is
listed but none is counted. Name one to price it. A printing sold as a product of its own is listed
too, with no variant, upstream's own description of it in printing, and both prices null with
reason separate_product.
unpriced — the card was read but neither market prices it.
unavailable — the card could not be read. This is counted separately from unpriced.
A market's total reports complete: true only when every line was priced in that market; any
unpriced, ambiguous or unavailable line makes it false.
Every price gives the market's own amount and currency, the timestamp upstream recorded it at and its
age, and its convertedAmount in the currency asked for. The rates used are given once per response,
in exchangeRates, with their date, their source and a rate per currency pair. Every missing price
carries a reason: no_listing, variant_unpriced, variant_not_printed (the catalogue says the
card was never printed that way), separate_product (the printing is sold as a product of its own
whose price is not carried, such as Base Set's 1st Edition), window_unavailable,
platform_unpriced, unavailable or unrecognised_shape.
rank_card_prices
Ranks the cards matching a search by one market's price.
| Argument | Type | Description |
|---|
name, pokemon, pokedex, set, rarity | as in search_cards, at least one required | The same filters, with the same matching and the same errors |
rankMarket | enum, required | tcgplayer or cardmarket — a ranking compares one market's figures only |
currency | enum, required | EUR, USD or GBP. Changes how prices are shown, never the order |
basis | enum, optional | As for get_card_pricing. The day averages can only be ranked on Cardmarket |
order | enum, optional | desc (the default) or asc |
limit | integer, optional | 1–50, default 10 |
Each card is ranked once, by its highest-priced printing in the chosen market, and each row shows the
other market's price for that printing too. Upstream can neither filter nor sort by price, so each call
reads up to the first 300 matching cards. truncated reports when more than that matched, and
coverage counts every card read as ranked, unpriced (with the reasons) or unavailable.
About the prices
- Prices are for one copy in unspecified condition, and are not what a seller would receive after
fees. Treat them as a market indication, not a valuation, and not as financial advice.
- The two markets are never blended. TCGplayer's market price and Cardmarket's trend price are
computed differently. That is why totals are per market and a ranking uses one market.
- The day averages are Cardmarket's alone. TCGplayer publishes none.
- Two markets far apart get a warning. When both price the same printing and one is more than 10×
the other, the line or row carries a warning. A gap that wide usually means upstream attached one
market's figures to a different product, so check both before relying on either.
- Conversion uses the latest ECB euro reference rate, not the rate of the day a price was recorded.
Comparing markets, or one price over time, therefore carries exchange-rate drift.
- A price describes the marketplace product, not a language edition. It is the same whatever
language is asked for. Japanese cards have carried Cardmarket prices only and Traditional Chinese
cards none, in every card sampled; Pokémon TCG Pocket cards are digital and never priced; and special
printings sold as products of their own (Poké Ball and Master Ball reverses, stamped promos, Base
Set's 1st Edition and Shadowless) are counted in separatelyListedPrintings but not priced.
- Data sources. Card data and prices come from the TCGdex API, whose prices
originate with Cardmarket and TCGplayer.
Exchange rates are the ECB's euro reference
rates,
fetched through Frankfurter. Prices are cached for up to an hour and rates
for up to twelve.
- Outbound requests. Besides
api.tcgdex.net, the server calls api.frankfurter.dev the first time
a price needs converting, and again at most every twelve hours after that. The request carries no
card or user data, but like any request it reveals the machine's IP address to that service.
The data is provided as is, with no warranty of accuracy or availability; see LICENSE.
Affiliation and trademarks
TCGdex MCP Server is an independent, unofficial project. It is not affiliated with, endorsed by,
sponsored by or approved by any of the following, and none of them is responsible for it or for the
data it returns:
- Nintendo, The Pokémon Company, The Pokémon Company International, Creatures and Game Freak.
Pokémon, the Pokémon Trading Card Game, Pokémon TCG Pocket, and the names of Pokémon, cards, sets
and related marks are trademarks of their respective owners. Card names, card text and card images
belong to their respective rights holders and are shown only as they come from TCGdex.
- TCGdex. This server is a client of TCGdex's public API, which supplies all card data and card
images. It uses the TCGdex name only to say which API it connects to, and it is not a TCGdex
product.
- Cardmarket and TCGplayer. Prices come from these marketplaces by way of TCGdex. This server
does not connect to either marketplace, and neither has reviewed or endorsed how their prices are
presented here.
- The European Central Bank and Frankfurter. Exchange rates are the ECB's published euro
reference rates, fetched through the Frankfurter API. Neither has any connection to this project.
All trademarks are the property of their respective owners and are used here only to identify the
services and products concerned.
Development
Requires Node 24 or newer. With nvm, .nvmrc selects it:
nvm use
npm install
npm run build
License
MIT