Back to Browse

Pokewallet Sdk MCP Server

FinanceLow Risk10.0MCP RegistryRemote
Free

Server data from the Official MCP Registry

Card prices and data for Pokémon, One Piece and 10 more TCGs, from TCGplayer and Cardmarket.

About

Card prices and data for Pokémon, One Piece and 10 more TCGs, from TCGplayer and Cardmarket.

Remote endpoints: streamable-http: https://mcp.pokewallet.io/mcp

Security Report

10.0
Low Risk10.0Low Risk

Valid MCP server (2 strong, 1 medium validity signals). No known CVEs in dependencies. Imported from the Official MCP Registry.

Endpoint verified · Requires authentication · 1 issue found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Found in Source Code

Found by scanning the linked source code. This listing connects to a hosted endpoint, so none of this runs on your machine: it describes what the server software does where it is hosted.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Applies to the server that hosts this plugin, not to your machine.

How to Connect

Remote Plugin

No local installation needed. Your AI client connects to the remote endpoint directly.

Add this to your MCP configuration to connect:

{
  "mcpServers": {
    "io-pokewallet-mcp": {
      "url": "https://mcp.pokewallet.io/mcp"
    }
  }
}

Documentation

View on GitHub

From the project's GitHub README.

PokeWallet SDKs

CI npm PyPI License: MIT

PokeWallet is a card price API: Pokémon, One Piece and ten more trading card games (Magic, Yu-Gi-Oh!, Lorcana, Digimon, Flesh and Blood and others), with TCGPlayer prices in USD and CardMarket prices in EUR. This repo has the official TypeScript and Python SDKs, which put all twelve games behind one interface, and an MCP server that lets MCP clients such as Claude Code and Cursor look up cards and prices with your own key.

1. Get an API key

  1. Sign up at https://pokewallet.io/dashboard and create a key. Keys start with pk_.
  2. Keep it in an environment variable, never in your code or in git:
export POKEWALLET_API_KEY=pk_live_xxx    # your real key here

The SDKs read POKEWALLET_API_KEY by themselves. Put the same line in your shell profile or your secrets manager; keep .env files out of version control.

PlanRequests
Free100 per hour, 1,000 per day
Paid planshigher limits, see https://pokewallet.io/pricing

Free keys can search cards and read cards and sets. Pro endpoints (set prices, statistics, completion cost, trending sets, top cards, Pokémon price history) need a Pro plan for Pokémon and One Piece, or an Ultra plan for the ten other games. Every account can activate a 7-day free trial of the Pro endpoints from the dashboard. Without access, the SDK raises PlanRequiredError with the link to activate the trial or upgrade.

2. Install

TypeScript (Node 18+, no runtime dependencies):

mkdir my-cards && cd my-cards && npm init -y
npm install @pokewallet/sdk

Python (3.9+, depends only on httpx):

python3 -m venv .venv && source .venv/bin/activate
pip install pokewallet

The files of release v0.1.3, with their checksums (SHA256SUMS), also remain available on the Releases page.

3. Quickstart

Your first result takes one file. Make sure POKEWALLET_API_KEY is set (step 1).

TypeScript — save as first.mjs, run with node first.mjs:

import { PokeWallet } from '@pokewallet/sdk'

const pw = new PokeWallet() // reads POKEWALLET_API_KEY

const results = await pw.pokemon.search('charizard', { limit: 3 })
for (const card of results.items) {
  const usd = card.tcgplayer?.prices[0]?.market // TCGPlayer market price
  const eur = card.cardmarket?.prices[0]?.trend // CardMarket trend price
  console.log(`${card.name} | ${card.setName} #${card.number} | $${usd} / €${eur}`)
}

// One card in detail, by the id a search returned
const card = await pw.pokemon.card(results.items[0].id)
console.log(card.name, card.rarity, card.tcgplayer.prices.map((p) => `${p.variant}: $${p.market}`))

// A set, and every page of it without handling page numbers
const page = await pw.pokemon.set('PLF', { limit: 5 })
console.log(`${page.set.name}: ${page.total} cards`)
let count = 0
for await (const c of pw.pokemon.setCards('PLF', { maxItems: 120 })) count++
console.log(`walked ${count} cards`)

