NeoSatoshi Card Recognition

NeoSatoshi 卡片识别 MCP 服务

适用于 NeoSatoshi 卡片识别 API 的 MCP 服务：让 Claude、Cursor、Codex 和其他 MCP 客户端识别照片中的 Pokémon、One Piece、Disney Lorcana、Yu-Gi-Oh!、Magic: The Gathering、Star Wars: Unlimited、Digimon Card Game 和足球卡（集换式卡牌册页面也适用；足球卡每张照片只能识别一张），并以 JSON 格式获取系列、编号、稀有度、Cardmarket ID 和每日价格（足球卡：球员、发行版本和异图），还可搜索卡片目录。

• 传输方式：stdio
• npm 包：neosatoshi-card-mcp，可执行文件 neosatoshi-card-mcp
• Node.js 18 或更高版本

工具

recognize_cards

参数	类型	说明
image_path	string	本地 .jpg、.jpeg 或 .png 文件，最大 12 MB（足球卡为 4 MB）。~ 会展开。
image_url	string	JPEG 或 PNG 的公开 https:// URL。原样转发给 API；服务不会下载图片。
image_base64	string	Base64 编码的 JPEG 或 PNG，可接受 data:image/...;base64, 前缀。
tcg	enum	pokemon（默认）、onepiece、lorcana、yugioh、magic、star_wars_unlimited、digimon、football

| include_images | boolean | 同时返回最多 10 张已识别卡片的目录图片（来自我们的 CDN，总大小最多 4 MB），以便助手与照片进行比对。默认值为 false。 |

请从 image_path、image_url、image_base64 中恰好选择一项。结果包含每张卡片的简短文本摘要、以 JSON 文本形式提供的完整 API 响应，以及相同的 structuredContent 响应。API 错误会作为工具错误返回，其中包含 API 的 error 代码和 message。

摘要示例：

1. Cinderace ex | Scarlet & Violet Black Star Promos (PR-SV) #163 | Promo | en | Cardmarket 796939 | trend 3.59 EUR | confidence 0.85 | 5 alternatives

Digimon 示例（异图共用卡片编号；印刷版本 ID 及其变体紧随系列信息）：

1. WarGreymon | RELEASE SPECIAL BOOSTER Ver.1.0 [BT01-03] (BT1) #BT1-025 | BT1-025_P1 Alternative Art | SR | en | Cardmarket 620026 | trend 16.85 EUR | TCGplayer 9.54 USD | confidence 1

Digimon Card Game（digimon），英文版和日文版：通过卡片编号和名称识别。若无法仅凭图片区分异图，print_unconfirmed 为 true，card_id 为 dg-c-<number>，且不含价格；印刷版本会作为备选项返回，每项均附带价格，可使用 correct_card 进行选择。英文版和日文版的 Cardmarket 价格（EUR），以及仅英文版的 TCGplayer 价格（USD）。不识别较早期的 Digimon 产品（1999 年的卡牌游戏、2000 年的集换式卡牌）。

足球卡示例（目前尚无价格；异图仅为建议，需由用户确认）：

1. Niklas Beste | 2025-26 Topps Chrome Bundesliga #BA-NBE | Base Cards Autograph Variation | Sport-Club Freiburg | parallel Gold Wave Refractor /50 (suggested, confirm it) | serial 37 | 2 alternatives | no price yet

当客户端发送进度令牌时（Claude Code、Claude Desktop 和大多数客户端都会发送），识别过程会以流式方式进行，并在识别出每张卡片后立即报告：在一页包含 8 张卡片的 Lorcana 页面上，第一张卡片约 8 秒后返回，全部 8 张约 11 秒后返回。

API 用于识别卡片；不会评估卡片品相（若卡片装在 PSA、BGS 或 CGC 鉴定盒中，足球卡还包括 SGC，返回结果会读取标签上的评分）。识别一张卡通常需要约 4 秒；静默一段时间后首次请求约需 10 到 12 秒；识别包含 9 张卡片的集换式卡牌册页面约需 17 秒；识别足球卡约需 6 到 25 秒。客户端最多等待 120 秒。

recognize_folder

参数	类型	描述
folder	字符串	存放照片的本地文件夹（不包括其子文件夹）。~ 会展开。
tcg	枚举	每个文件夹对应一种游戏。默认值为 pokemon。
max_files	整数	按名称顺序处理的照片数量上限。默认值为 20，上限为 100。
output	枚举	csv（默认值）、json（API 格式）或 both，将结果作为新文件写入文件夹。

