Pokémon TCG API

@pokemontcgapi/mcp

适用于 Pokémon TCG API 的 MCP 服务，API 位于 pokemontcgapi.com。它为 Agent 提供 11 个工具，覆盖整个 目录：国际版、日文版和简体中文版的印刷系列，8 种语言环境的卡牌名称、插画师、图片，以及附带来源、 依据、评级和样本量的价格。当前数量可通过 /v1/status 实时查看，详细分类见 coverage.json。

这是非官方项目。该项目并非由 Nintendo、Creatures Inc.、GAME FREAK inc. 或 The Pokémon Company International 制作、认可或支持，也与它们无关。Pokémon 及所有相关标志均为其各自所有者的商标。

获取密钥

每次注册生成一个 Idempotency-Key，并将其与请求正文一同保存：

IDEM=$(uuidgen)

curl -s -X POST "https://api.pokemontcgapi.com/v1/accounts/free" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEM" \
  -d '{"email":"[email protected]"}'

如果未收到响应？请在 24 小时内重复发送完全相同的请求（Idempotency-Key 相同、正文逐字节相同、网络相同：同一公网 IPv4 或同一 IPv6 /64）。如果响应已存储，系统会返回原响应，其中包括密钥；这是原始响应，因此之后轮换或撤销的密钥不会恢复。使用新的 Idempotency-Key 注册同一邮箱会返回 409 ACCOUNT_EXISTS；使用相同密钥搭配不同正文会返回 409 IDEMPOTENCY_CONFLICT。

我们只存储密钥的哈希；注册响应会保留 24 小时，以便重放相同请求。请立即保存 data.key.secret。

如果无法重放，请登录并轮换密钥，或使用已验证的邮箱访问 /v1/accounts/recover 以获取新密钥。

密钥会通过 data.key.secret 返回。确认我们发送邮件中的地址后，试用额度会从 80 增至 800 点数，试用期于注册 30 天后结束。付费方案每月 29 EUR 起： 价格。

安装

Claude Code：

claude mcp add pokemontcgapi --env PTCG_API_KEY=your-key -- npx -y @pokemontcgapi/mcp

Claude Desktop — claude_desktop_config.json：

{
  "mcpServers": {
    "pokemontcgapi": {
      "command": "npx",
      "args": ["-y", "@pokemontcgapi/mcp"],
      "env": { "PTCG_API_KEY": "your-key" }
    }
  }
}

Cursor — .cursor/mcp.json：

{
  "mcpServers": {
    "pokemontcgapi": {
      "command": "npx",
      "args": ["-y", "@pokemontcgapi/mcp"],
      "env": { "PTCG_API_KEY": "${env:PTCG_API_KEY}" }
    }
  }
}

VS Code — .vscode/mcp.json。请注意，顶层键为 servers，而不是 mcpServers；inputs 可避免将密钥写入已提交的文件：

{
  "inputs": [
    { "id": "ptcg-key", "type": "promptString", "description": "pokemontcgapi key", "password": true }
  ],
  "servers": {
    "pokemontcgapi": {
      "command": "npx",
      "args": ["-y", "@pokemontcgapi/mcp"],
      "env": { "PTCG_API_KEY": "${input:ptcg-key}" }
    }
  }
}

环境变量：PTCG_API_KEY（11 个工具中有 10 个需要），以及 PTCG_BASE_URL（默认为 https://api.pokemontcgapi.com）。Node ≥ 20。例外是 ptcg_get_reference，它读取公开路由。ptcg_get_catalogue_status 并非例外：它会先访问公开的 /v1/status， 然后按每个印刷地区读取一套数据，这需要密钥。没有密钥时，服务会启动并列出其工具，但随后这 10 个调用都会提示需要密钥。

工具

共有 11 个工具，并非每个端点各一个。每轮中，tools/list 都会占用模型的上下文，因此完整工具集约为 11 KB；每个工具的设计都像一个问题，而不是一条路由——模型无需串联 4 次调用来回答一个问题。