// Other games use the same methods
const lotus = await pw.games.mtg.search('black lotus', { limit: 2 })
console.log(lotus.items.map((c) => c.name))
console.log((await pw.onepiece.search('luffy', { limit: 2 })).items.map((c) => c.name))

Python — save as first.py, run with python first.py:

from pokewallet import PokeWallet

pw = PokeWallet()  # reads POKEWALLET_API_KEY

results = pw.pokemon.search("charizard", limit=3)
for card in results.items:
    usd = card.tcgplayer.prices[0].market if card.tcgplayer and card.tcgplayer.prices else None  # TCGPlayer
    eur = card.cardmarket.prices[0].trend if card.cardmarket and card.cardmarket.prices else None  # CardMarket
    print(f"{card.name} | {card.set_name} #{card.number} | ${usd} / €{eur}")

# One card in detail, by the id a search returned
card = pw.pokemon.card(results.items[0].id)
print(card.name, card.rarity, [f"{p.variant}: ${p.market}" for p in card.tcgplayer.prices])

# A set, and every page of it without handling page numbers
page = pw.pokemon.set("PLF", limit=5)
print(f"{page.set.name}: {page.total} cards")
count = sum(1 for _ in pw.pokemon.set_cards("PLF", max_items=120))
print(f"walked {count} cards")

# Other games use the same methods
print([c.name for c in pw.games.mtg.search("black lotus", limit=2).items])
print([c.name for c in pw.onepiece.search("luffy", limit=2).items])

Python, async (AsyncPokeWallet has the same methods; await them and use async for):

import asyncio
from pokewallet import AsyncPokeWallet

async def main():
    async with AsyncPokeWallet() as pw:
        pikachu, lotus = await asyncio.gather(
            pw.pokemon.search("pikachu", limit=2),
            pw.games.mtg.search("black lotus", limit=2),
        )
        print([c.name for c in pikachu.items], [c.name for c in lotus.items])
        async for card in pw.pokemon.set_cards("PLF", max_items=60):
            pass

asyncio.run(main())

No key yet? health() and listGames() / list_games() work without one:

import { PokeWallet } from '@pokewallet/sdk'
const pw = new PokeWallet()                       // no key needed for these two
console.log((await pw.health()).status)            // "healthy"
console.log((await pw.listGames()).map((g) => g.code).join(' '))  // mtg ygo cfv ...
from pokewallet import PokeWallet
pw = PokeWallet()
print(pw.health().status)                          # "healthy"
print(" ".join(g.code for g in pw.list_games()))   # mtg ygo cfv ...

More runnable scripts (pagination, error handling, Pro endpoints, other games, async) are in examples/ts and examples/py.

4. Everything available

Three worlds with the same methods: pw.pokemon, pw.onepiece, and pw.games.<code> for the ten other games (mtg, ygo, cfv, dbs, fab, dgm, swu, lor, rft, cpk; also pw.game(code) when the code is only known at runtime). The SDKs hide the differences between them: routes, set identifiers and the two pagination styles.

TypeScriptPythonReturnsAccess
search(q, {page, limit, lang})search(q, page=, limit=, lang=)one page of cards with pricesfree
searchAll(q, {limit, maxItems})search_all(...)iterator over every resultfree
card(id, {lang})card(id, lang=)one cardfree
sets({language})sets(language=)all setsfree
set(code, {page, limit, lang})set(code, page=, limit=, lang=)one page of a set's cardsfree
setCards(code, {limit, maxItems})set_cards(...)iterator over a whole setfree
prices(code)prices(code)prices of every card in a set (one row per finish; sealed products included, productType tells them apart)Pro
statistics(code, {variant})statistics(code, variant=)average, min, max, most expensive card, trend, rarity breakdown; variant is normal or foilPro
completionValue(code)completion_value(code)cost of one copy of every card in its base finishPro
trending({limit})trending(limit=)sets with the biggest CardMarket price moves over 7 days (period can only be 7d; anything else is refused before sending)Pro
topCards({metric, source, limit})top_cards(...)ranking by price (TCGPlayer market price, CardMarket trend price) or 7-day growth; each item has the card id, set, rarity, price and, for growth, change7d; TCGPlayer growth is Pokémon onlyPro
pokemon.priceHistory(id)pokemon.price_history(id)price snapshots at 7/14/30/60/120 daysPro, Pokémon only
health()health()service status and per-service checksno key needed
listGames()list_games()the ten games and their routesno key needed
imageUrl(idOrPath)image_url(id_or_path)an image URL (see below)free

