TCG MCP

tcg-mcp

一款 Pokemon TCG MCP 服务。可查询经过评级的卡牌（目前支持 PSA，CGC/BGS 尚未实现），在本地 SQLite 数据库中管理已拥有的收藏，查询定价服务（Pokemon TCG API + PriceCharting），通过目标价格追踪关注列表，并记录 PSA 人数统计快照，以便查看随时间变化的趋势。

tcg-mcp 是一个 Model Context Protocol 服务。只需安装一次，将其接入 Claude Desktop / Claude Code / Cursor / 任何 MCP 客户端，即可让你的助手获得 25 个工具，用于处理 PSA 证书 数据、个人收藏和实时市场价格。

---

功能介绍 — 25 个工具，按命名空间划分

PSA 评级（tcg_psa_*） — 查询证书、获取卡牌正反面图片、记录并查看 随时间变化的人数统计快照；还提供一个工作流工具，可一次调用完成证书查询 并将卡牌记录为已拥有。

CGC / BGS（tcg_cgc_*、tcg_bgs_*） — 在 v0.2 中为占位工具；这两家评级机构均没有公开 API。为保持路由一致性而列出；如果任一机构发布 API，将可直接路由。

收藏（tcg_collection_*） — 添加未评级或已评级卡牌（或密封产品：ETB、补充包盒、UPC、铁盒），按筛选条件列出、更新成本基础、软删除（标记为已售出）或硬删除、将卡牌关联到定价条目、获取成本基础摘要，或获取实时市场估值（与最新定价快照进行关联）。

定价（tcg_pricing_*） — 搜索服务、获取完整报价（Pokemon TCG API 提供顶层市场价/低价/高价及各变体明细；PriceCharting 提供各评级等级的价格），将快照保存到本地数据库，一次调用批量记录所有已关联卡牌的快照（并考虑各服务的速率限制），以及将历史快照作为时间序列查询，用于趋势分析。

关注列表（tcg_watchlist_*） — 添加附带理由文本的目标买入价，按持有周期（翻转 / 持有 / 密封）列出、更新，并填写原因后关闭（已买入 / 理由失效 / 手动关闭）。

元数据（tcg_list_providers） — 用于发现的工具，可显示启用的评级和定价服务、各服务所需的环境变量，以及命名空间中的工具。

如需查看完整工具列表，请在安装后运行 tcg_list_providers，或阅读 架构文档。

---

前置条件

1. Python 3.10 或更高版本（推荐 3.13）。
2. MCP 客户端 — Claude Desktop、Claude Code、Cursor、Continue 等。
3. （可选，仅用于 PSA 工具） PSA Public API 令牌 — 免费，可在 psacard.com/publicapi 注册获取。

无需任何令牌即可运行服务——全新安装且无需凭据，也能使用 Pokemon TCG API 查询、收藏和关注列表工具。

---

安装

选项 A — uvx（推荐，无需安装）

# install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# run the server (auto-installs the package on first use)
uvx tcg-mcp --help

选项 B — pipx

pipx install tcg-mcp
tcg-mcp --help

选项 C — pip

python3 -m pip install tcg-mcp

选项 D — 从源码安装（适用于贡献者）

git clone https://github.com/seanlok/tcg-mcp.git
cd tcg-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest        # run the test suite

---

配置

将 .env.example 复制为 .env，并填写你拥有的令牌：

cp .env.example .env
$EDITOR .env

也可以根据客户端支持的方式设置环境变量（大多数客户端允许在配置中为每个 MCP 服务指定 env）。

环境变量	用途	说明
PSA_API_TOKEN	PSA 工具	获取令牌 — 免费
POKEMONTCG_API_KEY	提高 Pokemon TCG API 速率限制（可选）	获取密钥 — 免费
PRICECHARTING_TOKEN	PriceCharting 工具	需要付费订阅
TCG_DB_PATH	本地数据库位置	默认值为 ~/.tcg-mcp/tcg.db

将其接入 MCP 客户端

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）、 %APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/.config/Claude/claude_desktop_config.json（Linux）：

{
  "mcpServers": {
    "tcg-mcp": {
      "command": "uvx",
      "args": ["tcg-mcp"],
      "env": {
        "PSA_API_TOKEN": "your-token-here",
        "TCG_DB_PATH": "~/Documents/tcg-mcp.db"
      }
    }
  }
}

完全退出 Claude Desktop（macOS 上按 ⌘Q——仅关闭窗口还不够）， 然后重新启动。

Claude Code

claude mcp add tcg-mcp -- uvx tcg-mcp

然后在运行 claude 的 shell 中导出你拥有的令牌。

Cursor / Continue / 等

格式相同——将客户端指向：

command: uvx
args:    ["tcg-mcp"]
env:     PSA_API_TOKEN=...    # optional

---

冒烟测试

接入客户端后，向它提问：

“使用 tcg-mcp 列出提供方。”