工具	回答的问题
ptcg_search_cards	“日本系列中的喷火龙卡牌”，可按名称、系列、地区、稀有度、画师或发行时间段搜索
ptcg_get_cards	一次调用最多查询 100 个 ID；base1-4 和 bs-4 都能正确解析
ptcg_get_card_prices	卡牌的所有当前观测数据，包含印次、品相、as_of 和 sample_n
ptcg_list_sets	“2024 年发行的所有日本系列”
ptcg_get_reference	类型、超类型和稀有度的精确字符串，避免猜测筛选条件
ptcg_list_artists	插画师及每位插画师绘制的卡牌数量
ptcg_get_catalogue_status	目录包含和不包含哪些内容，并实时衡量
ptcg_measure_centering	将单面照片转换为比例、不确定性和几何信息。消耗 25 个额度；没有上下限时显示“需要审核”属于预期情况
ptcg_grade_centering	根据已知的正面／轴线比例计算仅基于居中度的分数上限。消耗 1 个额度
ptcg_get_centering_standards	PSA/BGS/CGC/SGC 的阈值、来源状态和 URL。消耗 1 个额度
ptcg_identify_card_from_image	“这张照片里是哪张卡？”——返回排序后的候选结果；若重印版共用同一图案，则会明确拒绝识别。每次调用消耗 25 个额度；Growth 及以上套餐包含此功能

所有工具都标注了 readOnlyHint: true 和 destructiveHint: false。这里的工具都不会写入数据。 ptcg_identify_card_from_image 和 3 个居中度工具标注了 idempotentHint: false： 每次调用都会消耗额度。请勿自动重试付费操作。

Growth 及以上套餐包含居中度功能；Developer 套餐不包含。经验证的免费试用分别包含 5 次测量调用和 5 次确认调用。评分和标准没有单独的试用调用计数器。 测量功能接受 base64 图像字节、明确的正面／背面、可选的 standard/small 卡片尺寸，以及经校正的角点（TL、TR、BR、BL；使用 EXIF 方向校正后的像素坐标，并缩小至最长边不超过 2560 px）。 返回结果包含比例、不确定性和可编辑的几何信息；没有上下限时显示“需要审核”属于预期情况。 使用另一次测量校正角点后，由人员在应用中检查或移动裁切线和印刷线。应用调用 confirm 后会返回评分上限；也可以通过 grade 根据已知比例获取评分上限。

我们刻意不提供 confirm 工具。助手无法声称有人审核过这些线条。只有收集到该人员明确同意的应用，才能发送 confirmed_by: person。 请始终显示仅基于居中度得出的上限，而非最终评分的预测。绝不能将结果标记为已验证或已认证。请保留来源状态、不完整标记和不确定性，确保它们清晰可见。 请参阅两步指南。

商业限制导致的拒绝会在工具结果的第一行提供 next_step.handoff，后面附有 API 消息和完整详情。请原样向账户所有者展示该句及其 URL，且不要重试。所有者需完成结账、电子邮件验证或联系步骤。CARD_ALLOWANCE_EXCEEDED 也属于此类情况：当前周期已达到不同卡牌数量的检索上限（试用为 1,000 张，Developer 每月为 30,000 张）；已检索的卡牌仍可正常查询，新的卡牌则需等到下个周期或升级至 Growth。

导入卡牌目录

如需完整导入卡牌，请直接使用 REST API： GET /v1/cards?limit=250&orderBy=id，然后原样跟随 links.next。扁平列表会跨卡牌系列分页，比针对每个系列单独循环卡牌所需的请求更少。 添加 include=translations，即可按普通目录的费用获取名称。收费的 include 项目采用单独的费率。 如需限定单个印刷地区，请添加 q=set.region:JP 或 q=set.region:CN；lang 仅用于选择名称译文。 需要查询特定系列时，请使用 /v1/sets/{code}/cards；浏览系列元数据时，请使用 /v1/sets?region=JP。

快速入门指南包含两种分页循环和有日期标注的测量数据。 迁移指南说明了如何在导入前记录变更流水位，并在导入后维护副本。 MCP 搜索工具用于范围有限的交互式搜索；其 region 参数会以 set.region:JP（或 CN、WEST）的形式发送给 API，因此日文搜索只会读取日文数据行。完整导入请使用 REST。

此 API 不具备的内容

之所以提供最后一个工具，正是因为本节所述内容；该工具会通过实时调用返回这些事实，而不是让模型自行推断：