"Pro" means a Pro plan or the 7-day trial for Pokémon and One Piece, and an Ultra plan or the trial for the ten other games. Limits: limit is at most 100 for searches, 200 for set pages, 50 for trending and 100 for top cards; the SDK checks page, limit, period and variant before sending anything.

Statistics and completion value describe a set the same way in every world: set has id, code, name and totalCards (cards, not finishes; sealed products are not counted), and the most expensive card of each side has its id, name and price. Card ids from rankings open with card(id). A search page has truncated, true when the candidate list was cut at its cap (Pokémon and the ten games): refine the query instead of paging. A card's variants lists its finishes, Normal first, then alphabetical.

Every returned object has the same fields in both languages (camelCase in TypeScript, snake_case in Python): a card has id, name, number, rarity, setId, setCode, setName, tcgplayer.prices[] (finish, market, low, mid, high, directLow) and cardmarket.prices[] (avg, low, trend, avg1, avg7, avg30). Prices are numbers, or null / None when missing. On One Piece, card(id) and search fill setId, setCode and setName from each entry; in a set listing the cards have setId and setCode, and the set's name is in page.set. A card also has productType (card, or a sealed type) and, for One Piece, one id per entry: a Normal and a Foil entry of the same card have different ids. A set listing has cardCount and sealedCount. Game-specific fields (hp, attacks, Magic's p and t, One Piece ext_*) are in card.info, and the untouched server value is always in card.raw.

Images: imageUrl(id) only builds the URL. Image routes need your key in the X-API-Key header, so the URL cannot go straight into an <img> tag; fetch it with the header or proxy it from your server. It also takes the relative card.image.path the API returns with lang (below) and adds only the host.

Card languages (Pokémon). search, card and set take lang to get a card's name, rarity, attacks and text in another language: de, es, fr, it, pt, ko, zh-cn, zh-tw, th or id, in any case. en, ja or no value give the usual answer. The SDKs check the value before sending and refuse anything else with a ValidationError that lists the valid ones; for One Piece and the ten games lang is refused too, because only Pokémon has translations.

const card = await pw.pokemon.card(id, { lang: 'it' })
card.language          // 'it', or 'en' when this card has no Italian text
card.languages         // { en: ['data', 'image'], it: ['data', 'image'], ko: ['data'], ... }
card.image?.path       // '/images/pk_…?lang=it', or '/images/pk_…' when there is no Italian image
pw.imageUrl(card.image!.path!) // the URL to fetch with your key header
card = pw.pokemon.card(card_id, lang="it")
card.language, card.languages, card.image.path   # same fields, snake_case
pw.image_url(card.image.path)
  • card.languages is always there on Pokémon cards, with or without lang: for each language, data (name, rarity, attacks, text) and/or image. en is always present. Use it to see which values of lang give a translation for that card.
  • card.language and card.image.path / card.image.language appear only when you asked for a language. If the card has no text in it, language is en and the text is the English one; the image follows its own list, so it can be in your language even when the text is not.
  • A translation can be partial: some fields may stay in English. The rarity is the one printed on the card in that language. Attacks keep the usual [Cost] Name (damage) format.
  • Coverage varies by set and by language and grows over time. The European languages (de es fr it pt) are for the cards of English sets, the Asian ones (ko zh-cn zh-tw th id) for the cards of Japanese sets; the same card in the two families has two ids, with no link between them, so ko on an English card gives English.
  • Images exist for it fr de es pt; for the other languages image.path is the default image and image.language is en.
  • This needs the API release that serves lang. Against an older API the options still work, but nothing is translated and card.languages is empty.

