# PokémonGPT MCP

Live Pokémon TCG card data and TCGplayer market prices for AI assistants. Connect the MCP server to Claude, ChatGPT, Cursor or VS Code and ask about any card, set or price in plain language, in any language.

> "What's the most valuable card in Evolving Skies?"
> "How much is my Base Set Charizard 4/102?"
> "喷火龙最贵的卡是哪张？"
> "Cheap Fire ex cards under $5 for my deck"
> "Prismatic Evolutions Elite Trainer Box price"
> "日版喷火龙多少钱？"

It started as PokémonGPT, a custom GPT in the GPT Store. With custom GPTs retiring, it continues under the same name as an open MCP server, a portable skill, and a ChatGPT plugin built from both.

## Connect

**Hosted server:** `https://pokemongpt-455505.uc.r.appspot.com/mcp`
(Streamable HTTP, no sign-in, read-only. A free, best-effort service: please be gentle with it, or [host your own](#self-hosting).)

| Client | How |
|---|---|
| **Claude** (web / desktop) | Settings → Connectors → Add custom connector → paste the URL |
| **Claude Code** | `claude mcp add --transport http pokemongpt https://pokemongpt-455505.uc.r.appspot.com/mcp` |
| **ChatGPT** | Add the URL as an app in a plugin (`@Plugin Creator`), or as a custom connector where your plan offers developer mode |
| **Cursor** | `~/.cursor/mcp.json`: `{"mcpServers": {"pokemongpt": {"url": "https://pokemongpt-455505.uc.r.appspot.com/mcp"}}}` |
| **VS Code** | `.vscode/mcp.json`: `{"servers": {"pokemongpt": {"type": "http", "url": "https://pokemongpt-455505.uc.r.appspot.com/mcp"}}}` |
| Other MCP clients | Any client that supports remote Streamable HTTP servers |

### Add the skill (recommended)

The MCP server provides the data. The [`skills/pokemongpt`](skills/pokemongpt/SKILL.md) skill teaches the assistant how to use it well: translate names to English before searching, pick the right tool, report every printing's price separately, and add the right disclaimers. It also carries the original PokemonGPT persona for general Pokémon questions (games, Pokédex, competitive play).

- **Claude Code:** copy `skills/pokemongpt` to `~/.claude/skills/`
- **Claude (web / desktop):** zip the folder (`cd skills && zip -r pokemongpt.zip pokemongpt`) and upload it in Claude's skills settings
- **ChatGPT:** add it to the same plugin as the MCP app

Without an MCP connection, the skill falls back to `scripts/tcg_api.py`, a standard-library client for the same API.

## Tools

| Tool | Use it for |
|---|---|
| `search_cards` | English cards by name, set, number, rarity, type, stage, tag (`ex`, `VMAX`, ...), attack/ability text, illustrator, regulation mark, HP or price. Returns card details plus the price of every printing |
| `search_prices` | Raw TCGplayer listings: sets too new to have card details yet, **Japanese** cards (`language="jp"`), and **sealed product** (`singles_only=false`) |
| `list_sets` | English sets, newest first, and which are only covered by `search_prices` |
| `list_filter_values` | The exact values filters accept (rarities, stages, tags, ...) |

Every tool is read-only. The same searches are available as a plain HTTP API: see `/docs` on the server.

## Data

| | Source | Coverage |
|---|---|---|
| Card details | [PTCG-database](https://github.com/type-null/PTCG-database) (MIT), built from [pkmncards.com](https://pkmncards.com) | About 21,000 English cards across almost every set |
| Prices | TCGplayer, via [tcgcsv.com](https://tcgcsv.com) | About 47,000 English and 33,000 Japanese listings, singles and sealed |

- Prices are **TCGplayer market prices in USD for ungraded (raw) cards**, not PSA/BGS/CGC graded values. Every response includes `prices_as_of`; prices are refreshed periodically, not live.
- About 96% of cards are matched to a TCGplayer listing. The rest are mostly trainer kits and TCG Classic decks, which TCGplayer lists differently.
- A set released in the last few weeks may only be in `search_prices` until the card database catches up.

## Self-hosting

You need Python 3.12 and a MongoDB database (a free [MongoDB Atlas](https://www.mongodb.com/atlas) cluster is plenty: the data is about 60 MB).

```bash
git clone --recurse-submodules https://github.com/danielqingz/pokemongpt-mcp.git
cd pokemongpt-mcp
python3.12 -m venv .venv && .venv/bin/pip install -r requirements.txt
cp .env.example .env                           # then set MONGO_URL

.venv/bin/python scripts/fetch_prices.py --lang en   # TCGplayer prices, ~10+ minutes
.venv/bin/python scripts/fetch_prices.py --lang jp
.venv/bin/python scripts/load_data.py                # cards + prices into MongoDB, ~2 minutes

.venv/bin/uvicorn server.main:app --port 8000        # MCP at http://localhost:8000/mcp, API docs at /docs
```

To update later: `git submodule update --remote data` for new cards, then `scripts/load_data.py --refresh-prices`.

**Deploying:** `app.yaml` is ready for Google App Engine (`gcloud app deploy`; `.env` is uploaded with the app). It caps the server at 2 instances, because the endpoint is public and needs no sign-in. Elsewhere, run the same `uvicorn` command. If your database only accepts listed IP addresses, allow the host's.

**macOS note:** the python.org installer ships without root certificates. If downloads or Atlas connections fail with `CERTIFICATE_VERIFY_FAILED`, run `export SSL_CERT_FILE=$(.venv/bin/python -m certifi)` first.

**ChatGPT plugin:** `python scripts/build_plugin.py` packages `plugin/` and `skills/` into `dist/pokemongpt-<version>.zip` after checking the listing limits from OpenAI's submission docs. Point `plugin/mcp.json` and the URLs in `plugin/plugin.json` at your own server first.

### Layout

```
server/main.py         FastAPI app: HTTP API (/tcg/...) and the MCP endpoint (/mcp)
server/mcp_server.py   MCP tools
server/service.py      query logic shared by both (typed filters only, no raw database queries)
server/models.py       parameter and response models
scripts/               fetch_prices.py (TCGplayer via tcgcsv), load_data.py (MongoDB loader), build_plugin.py
skills/pokemongpt/     the skill: SKILL.md, reference.md, scripts/tcg_api.py
plugin/                ChatGPT plugin manifest, MCP config, logo; REVIEW.md has the submission materials
data/                  card database (git submodule)
```

## Privacy

The hosted server has no accounts and stores no searches. Like any web server, its host (Google Cloud) keeps standard request logs (IP address, time, requested URL) for a limited period. Your AI assistant's own privacy policy covers your conversations.

## Disclaimer

PokemonGPT is an unofficial fan project. It is not affiliated with, endorsed by or sponsored by Nintendo, The Pokémon Company, Creatures, GAME FREAK or TCGplayer. Pokémon and all related names are trademarks of their respective owners. Card text and images belong to their copyright holders. Prices are informational only and change constantly: check several sources before buying or selling.

## License

[MIT](LICENSE) for the code in this repository. Card data and images keep their own licenses and terms.

---

## 中文说明

PokemonGPT 原本是 GPT Store 上的宝可梦助手。自定义 GPT 下线后，它的卡牌和价格查询功能以开源 MCP 服务器加技能（skill）的形式继续提供。

- **直接使用：** 把 `https://pokemongpt-455505.uc.r.appspot.com/mcp` 添加到 Claude、ChatGPT、Cursor 等支持 MCP 的工具里（方法见上方 [Connect](#connect)），再安装 `skills/pokemongpt` 技能效果更好。
- **可以用中文提问**，比如"喷火龙最贵的卡是哪张？""日版喷火龙多少钱？"。助手会先翻译成英文卡名再查询。
- **价格说明：** 来自 TCGplayer 的美元市场价，指未评级的散卡（不是 PSA 等评级卡），每次结果都会注明价格日期。
- **自己部署：** 见上方 [Self-hosting](#self-hosting)。
- 本项目为非官方粉丝作品，与任天堂、宝可梦公司及 TCGplayer 无关。