MCP server

Card recognition in Claude, Cursor, VS Code and Codex

Our MCP server lets your AI assistant identify trading cards in a photo, value a binder page, turn a folder of photos into a spreadsheet and fix a wrong card. Pokémon, One Piece, Disney Lorcana, Yu-Gi-Oh!, Magic: The Gathering, Star Wars: Unlimited and football (soccer) cards, with Cardmarket product ID and daily prices.

Claude Code

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

Leave out -e NEOSATOSHI_API_KEY=... to try it with the public demo key. npm package neosatoshi-card-mcp, source on GitHub (MIT), official MCP registry: io.github.Cookiebreed/card-recognition-mcp.

Tools

What the assistant can do, and what it costs on your own key.

Tool	What it does	Cost
`recognize_cards`	Identify the cards in one photo (local file, https link or base64). Several cards per photo in all six trading card games; football one card front. Reports each card as soon as it is recognised, and on request returns the catalog images to compare.	One credit per detected card; nothing for a photo without a card
`recognize_folder`	Every JPEG and PNG in a folder, one detection per photo, written to a new CSV or JSON file in that folder (name, set, number, rarity, Cardmarket ID and prices per card).	One credit per detected card
`search_cards`	Search the catalog by card name, name and number, a printed code or set + number; football by player. With a request_id it is the free correction search for a wrong detection.	0.5 credits when it returns a card; correction search free
`correct_card`	Replace a wrongly detected card with the right one, within 24 hours of the detection.	Free
`get_card`	One card by its card_id, for example to refresh a stored price.	0.5 credits when the card exists
`list_supported_games`	Games, card languages and limits.	Free, no API call

Credits come from your plan's card scans, the same balance as the app. Without a key the public demo key allows 10 detections, 10 searches and 3 lookups per day per network and is never charged.

Setup

Node.js 18 or newer. Replace YOUR_API_KEY with a key from your dashboard, or leave the env out for the demo key.

Claude Code

One command in your terminal.

bash

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

Claude Desktop

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude.

json

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

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (project). Same JSON as Claude Desktop.

json

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

VS Code (Copilot agent mode)

.vscode/mcp.json in your workspace.

json

{
  "servers": {
    "neosatoshi-cards": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "neosatoshi-card-mcp"],
      "env": { "NEOSATOSHI_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Codex CLI

~/.codex/config.toml

toml

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

Your own key: dashboard settings, API keys (any paid plan). To limit which folders the assistant may read, add NEOSATOSHI_ALLOWED_DIRS (folders separated by :, on Windows ;).

Example chats

Ask in plain words; the assistant picks the tool.

“What are the cards on ~/Pictures/binder-page-3.jpg worth? Sort them by price.”

recognize_cards reads the binder page and returns every card with its Cardmarket trend price; the assistant sorts and sums them.

“Scan my folder ~/Pictures/lorcana-lot and give me a CSV for my spreadsheet.”

recognize_folder runs every photo once and writes neosatoshi_cards_<date>.csv into the folder.

“Card 4 is wrong, it is the foil Elsa from The First Chapter. Fix it.”

search_cards with the request_id finds the right card for free, correct_card replaces it and also improves the recognition.

“Which Harry Kane Topps Chrome cards exist from 2023, and which parallels are numbered?”

search_cards with tcg football finds the cards, get_card lists the parallels of a card with their print runs.

Questions

Is there an MCP server for trading card recognition?

Yes. neosatoshi-card-mcp is an MCP server (stdio) for Claude, Cursor, VS Code, Codex and other MCP clients. It identifies Pokémon, One Piece, Disney Lorcana, Yu-Gi-Oh!, Magic: The Gathering, Star Wars: Unlimited and football (soccer) cards in a photo and returns set, number, rarity, Cardmarket product ID and daily prices. It is listed in the official MCP registry as io.github.Cookiebreed/card-recognition-mcp.

Can I try it without an account?

Yes. Without NEOSATOSHI_API_KEY the server uses the public demo key: 10 detections, 10 searches and 3 lookups per day per network, never charged. For more, create your own key on any paid plan.

Does it estimate card condition?

No. It identifies which card it is. On a PSA, BGS or CGC slab (football also SGC) it reads the grade from the label, but it never estimates a grade or condition.

Which files can the assistant read?

Only JPEG and PNG files, checked by their content, at most 12 MB (football 4 MB). Set NEOSATOSHI_ALLOWED_DIRS to the folders it may read; symlinks cannot escape it. The server writes only recognize_folder results, as new files, and never overwrites one.

Calling the REST API yourself? Everything per game is in the Detection API documentation, and the spec is at /openapi.json.