Image outcomes: 404 Image not found means the source has no image, so do not retry it in the same run (check again from time to time); 502, 503 and other 5xx answers are temporary, so retry with backoff; on 429 wait for Retry-After when it is present.

Prices of CardMarket-only sets. For a set with a negative id (source is cm), each prices row is one CardMarket product and its cardmarket block is the normal price of that product. A tcgplayer block, when there is one, is an extra link made through CardTrader: its variant is null and it can be for a different finish than the CardMarket one (for example 1st Edition Holofoil), so do not compare or add the two. For European prices by finish (normal and holo), use card(id). An ambiguous set_code on prices answers 300 with matches: pass the numeric set_id instead.

5. Errors, retries and limits

Every failure is a typed error, all subclasses of PokeWalletError:

ErrorWhenUseful fields
ValidationErrorbad arguments, or no API key; raised before any request
AuthError401: key missing, malformed or unknown
PlanRequiredError403: plan or trial does not cover this endpointredeemUrl (activate the trial), upgradeUrl
FeatureNotEnabledError403: this account does not have access to this featurecontactUrl
NotFoundError404: unknown card or setdidYouMean, suggestions
GameUnavailableError404 on a game route that is switched off
AmbiguousSetErrora set code matches several setsmatches (each has setId, setCode, name, language)
RateLimitError429: quota used uplimits, retryAfter
UnavailableError503: service busyretryAfter
NetworkError, ServerErrorno answer, other 5xx
import { AmbiguousSetError, PlanRequiredError } from '@pokewallet/sdk'

try {
  const trending = await pw.pokemon.trending()
} catch (e) {
  if (e instanceof PlanRequiredError) console.log(`Needs Pro: ${e.redeemUrl ?? e.upgradeUrl}`)
  else throw e
}

try {
  await pw.pokemon.set('PR')                       // "PR" exists in many sets
} catch (e) {
  if (e instanceof AmbiguousSetError) {
    const page = await pw.pokemon.set(e.matches[0].setId)   // pick one by its setId
  } else throw e
}
from pokewallet import AmbiguousSetError, PlanRequiredError

try:
    trending = pw.pokemon.trending()
except PlanRequiredError as e:
    print(f"Needs Pro: {e.redeem_url or e.upgrade_url}")

try:
    pw.pokemon.set("PR")                           # "PR" exists in many sets
except AmbiguousSetError as e:
    page = pw.pokemon.set(e.matches[0].set_id)     # pick one by its set_id

An ambiguous set code is reported the same way on every endpoint, even though the API answers it three different ways.

Retries. The SDK retries only two situations: a 429 that carries a Retry-After header within 30 seconds (and whose quota is not already exhausted), and a 503, up to 2 times, honoring Retry-After. It never retries other errors, and never guesses a wait. Options: maxRetries, retryAfterCapSeconds, timeoutMs, client, fetch (TypeScript); max_retries, retry_after_cap, timeout, client, transport (Python).

Client header. Every request carries X-PokeWallet-Client: pokewallet-sdk-ts/<version> (Python: pokewallet-sdk-py/<version>), next to the User-Agent. Browsers cannot set User-Agent, so this header is how a browser app identifies itself; the client option replaces its value with your own app name.

Quota. After any call, pw.lastRateLimit (Python: pw.last_rate_limit) holds limitHour, remainingHour, limitDay and remainingDay. The free plan allows 100 requests per hour; a RateLimitError has limits (hourly / daily) showing what is left. Error responses count against your quota too.

Service status. health() returns status (healthy or unhealthy) and a check per service. If the API reports itself unhealthy (HTTP 503), you still get that report back as data, not an exception.

6. MCP server

packages/mcp is a small server for the Model Context Protocol. It lets any MCP client (Claude Code, Claude Desktop, Cursor, VS Code, Gemini CLI, your own agents, ...) search cards and read prices using your own key: the client sends Authorization: Bearer pk_…, the server forwards it to PokeWallet and keeps nothing. Your plan and quota stay yours, and every tool call uses one request of your quota.

