{
  "markdown": "# tcg-mcp\n\n<!-- mcp-name: io.github.seanlok/tcg-mcp -->\n\n> A Pokemon TCG MCP server. Looks up graded cards (PSA today, CGC/BGS\n> stubbed), manages your owned collection in a local SQLite DB, queries\n> pricing providers (Pokemon TCG API + PriceCharting), tracks a watchlist\n> with target prices, and snapshots PSA pop counts so you can see trends\n> over time.\n\n[![PyPI](https://img.shields.io/pypi/v/tcg-mcp.svg)](https://pypi.org/project/tcg-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/tcg-mcp.svg)](https://pypi.org/project/tcg-mcp/)\n[![Downloads](https://img.shields.io/pypi/dm/tcg-mcp.svg)](https://pypistats.org/packages/tcg-mcp)\n[![CI](https://github.com/seanlok/tcg-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/seanlok/tcg-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n`tcg-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)\nserver. Install it once, wire it into Claude Desktop / Claude Code / Cursor /\nany MCP client, and your assistant gains 25 tools for working with PSA cert\ndata, your personal collection, and live market prices.\n\n---\n\n## What it does — 25 tools, namespaced\n\n**PSA grading (`tcg_psa_*`)** — cert lookup, front/back images, snapshot pop\ndata over time, plus a workflow tool that looks up a cert and records it as\nowned in one call.\n\n**CGC / BGS (`tcg_cgc_*`, `tcg_bgs_*`)** — stubs in v0.2; no public API exists\nfor either grader. Listed for routing parity; will route cleanly if either\ngrader publishes an API.\n\n**Collection (`tcg_collection_*`)** — add raw or graded cards (or sealed\nproducts: ETBs, booster boxes, UPCs, tins), list with filters, update cost\nbasis, soft-delete (mark sold) or hard-delete, attach a card to a pricing\nlisting, get a cost-basis summary or a live market valuation that joins\nagainst the most recent pricing snapshots.\n\n**Pricing (`tcg_pricing_*`)** — search a provider, get a full price quote\n(top-level market/low/high plus per-variant breakdown for Pokemon TCG API,\nplus per-grade levels for PriceCharting), persist snapshots into the local\nDB, **bulk-snapshot every attached card in one call** with per-provider\nrate-limit awareness, and **query historical snapshots** as a time series\nfor trend analysis.\n\n**Watchlist (`tcg_watchlist_*`)** — add target buy prices with thesis text,\nlist by horizon (flip / hold / sealed), update, and close with a reason\n(bought / thesis_invalidated / manual).\n\n**Meta (`tcg_list_providers`)** — discovery tool that shows which grading +\npricing providers are enabled, what env var each needs, and what tools are\nin the namespace.\n\nFor the full tool list run `tcg_list_providers` after install or read the\n[architecture doc](docs/architecture.md).\n\n---\n\n## Prerequisites\n\n1. **Python 3.10 or newer** (3.13 recommended).\n2. **An MCP client** — Claude Desktop, Claude Code, Cursor, Continue, etc.\n3. *(Optional, for PSA tools only)* **A PSA Public API token** — free, sign\n   up at [psacard.com/publicapi](https://www.psacard.com/publicapi).\n\nThe server works without any tokens — Pokemon TCG API queries, collection,\nand watchlist tools all function on a fresh install with zero credentials.\n\n---\n\n## Install\n\n### Option A — `uvx` (recommended, zero install)\n\n```bash\n# install uv if you don't have it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# run the server (auto-installs the package on first use)\nuvx tcg-mcp --help\n```\n\n### Option B — `pipx`\n\n```bash\npipx install tcg-mcp\ntcg-mcp --help\n```\n\n### Option C — `pip`\n\n```bash\npython3 -m pip install tcg-mcp\n```\n\n### Option D — from source (for contributors)\n\n```bash\ngit clone https://github.com/seanlok/tcg-mcp.git\ncd tcg-mcp\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\npytest        # run the test suite\n```\n\n---\n\n## Configure\n\nCopy `.env.example` to `.env` and fill in any tokens you have:\n\n```bash\ncp .env.example .env\n$EDITOR .env\n```\n\nOr set the env vars however your client supports it (most clients let you\nspecify `env` per MCP server in the config).\n\n| Env var | Required for | Notes |\n|---|---|---|\n| `PSA_API_TOKEN` | PSA tools | [Get one](https://www.psacard.com/publicapi) — free |\n| `POKEMONTCG_API_KEY` | Higher Pokemon TCG API rate limit (optional) | [Get one](https://dev.pokemontcg.io/) — free |\n| `PRICECHARTING_TOKEN` | PriceCharting tools | Paid subscription required |\n| `TCG_DB_PATH` | Local DB location | Default `~/.tcg-mcp/tcg.db` |\n\n---\n\n## Wire it into your MCP client\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS),\n`%APPDATA%\\Claude\\claude_desktop_config.json` (Windows), or\n`~/.config/Claude/claude_desktop_config.json` (Linux):\n\n```json\n{\n  \"mcpServers\": {\n    \"tcg-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"tcg-mcp\"],\n      \"env\": {\n        \"PSA_API_TOKEN\": \"your-token-here\",\n        \"TCG_DB_PATH\": \"~/Documents/tcg-mcp.db\"\n      }\n    }\n  }\n}\n```\n\nQuit Claude Desktop fully (⌘Q on macOS — closing the window isn't enough)\nand relaunch.\n\n### Claude Code\n\n```bash\nclaude mcp add tcg-mcp -- uvx tcg-mcp\n```\n\nThen export the tokens you have in the shell that runs `claude`.\n\n### Cursor / Continue / etc.\n\nSame shape — point the client at:\n\n```\ncommand: uvx\nargs:    [\"tcg-mcp\"]\nenv:     PSA_API_TOKEN=...    # optional\n```\n\n---\n\n## Smoke-test it\n\nAfter wiring up the client, ask it:\n\n> \"Use tcg-mcp to list providers.\"\n\nYou should see `pokemontcg` enabled, plus `psa` enabled if your token is\nset, and stubs for the others.\n\nThen try a real lookup:\n\n> \"Search Pokemon TCG API for Charizard ex from Obsidian Flames.\"\n\n> \"Add a 1999 Pokemon Base Set Charizard #4 (raw) to my collection — paid $250 on 2026-04-15.\"\n\n> \"Add Charizard ex Surging Sparks to my watchlist with a target buy price of $180.\"\n\n> \"What's my collection cost basis?\"\n\n---\n\n## Architecture, briefly\n\n```\n+----------------------+\n|     MCP client       |  Claude Desktop, Cursor, etc.\n+----------+-----------+\n           | stdio (JSON-RPC)\n+----------v-----------+\n|     server.py        |  FastMCP — tool registration, validation\n+----------+-----------+\n           |\n   +-------+-------+----------------+\n   |               |                |\n+--v--+         +--v--+        +----v----+\n| psa |  ...    |pricing|      | storage |  SQLite — collection,\n+--+--+         +--+----+      +----+----+  watchlist, pop trends,\n   | httpx         | httpx          |       pricing snapshots\n+--v---------------v----+      +----v----+\n|  PSA / Pokemon TCG    |      | tcg.db  |\n|  API / PriceCharting  |      +---------+\n+-----------------------+\n```\n\nProvider abstractions ([`providers/base.py`](src/tcg_mcp/providers/base.py),\n[`pricing/base.py`](src/tcg_mcp/pricing/base.py)) make adding a new grader\nor pricing source a single-file change. See\n[`docs/adding-a-provider.md`](docs/adding-a-provider.md).\n\n---\n\n## Local SQLite database\n\nAll your personal data — collection, watchlist, pricing snapshots, pop\nsnapshots — lives in a single SQLite file. Default location is\n`~/.tcg-mcp/tcg.db`. Point `TCG_DB_PATH` at any path you prefer.\n\nThe file format is plain SQLite, so you can inspect or back up the data\ndirectly:\n\n```bash\nsqlite3 ~/.tcg-mcp/tcg.db\n.tables\nSELECT subject, grade, acquisition_price FROM owned_cards WHERE status='owned';\n```\n\nSchema is in [`src/tcg_mcp/storage/schema.sql`](src/tcg_mcp/storage/schema.sql).\nMigrations are forward-only and idempotent (safe to run on every startup).\n\n---\n\n## Known limits\n\n- **PSA images** only exist for cards graded after **October 2021**. Older\n  slabs return an empty image list — that's the upstream API, not a bug.\n- **PSA's `Brand` field** is the closest thing to a clean \"set name\" in\n  their schema. We surface it as `set_name`; for finer-grained set parsing,\n  reach into the raw payload.\n- **CGC / BGS** providers are stubs in v0.2. They're listed for discovery\n  but raise `NotSupportedError` if called. Implementation depends on either\n  grader publishing a public API or an explicit decision to support polite\n  scraping.\n- **Rate limits** on the PSA free tier aren't publicly documented. If you\n  see \"PSA API rate limit exceeded\", wait or upgrade your plan.\n- **PriceCharting** is paid-only. Without a `PRICECHARTING_TOKEN` the\n  provider is registered as `disabled` and graded-card prices aren't\n  available — but Pokemon TCG API still gives you raw market prices.\n\n---\n\n## Roadmap\n\n> **Standing constraint:** every milestone below has a **free path** as the\n> default. Paid providers (GemRate, eBay Marketplace Insights, etc.) stay\n> optional add-ons that activate only when their key is configured.\n\n- ✅ **v0.3 — shipped:** `tcg_pricing_snapshot_collection`,\n  `tcg_pricing_get_history`, rounded per-item valuation, clearer PSA 429\n  error message, `CHANGELOG.md`.\n- ✅ **v0.4 — shipped:** Catalog tools (`tcg_catalog_*`) backed by Pokemon\n  TCG API, `tcg_collection_set_completion` with watchlist intersection,\n  richer `tcg_collection_search`, smart-routed `tcg_pricing_get_card`.\n- v0.5 — CGC support (free path: polite scraping; optional paid GemRate).\n- v0.6 — BGS support (free path: polite scraping; optional paid GemRate).\n- v0.7 — eBay sold comps (free path: eBay Browse API + scraping; optional\n  paid Marketplace Insights API).\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for the full version history.\n\n---\n\n## Contributing\n\nContributions welcome. To add a new grading or pricing provider, see\n[`docs/adding-a-provider.md`](docs/adding-a-provider.md). The contract is\nintentionally small: implement a Protocol method, register it conditionally\nbased on credentials, write a mock-httpx test.\n\n```bash\n# Run tests + lint locally\npytest\nruff check .\n```\n\n---\n\n## Disclaimers\n\nThis project is **independent**. It is not affiliated with PSA, CGC,\nBeckett, The Pokemon Company, Nintendo, TCGPlayer, Cardmarket,\nPriceCharting, or any other organization. Each external API call is\nsubject to that provider's Terms of Service.\n\n---\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n\n---\n\n## Sources / further reading\n\n- [Model Context Protocol](https://modelcontextprotocol.io) — official site\n- [MCP Registry](https://modelcontextprotocol.io/registry) — discovery\n- [Pokemon TCG API](https://docs.pokemontcg.io/) — pricing + catalog\n- [PSA Public API](https://www.psacard.com/publicapi/documentation)\n- [PriceCharting API](https://www.pricecharting.com/api-documentation)\n",
  "bytes": 10373,
  "sha": "a7d6702fc3003088f344a12605a40123055d7b8f7135a72536163d329e401dcd",
  "repo_slug": "seanlok/tcg-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_seanlok_tcg_mcp_c62f5259/readme"
}