每张照片检测一次，每张检测到的卡牌消耗 1 个额度。绝不会覆盖现有文件。如果发生会导致所有照片处理失败的错误（额度不足、密钥无效、达到演示版限额），则会提前停止。CSV 列：file、card_index、name、tcg、language、set_name、set_code、number、rarity、cardmarket_id、cardmarket_trend_eur、cardmarket_avg30_eur、tcgplayer_market_usd、confidence、graded、season、subset、parallel、request_id。以 =、+、- 或 @ 开头的单元格会加上前置 '，以免电子表格执行其内容。

search_cards

搜索卡牌目录；结果为完整卡牌对象，类似检测返回的对象（系列、编号、稀有度、Cardmarket 商品 ID、每日价格、图片），最多 10 条，包含 has_more，但不包含总数。使用来自 recognize_cards 的 request_id 和 card_index 时，这是免费的纠错搜索（24 小时内每张检测到的卡牌可搜索 5 次，最多返回 5 条结果）。不提供这些参数时，则为收费的卡牌搜索：返回卡牌时消耗 0.5 个额度。

足球：{"tcg": "football", "q": "kane chrome 2023"}，只能使用 q（球员，可选附加系列或赛季词），不能使用 language、set 或 number，目前不提供价格。每条结果都包含可用于 get_card 的 ref。

correct_card

将检测到的卡牌更正为目录中的正确卡牌（card_id 来自纠错搜索或该卡牌的备选项）。免费，须在 24 小时内完成，每张卡牌最多更正 3 次，且只能使用执行该检测的密钥。

get_card

通过 card_id 获取一张卡牌，例如用于刷新价格。卡牌存在时消耗 0.5 个额度。检测结果有误时，请改用 search_cards 并提供 request_id，再使用 correct_card；两者均免费。

足球：传入 search_cards 结果中的 ref（同一密钥，且须在 24 小时内）。随后返回的卡牌会包含其子系列的所有平行版本及其印量。没有有效的 ref 时，请求会被拒绝，且不收费。

export_cards

将最多 20 次检测的卡牌（recognize_cards 或 recognize_folder 返回的 request_ids，须在 48 小时内）导出为与 NeoSatoshi 网站导出相同的文件，并由网站自身的导出代码生成：你为新卡牌设置的状况、通过 correct_card 进行的更正、已保存的预设、价格规则和模板都会生效。

• format 为 csv/json（默认值为 csv）：自定义导出。使用 preset（已保存的预设 ID），或使用 fields 和 json_mode（api = 文档说明的卡牌格式，custom = 自选字段）。
• format 为 tcgpowertools：用于 Cardmarket 的 TCGPowerTools CSV（你的 TCGPowerTools 规则和已保存的备注；comment）。
• format 为 shopify：Shopify 商品 CSV，价格使用商店货币（store_currency，否则从已连接的商店读取；variant_mode）。
• format 为 ebay：适用于单个站点的 eBay Seller Hub CSV（marketplace，例如 EBAY_DE；one_row_per_card）。
• 对于最后三种格式：price_source、min_price、markup_percent 和 rounding 与网站定价步骤中的按钮类似（加价或舍入设置会替代你已保存的价格规则；markup_percent 设为 0 表示不加价）。save_to_folder 会将新文件写入允许的文件夹（绝不覆盖现有文件），否则文件会随答复返回（最多 100 KB）。免费，仅限自有密钥（演示检测不会保留卡牌），暂不支持足球。答复会列出未导出的卡牌（skipped），以及价格取决于特殊版本的卡牌（warnings）。

list_export_presets

已保存的导出预设（以及内置的推荐 CSV）和 export_cards 接受的所有字段 ID。免费。

list_supported_games

游戏、卡牌语言、tcg 值、限额和卡牌搜索价格。不调用 API，不收费。

费用

调用	自有密钥	演示密钥
recognize_cards	每检测到一张卡消耗 1 个积分；未检测到卡时不收费	每个网络每天 10 次
search_cards（卡片搜索）、get_card	返回卡片时消耗 0.5 个积分	每个网络每天 10 次搜索、3 次查询，永不收费
使用 request_id 调用 search_cards、correct_card	免费	免费
export_cards、list_export_presets	免费，每天可导出 200 次	不可用（演示检测不会保存卡片）

配置

