
TCG MCP
io.github.seanlok由 GitHub 账号 seanlok 发布v0.4.0更新于 Oct 24, 2026
Pokemon TCG MCP server: PSA grading, collection management, and multi-provider pricing.
概览
一个本地运行的宝可梦集换式卡牌 MCP 服务器,让助手查询 PSA 评级卡、管理卡牌收藏、跟踪关注清单并查询市场价格。
- 可以做什么
- 查询 PSA 证书、获取正反面图片并随时间记录评级数量快照,还能在一次调用中查询证书并登记为已拥有(CGC/BGS 仅为占位)。向本地收藏添加裸卡、评级卡或密封产品,列出并筛选、更新成本基础、标记售出或删除,并获取成本汇总或实时估值。搜索价格数据源,获取含各版本或各评级档位的完整报价,批量快照已关联卡牌并查询历史价格序列。管理带目标买入价、投资理由和持有周期的关注清单,并以原因关闭条目。列出已启用的评级与价格数据源及其所需的环境变量。
- 适用场景
- 适合收藏者和卖家让助手查询 PSA 证书信息、维护带成本基础的个人卡牌库存、关注目标买入价,并在聊天客户端内跟踪裸卡与评级卡的市场价格。
- 运行要求
- 通过 stdio 在本地运行;需要 Python 3.10 或更高版本(推荐 3.13),可用 uvx、pipx 或 pip 安装,并需要 Claude Desktop、Claude Code 或 Cursor 等 MCP 客户端。可选凭据:PSA_API_TOKEN 用于 PSA 工具,POKEMONTCG_API_KEY 用于提高速率上限,PRICECHARTING_TOKEN(付费)用于评级卡定价。TCG_DB_PATH 指定 SQLite 文件位置,默认 ~/.tcg-mcp/tcg.db。需要访问外部 API 的网络连接。
安装
在 SourceWeft 中
- 打开 控制台中的 TCG MCP,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
tcg-mcp
A Pokemon TCG MCP server. Looks up graded cards (PSA today, CGC/BGS stubbed), manages your owned collection in a local SQLite DB, queries pricing providers (Pokemon TCG API + PriceCharting), tracks a watchlist with target prices, and snapshots PSA pop counts so you can see trends over time.
[PyPI] [Python] [Downloads] [CI] [License: MIT]
tcg-mcp is a Model Context Protocol
server. Install it once, wire it into Claude Desktop / Claude Code / Cursor /
any MCP client, and your assistant gains 25 tools for working with PSA cert
data, your personal collection, and live market prices.
What it does — 25 tools, namespaced
PSA grading (tcg_psa_*) — cert lookup, front/back images, snapshot pop
data over time, plus a workflow tool that looks up a cert and records it as
owned in one call.
CGC / BGS (tcg_cgc_*, tcg_bgs_*) — stubs in v0.2; no public API exists
for either grader. Listed for routing parity; will route cleanly if either
grader publishes an API.
Collection (tcg_collection_*) — add raw or graded cards (or sealed
products: ETBs, booster boxes, UPCs, tins), list with filters, update cost
basis, soft-delete (mark sold) or hard-delete, attach a card to a pricing
listing, get a cost-basis summary or a live market valuation that joins
against the most recent pricing snapshots.
Pricing (tcg_pricing_*) — search a provider, get a full price quote
(top-level market/low/high plus per-variant breakdown for Pokemon TCG API,
plus per-grade levels for PriceCharting), persist snapshots into the local
DB, bulk-snapshot every attached card in one call with per-provider
rate-limit awareness, and query historical snapshots as a time series
for trend analysis.
Watchlist (tcg_watchlist_*) — add target buy prices with thesis text,
list by horizon (flip / hold / sealed), update, and close with a reason
(bought / thesis_invalidated / manual).
Meta (tcg_list_providers) — discovery tool that shows which grading +
pricing providers are enabled, what env var each needs, and what tools are
in the namespace.
For the full tool list run tcg_list_providers after install or read the
architecture doc.
Prerequisites
- Python 3.10 or newer (3.13 recommended).
- An MCP client — Claude Desktop, Claude Code, Cursor, Continue, etc.
- (Optional, for PSA tools only) A PSA Public API token — free, sign up at psacard.com/publicapi.
The server works without any tokens — Pokemon TCG API queries, collection, and watchlist tools all function on a fresh install with zero credentials.
Install
Option A — uvx (recommended, zero install)
Option B — pipx
Option C — pip
Option D — from source (for contributors)
Configure
Copy .env.example to .env and fill in any tokens you have:
Or set the env vars however your client supports it (most clients let you
specify env per MCP server in the config).
Wire it into your MCP client
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS),
%APPDATA%\Claude\claude_desktop_config.json (Windows), or
~/.config/Claude/claude_desktop_config.json (Linux):
Quit Claude Desktop fully (⌘Q on macOS — closing the window isn't enough) and relaunch.
Claude Code
Then export the tokens you have in the shell that runs claude.
Cursor / Continue / etc.
Same shape — point the client at:
Smoke-test it
After wiring up the client, ask it:
"Use tcg-mcp to list providers."
You should see pokemontcg enabled, plus psa enabled if your token is
set, and stubs for the others.
Then try a real lookup:
"Search Pokemon TCG API for Charizard ex from Obsidian Flames."
"Add a 1999 Pokemon Base Set Charizard #4 (raw) to my collection — paid $250 on 2026-04-15."
"Add Charizard ex Surging Sparks to my watchlist with a target buy price of $180."
"What's my collection cost basis?"
Architecture, briefly
Provider abstractions (providers/base.py,
pricing/base.py) make adding a new grader
or pricing source a single-file change. See
docs/adding-a-provider.md.
Local SQLite database
All your personal data — collection, watchlist, pricing snapshots, pop
snapshots — lives in a single SQLite file. Default location is
~/.tcg-mcp/tcg.db. Point TCG_DB_PATH at any path you prefer.
The file format is plain SQLite, so you can inspect or back up the data directly:
Schema is in src/tcg_mcp/storage/schema.sql.
Migrations are forward-only and idempotent (safe to run on every startup).
Known limits
- PSA images only exist for cards graded after October 2021. Older slabs return an empty image list — that's the upstream API, not a bug.
- PSA's
Brandfield is the closest thing to a clean "set name" in their schema. We surface it asset_name; for finer-grained set parsing, reach into the raw payload. - CGC / BGS providers are stubs in v0.2. They're listed for discovery
but raise
NotSupportedErrorif called. Implementation depends on either grader publishing a public API or an explicit decision to support polite scraping. - Rate limits on the PSA free tier aren't publicly documented. If you see "PSA API rate limit exceeded", wait or upgrade your plan.
- PriceCharting is paid-only. Without a
PRICECHARTING_TOKENthe provider is registered asdisabledand graded-card prices aren't available — but Pokemon TCG API still gives you raw market prices.
Roadmap
Standing constraint: every milestone below has a free path as the default. Paid providers (GemRate, eBay Marketplace Insights, etc.) stay optional add-ons that activate only when their key is configured.
- ✅ v0.3 — shipped:
tcg_pricing_snapshot_collection,tcg_pricing_get_history, rounded per-item valuation, clearer PSA 429 error message,CHANGELOG.md. - ✅ v0.4 — shipped: Catalog tools (
tcg_catalog_*) backed by Pokemon TCG API,tcg_collection_set_completionwith watchlist intersection, richertcg_collection_search, smart-routedtcg_pricing_get_card. - v0.5 — CGC support (free path: polite scraping; optional paid GemRate).
- v0.6 — BGS support (free path: polite scraping; optional paid GemRate).
- v0.7 — eBay sold comps (free path: eBay Browse API + scraping; optional paid Marketplace Insights API).
See CHANGELOG.md for the full version history.
Contributing
Contributions welcome. To add a new grading or pricing provider, see
docs/adding-a-provider.md. The contract is
intentionally small: implement a Protocol method, register it conditionally
based on credentials, write a mock-httpx test.
Disclaimers
This project is independent. It is not affiliated with PSA, CGC, Beckett, The Pokemon Company, Nintendo, TCGPlayer, Cardmarket, PriceCharting, or any other organization. Each external API call is subject to that provider's Terms of Service.
License
MIT — see LICENSE.
Sources / further reading
- Model Context Protocol — official site
- MCP Registry — discovery
- Pokemon TCG API — pricing + catalog
- PSA Public API
- PriceCharting API
来源:README.md,提交 8b62789
工具
0版本历史
1- v0.4.0最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分
