Metadata-Version: 2.4
Name: cardshowdata-mcp
Version: 1.0.0
Summary: Model Context Protocol server for the CardShowData TCG pricing API
Project-URL: Homepage, https://cardshowdata.com
Project-URL: Documentation, https://cardshowdata.com/docs
Project-URL: Support, https://cardshowdata.com/support
Author-email: CardShowData <support@cardshowdata.com>
License-Expression: MIT
Keywords: claude,lorcana,magic,mcp,pokemon,pricing,tcg,yugioh
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# CardShowData MCP Server

Model Context Protocol server for the [CardShowData](https://cardshowdata.com) TCG pricing API. Lets AI assistants (Claude Desktop, Claude Code, ChatGPT, Cursor, etc.) answer questions like "What's a Base Set Charizard worth?" or "Which Pokemon cards spiked this week?" with live pricing data.

## Install

The recommended way is via [`uvx`](https://docs.astral.sh/uv/), which fetches and runs the latest published version with no setup:

```bash
uvx cardshowdata-mcp
```

You'll need a free API key — sign up at [cardshowdata.com](https://cardshowdata.com).

## Configure in Claude Desktop / Claude Code

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "cardshowdata": {
      "command": "uvx",
      "args": ["cardshowdata-mcp"],
      "env": {
        "CSD_API_KEY": "your_api_key"
      }
    }
  }
}
```

Restart Claude Desktop. The 14 tools below become available immediately.

## Tools

| Tool | What it does |
|------|--------------|
| `search_cards` | Search cards by name, optional 2-letter TCG filter (`pk`, `mt`, `lc`, `op`, `dg`, ...) |
| `get_card` | Full card detail by `pretty_id` (e.g. `pk_bs_004`) or `csd_product_id` UUID |
| `get_pricing` | Latest per-variant pricing in USD cents |
| `get_grading` | Graded prices (PSA, BGS, CGC, SGC, TAG, AGS, ACE) with high/median/low |
| `get_pricing_history` | Daily price snapshots, per-variant time series |
| `get_lifecycle` | Per-variant first/last seen, peak, decay half-life |
| `get_pricing_changes` | Variants with significant price movement since a given timestamp |
| `get_ebay_sales` | Recent eBay sold listings for a graded card |
| `list_tcgs` | Every TCG with `tcg_slug`, `tcg_code`, product/set counts |
| `list_sets` | Sets/expansions for a TCG with set codes |
| `search_catalog` | Quick fuzzy product search across every TCG |
| `refresh_population` | Trigger an on-demand grading population refresh (Pro+) |
| `get_usage` | Caller's rate limits and current daily/monthly usage |
| `explain_api_error` | Human-readable explanation for any of the 40 stable error codes |

## Configuration

| Env var | Default | What it does |
|---------|---------|--------------|
| `CSD_API_KEY` | _(required)_ | API key from your CardShowData dashboard |
| `CSD_BASE_URL` | `https://api.cardshowdata.com` | Override for staging or self-hosted |

## Notes

- **All prices are integer cents** (`market_price_cents`, `recommended_list_price_cents`, etc.). Cardmarket entries are EUR; everything else is USD — distinguished by the `currency` field.
- **Pricing is per-variant.** A Base Set Charizard's 1st-edition holofoil and unlimited holofoil have very different fair values; always inspect every entry in `variants[]`.
- **Errors use a stable envelope** (`{error: {type, code, message, status, request_id, doc_url, details}}`). Pass `error.code` to `explain_api_error` for handling guidance.

## Develop locally

```bash
git clone https://github.com/cardshowdata/cardshowdata
cd cardshowdata/packages/mcp
uv sync
uv run pytest
```

## License

MIT