你应该会看到 pokemontcg 已启用；如果设置了令牌，psa 也会启用，其他提供方则显示为存根。

然后尝试实际查询：

“在 Pokemon TCG API 中搜索 Obsidian Flames 系列的 Charizard ex。”

“将一张 1999 Pokemon Base Set Charizard #4（未评级）添加到我的收藏中——于 2026-04-15 以 $250 购入。”

“将 Charizard ex Surging Sparks 添加到我的关注列表，目标买入价为 $180。”

“我的收藏成本是多少？”

---

架构简介

+----------------------+
|     MCP client       |  Claude Desktop, Cursor, etc.
+----------+-----------+
           | stdio (JSON-RPC)
+----------v-----------+
|     server.py        |  FastMCP — tool registration, validation
+----------+-----------+
           |
   +-------+-------+----------------+
   |               |                |
+--v--+         +--v--+        +----v----+
| psa |  ...    |pricing|      | storage |  SQLite — collection,
+--+--+         +--+----+      +----+----+  watchlist, pop trends,
   | httpx         | httpx          |       pricing snapshots
+--v---------------v----+      +----v----+
|  PSA / Pokemon TCG    |      | tcg.db  |
|  API / PriceCharting  |      +---------+
+-----------------------+

提供方抽象（providers/base.py、 pricing/base.py）使添加新的评级服务 或定价来源只需修改一个文件。请参阅 docs/adding-a-provider.md。

---

本地 SQLite 数据库

你的所有个人数据——收藏、关注列表、价格快照、流通量 快照——都存放在一个 SQLite 文件中。默认位置为 ~/.tcg-mcp/tcg.db。将 TCG_DB_PATH 指向你偏好的任意路径。

文件格式为标准 SQLite，因此你可以直接检查或备份数据：

sqlite3 ~/.tcg-mcp/tcg.db
.tables
SELECT subject, grade, acquisition_price FROM owned_cards WHERE status='owned';

数据库架构见 src/tcg_mcp/storage/schema.sql。 迁移仅向前进行且具备幂等性（可在每次启动时安全运行）。

---

已知限制

• PSA 图片仅适用于 2021 年 10 月之后评级的卡牌。更早的 卡砖会返回空图片列表——这是上游 API 的限制，并非程序错误。
• PSA 的 Brand 字段是其架构中最接近规范“系列名称”的字段。我们将其显示为 set_name；如需更细致地解析系列信息， 请查看原始数据。
• CGC / BGS 提供方在 v0.2 中是存根。它们会列出以供发现， 但调用时会抛出 NotSupportedError。具体实现取决于评级机构是否发布公共 API，或是否明确决定支持适度抓取。
• PSA 免费套餐的速率限制没有公开说明。如果你看到“PSA API rate limit exceeded”，请稍候或升级套餐。
• PriceCharting 仅提供付费服务。未设置 PRICECHARTING_TOKEN 时，该提供方会注册为 disabled，无法获取评级卡牌价格——但 Pokemon TCG API 仍会提供未评级卡牌的市场价格。

---

路线图

持续约束：以下每个里程碑都以免费路径为默认方案。付费提供方（GemRate、eBay Marketplace Insights 等）仍为可选附加项，仅在配置相应密钥后启用。

• ✅ v0.3 — 已发布：tcg_pricing_snapshot_collection、 tcg_pricing_get_history、按单件取整估值、更清晰的 PSA 429 错误消息、CHANGELOG.md。
• ✅ **v0.4 — 已发布：**由 Pokemon TCG API 提供支持的目录工具（tcg_catalog_*）、支持与关注列表求交的 tcg_collection_set_completion、更丰富的 tcg_collection_search、智能路由的 tcg_pricing_get_card。
• v0.5 — 支持 CGC（免费路径：适度抓取；可选付费 GemRate）。
• v0.6 — 支持 BGS（免费路径：适度抓取；可选付费 GemRate）。
• v0.7 — eBay 已售商品对比（免费路径：eBay Browse API + 抓取；可选付费 Marketplace Insights API）。

完整版本历史请参阅 CHANGELOG.md。

---

贡献

欢迎贡献。要添加新的评级或定价提供方，请参阅 docs/adding-a-provider.md。约定刻意保持精简：实现一个 Protocol 方法，根据凭据有条件地注册，并编写一个 mock-httpx 测试。

# Run tests + lint locally
pytest
ruff check .

---

免责声明

本项目独立运营，与 PSA、CGC、Beckett、The Pokemon Company、Nintendo、TCGPlayer、Cardmarket、PriceCharting 或任何其他组织均无关联。每次调用外部 API 均须遵守相应服务提供商的服务条款。

---

许可证

MIT — 详见 LICENSE。

---

来源 / 延伸阅读

• Model Context Protocol — 官方网站
• MCP Registry — 发现服务
• Pokemon TCG API — 价格与目录
• PSA Public API
• PriceCharting API