• 没有韩文卡牌。 KR 系列数量为零，ko 译文数量也为零。印刷地区和语言环境已纳入架构模型，但没有对应数据，因此按这些字段筛选会返回空结果，而不是报错。
• 卡牌游戏文本为英文，且覆盖不均。 自 2026 年 9 月 3 日起，attacks、abilities、weaknesses、resistances、subtypes、retreat_cost、rules 和 flavor_text 字段中才有数据，涉及 20,725 张西方地区印刷的卡牌。截至 2026 年 9 月 16 日，以 57,450 张卡牌为基准测得：整个目录中 attacks 的覆盖率为 29.9%，西方地区部分为 82.9%；subtypes 为 35.0%，weaknesses 为 28.0%，flavor_text 为 17.9%，abilities 为 7.0%，rules 为 5.1%。日文和中文印刷的卡牌均不包含这些数据，因此 attacks 为 null 表示我们没有这项数据，绝不表示该卡牌没有攻击。
• 没有赛制合法性数据。 卡牌对象不包含 legalities 字段，level 也为空。如果问题涉及套牌是否合法，此 API 无法回答。

这三项数据均经过测量，在来源中标注了日期，并且在工具说明中逐字重复，因此 Agent 会在调用工具前就获知，而不是调用后才知道。

正确读取价格

没有印刷版本筛选器。初版、无限版、全息、反向全息和评级行都会一起返回，因此应读取每一行的 printing、condition 和 grading，而不是只看第一个数字。basis 用于区分上游发布的 GUIDE 与我们计算得出的 DERIVED；PTCG_INDEX 是我们自己的欧元综合指数，并带有 sample_n。每条观测都有 as_of 日期，且至少延迟一天——引用价格时务必注明日期。

计划限制的内容会明确列出，而不是隐藏起来：试用密钥无法获取 graded 和 non_english_locales，Developer 计划无法获取 graded，Growth 及以上计划则没有限制。API 会在价格路由的 meta.withheld 中、价格随卡片返回时的 X-Plan-Withheld 标头中，以及批量响应顶层的 withheld 字段中说明这些限制。因此，没有评级行的卡片可能是受计划限制，而不是目录中没有数据。

对于 ptcg_get_cards，只要 API 返回 missing 字段，该字段就是权威依据，包括其中的 suggested_id 值。工具会保留现有的字符串数组 missing，并新增一个由 { id, suggested_id? } 组成的数组 missing_details；文本中也会显示每条建议。如果 API 未返回 missing，工具会通过比较请求的 ID 与返回的 id 和 legacy_id 来进行回退处理，比较时忽略大小写和重复 ID。这样无需额外请求即可支持较旧的 API 版本，但无法发现这些版本未报告的规范集合冲突或建议。当前 API 在所有 ID 都能匹配时会省略 missing，此时回退逻辑会返回空数组。 ptcg_get_card_prices 会读取卡片及其价格，因此相关排除信息会通过该标头返回。

上下文管理

无论 API 允许返回多少行，结果最多返回 50 行，并以对齐表格而非 JSON 的形式发送，同时只选取精简的字段。由于每行不会重复列出键，同样的行用表格表示会比用 JSON 更短；但我们不会公布百分比，因为没有可复现的测量结果可供佐证。 发生截断时，始终会告知用户，并提供用于继续获取结果的游标。价格行是唯一不会截断的内容。

协议

基于 @modelcontextprotocol/server v2 构建，协商使用 2025-11-25 版本，并接受最低至 2024-10-07 的客户端。使用 stdio 传输。

该版本是库的版本，并非我们自行声明：@modelcontextprotocol/[email protected] 中的 SUPPORTED_PROTOCOL_VERSIONS 最高为 2025-11-25，因此客户端请求更新版本时，收到的响应会是该版本。我们已根据已发布的包进行验证，而不是依据变更日志。

另有提供

• TypeScript SDK，无运行时依赖：@pokemontcgapi/sdk — 源代码
• 文档：https://pokemontcgapi.com/docs
• 覆盖情况，实时测量：https://pokemontcgapi.com/coverage

从源代码构建

npm ci
npm run typecheck
npm run build

Node >= 20。npm test 会运行 tests/ 中的单元测试。CI 强制检查的是：软件包必须能在 Node 20 和 Node 22 上完成类型检查和构建，并且 npm pack 生成的文件列表必须符合注册表预期接收的内容。

此软件包在一个私有单体仓库中开发，该仓库负责运行 pokemontcgapi.com，并在每次发布时将代码镜像到这里， 因此合并的拉取请求需要手动同步回来，不能通过合并按钮完成。这并不意味着应该把补丁发送到别处——请在这里提交问题或拉取请求，这里才是会有人查看的地方。

许可证

MIT。API 提供的数据受各来源的再分发条款约束——请参阅 https://pokemontcgapi.com/legal/attribution。