Tools (all read-only): list_games, search_cards (at most 10 results), get_card, list_sets (filter by name or language), get_set (an ambiguous set returns its alternatives; search_cards, get_card and get_set take an optional Pokémon lang, see "Card languages" above), get_price_history (Pokémon), top_cards, trending_sets, set_statistics, set_completion_value. trending_sets covers the last 7 days, the only period. A game parameter picks pokemon (default), onepiece or a game code.

The hosted server is at https://mcp.pokewallet.io/mcp. Connect a client, passing your key as a Bearer header.

Claude Code:

claude mcp add --transport http pokewallet https://mcp.pokewallet.io/mcp \
  --header "Authorization: Bearer $POKEWALLET_API_KEY"

This saves the key in Claude Code's own config on your machine, like any header you pass. Add --scope user to have the server in every project; /mcp inside Claude Code shows whether it is connected.

Cursor — ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "pokewallet": {
      "url": "https://mcp.pokewallet.io/mcp",
      "headers": { "Authorization": "Bearer ${env:POKEWALLET_API_KEY}" }
    }
  }
}

VS Code (Copilot agent mode) — .vscode/mcp.json in a project, or MCP: Open User Configuration for every project. VS Code asks for the key on first start and stores it securely:

{
  "servers": {
    "pokewallet": {
      "type": "http",
      "url": "https://mcp.pokewallet.io/mcp",
      "headers": { "Authorization": "Bearer ${input:pokewallet-key}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "pokewallet-key", "description": "PokeWallet API key", "password": true }
  ]
}

Gemini CLI — ~/.gemini/settings.json (or .gemini/settings.json in a project):

{
  "mcpServers": {
    "pokewallet": {
      "httpUrl": "https://mcp.pokewallet.io/mcp",
      "headers": { "Authorization": "Bearer $POKEWALLET_API_KEY" }
    }
  }
}

mcp-remote (for clients that only speak stdio, such as Claude Desktop) — in the client's MCP config:

{
  "mcpServers": {
    "pokewallet": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.pokewallet.io/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer pk_live_xxx" }
    }
  }
}

Replace pk_live_xxx with your key; this file is the one place where it has to be written down, so keep the file private. For Claude Desktop the file is claude_desktop_config.json (Settings → Developer → Edit Config); restart the app after saving.

Other clients (Windsurf, Cline, Zed, your own code with an MCP SDK, ...): give them the URL https://mcp.pokewallet.io/mcp (Streamable HTTP) and the header Authorization: Bearer <your key>. A client that only runs local servers can use the mcp-remote setup above.

The custom connectors of the claude.ai and ChatGPT web apps cannot send an API key header (they support OAuth or no authentication), so they cannot connect to this server for now.

Run it locally instead (needs the repo, Node 22+):

gh repo clone pokewallet-lab/pokewallet-sdk && cd pokewallet-sdk
(cd packages/ts && npm install && npm run build)
cd packages/mcp && npm install && npx wrangler dev

The local endpoint is http://127.0.0.1:8787/mcp: use it in place of the hosted URL above, and add --allow-http to the mcp-remote arguments, since the URL is plain http://. See packages/mcp for details.

7. Versioning and compatibility

The SDKs follow semantic versioning. While the version is 0.x the surface is still settling, so a minor release (0.2.0) may contain breaking changes; they are listed in the release notes. From 1.0 on, breaking changes only come in major releases. The TypeScript and Python packages are versioned and released independently.

  • Breaking: removing or renaming a method, option, field or error class; changing a return type or what an error means; changing the default retry behavior; raising the minimum Node.js or Python version.
  • Not breaking: new methods, new optional parameters, new fields on returned objects, new error subclasses, bug fixes.

How the SDKs relate to API changes:

What changes in the APIWhat you need
New cards, new sets, new pricesNothing: it is data
New fields in a responseNothing: they appear in .raw right away and get a typed field in a later release
A new endpoint, or a new gameAn SDK release; unknown games are skipped by listGames() until then
A field or endpoint changes or is removedAn SDK release; the weekly contract run against the live API is meant to catch this first

8. Key safety and license

  • Read the key from the environment. Do not commit it, print it, or paste it into issues.
  • The SDKs hold the key in private storage, show it as pk_*** in JSON.stringify, repr, util.inspect, errors and logs, and remove it from any server text that echoes it. Python clients cannot be pickled or copied.
  • If a key leaks, revoke it in the dashboard and create a new one.

MIT License, Copyright (c) 2026 PokeWallet. See LICENSE.

Package documentation: packages/ts (TypeScript), packages/py (Python), packages/mcp (MCP server), openapi/pokewallet.yaml (API specification).

Attribution

If you show data obtained through the PokeWallet API, the SDKs or the MCP server to other people (an app, website, bot, dashboard, report, published content, or an AI assistant answer you publish), credit PokéWallet with the visible text "Data by PokéWallet" (or "Powered by PokéWallet") linking to https://pokewallet.io. Private use needs no attribution. See the Terms of Use.

This is about the data and the service. The MIT license of the code is separate.

Repository layout

PathWhat
openapi/pokewallet.yamlHand-written OpenAPI 3.1 spec of the API as it behaves today; the TypeScript types are generated from it
packages/ts@pokewallet/sdk, zero runtime dependencies, ESM + CJS, Node 18+
packages/pypokewallet, Python 3.9+, httpx only, sync and async
packages/mcpStateless MCP server on a Cloudflare Worker, hosted at https://mcp.pokewallet.io/mcp
examples/ts, examples/pyRunnable examples
.github/scriptsHelper scripts used by the CI and release workflows
tests/fixturesRecorded API answers shared by the TypeScript, Python and MCP unit tests

The MCP package is not published to a package registry. The two SDK packages are published through the tag workflow described under Release. CI is .github/workflows/ci.yml: typecheck and unit tests only, no key.

Tests

LevelCommandNeeds
Unitcd packages/ts && npm testnpm install
cd packages/py && python -m pytestpip install -e '.[test]'
cd packages/mcp && npm testnpm install in packages/ts and packages/mcp; run npm run typecheck once to build the SDK
Contract (live API, about 45 calls each)cd packages/ts && npm run test:contractPOKEWALLET_API_KEY
cd packages/py && python -m pytest tests/contractPOKEWALLET_API_KEY
MCP end to end (local wrangler dev, live API)cd packages/mcp && npm run test:e2ePOKEWALLET_API_KEY
Customer-stylenpm pack / pip wheel ., install in a fresh folder or venv, run the README snippetsPOKEWALLET_API_KEY

Contract and end-to-end tests skip cleanly without a key (the two key-less endpoint tests always run). The card-language checks run only with POKEWALLET_LANG_LIVE=1, once the API serves lang; POKEWALLET_BASE_URL points the contract suites at another deployment, such as a local one. Load the key into the process that needs it and mask the output:

( set -a; . <(grep '^POKEWALLET_API_KEY=' /path/to/.dev.vars); set +a; npm run test:contract ) 2>&1 | sed -E 's/pk_[A-Za-z0-9_-]{6,}/pk_***/g'

Release

Releases are published by GitHub Actions from version tags: ts-v<semver> for the TypeScript package and py-v<semver> for the Python package. A tag runs release.yml, which checks that the tag matches the version in the package files, runs the unit tests, builds, and publishes after a maintainer approves the run on the release environment. Each pull request runs a publish dry-run (publish-check.yml), and a weekly job (drift.yml) runs the contract tests against the live API.

  • PyPI uses Trusted Publishing; no token is stored.
  • npm: the first version (0.1.1) was published manually, which is how a new package is created. Later versions are published by the workflow through npm Trusted Publishing, which must be configured in the settings of @pokewallet/sdk on npmjs.com: provider GitHub Actions, owner pokewallet-lab, repository pokewallet-sdk, workflow release.yml, environment release, with Allow npm publish checked (without it only npm stage publish is allowed and the workflow fails with 403 OIDC permission denied for this action). Staged publishing of a new package needs an approval with two-factor authentication on npmjs.com; new releases of an existing package go through the workflow.

Reviews

No reviews yet

Be the first to review this server!