Dusk Reborn RPG MCP server
by rdsdehal
README.md
<div align="center">
<img src="assets/banner.svg" alt="Dusk Reborn RPG MCP server" width="100%">
<br>
**Give your AI assistant live, structured access to a fan-made browser RPG: which forms exist, and what they sell for.**
[](https://registry.modelcontextprotocol.io/v0/servers?search=pkmnreborn)
[](https://github.com/rdsdehal/dusk-reborn-mcp/releases)
[](https://github.com/rdsdehal/dusk-reborn-mcp/actions/workflows/check.yml)



[](LICENSE)
[**Connect**](#-connect-in-30-seconds) ·
[**Tools**](#-tools) ·
[**See it work**](#-see-it-work) ·
[**How it works**](#-how-it-works) ·
[**Docs**](#-documentation) ·
[**Play the game**](https://pkmnreborn.com)
</div>
---
The **Dusk Reborn RPG MCP server** is a hosted, read-only [Model Context Protocol](https://modelcontextprotocol.io)
endpoint for [Pokemon Dusk Reborn](https://pkmnreborn.com), a free fan-made browser game with a player-run economy. An
assistant can ask "does a Frost Mega Lugia exist?" or "what did Shadow Shellder sell for this month?" and get
structured JSON back, instead of scraping web pages.
There is nothing to install and nothing to sign up for. It is one URL.
```
https://pkmnreborn.com/mcp
```
> [!NOTE]
> Unofficial fan project. Not affiliated with, endorsed by or connected to Nintendo, The Pokemon Company, Creatures,
> GAME FREAK or Niantic. This repository holds documentation and examples only: no game code, no game assets and no
> Pokemon artwork. Prices are in GC coins, the game's fictional currency, and are not financial advice.
## ⚡ Connect in 30 seconds
| Client | How |
|---|---|
| **Claude Code** | `claude mcp add --transport http dusk-reborn https://pkmnreborn.com/mcp` |
| **VS Code** | Add to `.vscode/mcp.json`: `{"servers": {"dusk-reborn": {"type": "http", "url": "https://pkmnreborn.com/mcp"}}}` |
| **Cursor, Windsurf, Claude Desktop, MCP Inspector** | [Copy-paste configs](docs/examples/README.md) |
| **Anything else** | Add the URL as a remote MCP server (Streamable HTTP, no authentication) |
Or skip the client and call it directly:
```bash
curl -s https://pkmnreborn.com/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_pokedex_variants","arguments":{"species":"Mew"}}}'
```
## 🧰 Tools
Seven tools, all annotated `readOnlyHint: true` and `destructiveHint: false`, all returning structured JSON.
**Pokedex: what exists in the game**
| Tool | Answers |
|---|---|
| `get_pokedex_variants` | Every registered form of a species, with color, form type and exact in-game name |
| `check_pokedex_forms` | Up to 25 exact form names in one call: is each one registered? |
**Stock Market: what forms sell for between players**
| Tool | Answers |
|---|---|
| `search_pokemon` | Find colored forms by name, with reference price, 30 day change and recent sales |
| `get_pokemon_price` | The full market record for one colored form |
| `get_price_history` | Recorded player-to-player sales, newest first, plus a daily reference price series |
| `get_market_trends` | Biggest risers, fallers and most traded forms over the last 30 days |
| `get_market_summary` | Market totals and the game's own plain-language explanation of how prices are made |
Arguments and result fields for each tool: **[docs/tools.md](docs/tools.md)**.
## 🎬 See it work
Real output from the live server (2026-11-15), trimmed for length.
**Prompt:** *"Which forms of Mew are registered, and how many?"*
```jsonc
// get_pokedex_variants { "species": "Mew" }
{
"species": "Mew",
"dex_number": 151,
"count": 11,
"variants": [
{ "name": "Mew", "color": "Normal", "form_type": "base" },
{ "name": "MegaMew", "color": "Normal", "form_type": "mega" },
{ "name": "ShinyMew", "color": "Shiny", "form_type": "base" }
// ...8 more
]
}
```
**Prompt:** *"What does a Shadow Shellder go for?"*
```jsonc
// get_pokemon_price { "name": "Shadow Shellder" }
{
"display_name": "Shadow Shellder",
"reference_price": { "amount": 1000, "currency": "GC", "basis": "level_5_copy" },
"recorded_sales": 16,
"copies_in_game": 133,
"color_bonus": { "amount": "15%", "stat": "Attack" },
"price_status": "priced"
}
```
More things to ask: *"Does a Frost Mega Lugia exist?"*, *"Which colored forms moved the most in the last 30
days?"*, *"Show the last five sales of Shadow Shellder."*
## 🏗️ How it works
```mermaid
flowchart LR
A["AI client<br/>Claude, VS Code, Cursor, ..."] -- "POST JSON-RPC<br/>Streamable HTTP" --> B["/mcp"]
subgraph Game ["Dusk Reborn RPG (hosted)"]
B --> C["Guard<br/>method, size, rate limit"]
C --> D["Seven read-only tools"]
D --> E[("Registered forms<br/>+ aggregated market data")]
end
F["Server Card<br/>AI Catalog<br/>llms.txt<br/>OpenAPI"] -. discovery .-> A
G["Official MCP Registry"] -. discovery .-> A
```
The server is part of the live game and shares its data with the public Pokedex and Stock Market pages, so every answer
matches what a player sees on the site.
### Design decisions
- **Read-only by construction.** No write tools exist. Results contain aggregates and public game records only: no
player accounts, inventories, trades or contact details, and sales carry no player names.
- **Stateless.** One JSON response per request, no sessions, no event stream. It scales like a plain HTTP endpoint and
needs no sticky routing. `GET` and `DELETE` answer `405`.
- **Four protocol revisions.** The stateless `2026-07-28` revision and the legacy `2025-03-26`, `2025-06-18` and
`2025-11-25` revisions all work, so older clients keep working.
- **Errors a model can use.** Bad input returns a normal result with `isError: true` and a message such as
`color must be one of Shadow, Haunted, ...; limit must be 1 to 25.`, not an opaque HTTP error.
- **Protected cheaply.** Method, size, content type and rate limits (about 60 a minute and 1,000 an hour per client)
are checked before the database is opened. Over the limit: `429` with `Retry-After`.
- **Honest about its data.** Reference prices are a weighted middle of completed sales, normalized to a level 5 copy,
rebuilt about hourly, with gifts and related-account trades discounted. See [docs/data-notes.md](docs/data-notes.md).
- **Discoverable.** Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=pkmnreborn)
under a domain-proved name, with a [Server Card](https://pkmnreborn.com/mcp/server-card), an
[AI Catalog](https://pkmnreborn.com/.well-known/ai-catalog.json), [`llms.txt`](https://pkmnreborn.com/llms.txt) and an
[OpenAPI file](https://pkmnreborn.com/api/v1/openapi.json).
## 🔌 Also a REST API
The same data is available over plain `GET`, no key. See [docs/api.md](docs/api.md) for routes, or the
[OpenAPI description](https://pkmnreborn.com/api/v1/openapi.json).
```bash
curl -s 'https://pkmnreborn.com/api/v1/market?q=shellder&color=Shadow&per_page=5'
```
## 📚 Documentation
| | |
|---|---|
| [Tool reference](docs/tools.md) | Arguments and result fields for all seven tools |
| [REST API](docs/api.md) | Routes, filters and examples |
| [Client examples](docs/examples/README.md) | Claude Code, VS Code, Cursor, Windsurf, Claude Desktop, Inspector, curl |
| [Data notes](docs/data-notes.md) | What the data is, and is not |
| [FAQ](docs/faq.md) | Limits, errors, protocol versions |
| [Developer guide](https://pkmnreborn.com/developers) | The same information as a web page |
| [Changelog](CHANGELOG.md) | What changed, and when |
## 🚦 Limits
About 60 requests a minute and 1,000 an hour per client address. If the game's Stock Market is switched off, `/mcp`
answers `404`.
## 🤝 Feedback, security and rights holders
- **Bugs and wrong data:** open an issue here, or use **#bugs-and-errors** on [Discord](https://discord.gg/FwWCv3S).
- **Security:** see [SECURITY.md](SECURITY.md). Please do not post details publicly.
- **Contributing:** documentation fixes and verified client configs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
- **Rights holders:** Pokemon and related names, characters and artwork are trademarks and copyrights of their
respective owners, including Nintendo, Creatures, GAME FREAK and The Pokemon Company. This project uses them as a fan
project and does not claim them. Questions or requests: <admin@pkmnreborn.com>.
## 🎮 About the game
Pokemon Dusk Reborn is a free-to-play browser RPG made by fans, for fans, and run as a not-for-profit hobby project.
[Play it](https://pkmnreborn.com), read [how to play](https://pkmnreborn.com/how-to-play.php), or join the
[Discord](https://discord.gg/FwWCv3S).
## License
The documentation and examples in this repository are released under the [MIT License](LICENSE). The game itself and
the MCP server's code are not part of this repository and are not covered by that license.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data