变量	必需	说明
NEOSATOSHI_API_KEY	否	从 https://neosatoshi.com/dashboard/settings/settings#api-keys 获取的 API 密钥（适用于任何付费套餐）。不设置时将使用公共演示密钥：每个网络每天可检测 10 次。
NEOSATOSHI_ALLOWED_DIRS	否	image_path 可读取的目录，以 : 分隔（Windows 上使用 ;）。未设置时，允许读取任何可读取的图像文件。设置此项可限制助手能够发送的内容。

设置

Claude Code

claude mcp add neosatoshi-cards -e NEOSATOSHI_API_KEY=your_key -- npx -y neosatoshi-card-mcp

限制目录时：

claude mcp add neosatoshi-cards -e NEOSATOSHI_API_KEY=your_key -e NEOSATOSHI_ALLOWED_DIRS="$HOME/Pictures/cards" -- npx -y neosatoshi-card-mcp

若要使用演示密钥试用，请省略 -e NEOSATOSHI_API_KEY=...。

Claude Desktop，一键安装

下载 neosatoshi-card-mcp.mcpb 并打开：Claude Desktop 会安装扩展，并提示输入可选的 API 密钥和允许访问的可选文件夹。Claude Desktop 已附带 Node.js。

使用 npm run build:mcpb 自行构建（需要开发依赖）。

Claude Desktop，手动安装

添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json，Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "neosatoshi-cards": {
      "command": "npx",
      "args": ["-y", "neosatoshi-card-mcp"],
      "env": {
        "NEOSATOSHI_API_KEY": "your_key",
        "NEOSATOSHI_ALLOWED_DIRS": "/Users/you/Pictures/cards"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{
  "mcpServers": {
    "neosatoshi-cards": {
      "command": "npx",
      "args": ["-y", "neosatoshi-card-mcp"],
      "env": { "NEOSATOSHI_API_KEY": "your_key" }
    }
  }
}

Codex CLI

~/.codex/config.toml：

[mcp_servers.neosatoshi-cards]
command = "npx"
args = ["-y", "neosatoshi-card-mcp"]
env = { NEOSATOSHI_API_KEY = "your_key" }

从源代码安装

cd mcp-server
npm install
npm run build
node dist/index.js   # speaks MCP on stdin/stdout

将任意客户端指向 node /absolute/path/to/mcp-server/dist/index.js，而不是 npx。

安全性

• 文件：只读取常规文件。拒绝目录、设备、套接字和管道。先解析符号链接，再检查真实目标。仅接受内容以 JPEG 或 PNG 魔数开头的 .jpg、.jpeg 和 .png 文件，大小最多为 12 MB（足球类为 4 MB）。
• NEOSATOSHI_ALLOWED_DIRS 会根据解析后的真实路径进行检查，因此 ../ 和符号链接都无法越过限制。不存在的目录条目不会授予任何权限。
• 网络：服务只会调用 https://europe-west1-neosatoshi.cloudfunctions.net/detectApi 和 .../cardsApi；使用 include_images 时，还会调用我们的卡片图像 CDN https://d1m1gwcombja0u.cloudfront.net（会跳过其他图像主机）。
• 写入：只有 recognize_folder 会写入文件，并且只会在读取的文件夹中创建名为 neosatoshi_cards_<date>-<time>.csv / .json 的新文件（同样会检查 NEOSATOSHI_ALLOWED_DIRS）。image_url 会传递给 API，由 API 获取并验证；服务本身不会获取 URL。
• 不执行 Shell 命令。
• API 密钥只会通过 Authorization 标头发送。它不会被记录或返回，并且会从错误消息中清除。

开发

npm install
npm test     # builds, then runs node:test (file safety and tool tests with a fake fetch, no live API calls)

发布说明

• server.json 用于官方 MCP 注册表（https://registry.modelcontextprotocol.io）。其中的 name 与 package.json 中的 mcpName（io.github.Cookiebreed/card-recognition-mcp）一致；注册表会验证 io.github.* 名称对应的 GitHub 所有权。
• smithery.yaml 用于 Smithery。
• mcpb/manifest.json 和 scripts/build-mcpb.mjs 用于构建 Claude Desktop 扩展；将 neosatoshi-card-mcp.mcpb 上传到每个 GitHub 发行版，并使用该确切文件名。

许可证

此代码采用 MIT 许可证（参见 LICENSE）。API 是受 https://neosatoshi.com/termsofuse 约束的商业服务。