Pokédex MCP Server

A local Model Context Protocol server that exposes a public, read-only Gen I Pokédex knowledge base (National Pokédex #001–#025) to Claude Desktop.

It fetches plain Markdown directly from the public GitHub repository alexverdin/llm-pokedex-demo over raw.githubusercontent.com — no authentication, no tokens, no git clone, no database. Downloaded files are held in an in-memory cache (default TTL: 10 minutes) so repeated queries don't re-download.

What it does

Tools (7):

Tool	Description
list_pokedex_entries	All 25 entries [{ id, name, types, file }]. Optional type filter (case-insensitive substring).
search_by_name	Entries whose name contains query (case-insensitive).
get_pokemon	Get one entry by id ("025") or name ("pikachu"). format: "parsed" (default), "markdown", "both".
get_base_stats	{ hp, attack, defense, spAtk, spDef, speed, total } as numbers.
compare_pokemon	Compare 2–6 ids; returns a Markdown table of types + all base stats.
rank_by_stat	Rank all 25 by stat (hp|attack|defense|spAtk|spDef|speed|total), order (asc|desc, default desc), limit (default 5).
get_evolution_chain	Evolution section text for an id/name + related entries resolved by scanning other files.

Resources (2):

• pokedex://index — raw INDEX.md.
• pokedex://pokemon/{id} — raw entry Markdown for a 3-digit id.

Requirements

• Node.js ≥ 20 (node --version).
• An MCP client — Claude Desktop and/or OpenCode.

Installation

git clone https://github.com/alexverdin/mcp-pokedex-demo.git
cd mcp-pokedex-demo
npm install
npm run build

Verify it starts (Ctrl+C to stop — it waits for a client on stdio):

npm start
# stderr: pokedex-mcp running on stdio (repo: alexverdin/llm-pokedex-demo@main)

Claude Desktop config

Add the server to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Use an absolute path to the built entry point (dist/index.js):

{
  "mcpServers": {
    "pokedex": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp-pokedex-demo/dist/index.js"]
    }
  }
}

Windows example (note the doubled backslashes):

{
  "mcpServers": {
    "pokedex": {
      "command": "node",
      "args": ["C:\\Users\\you\\mcp-pokedex-demo\\dist\\index.js"]
    }
  }
}

Restart Claude Desktop (fully quit and reopen) after editing the config. The server and its tools appear once Claude Desktop relaunches.

Optional flags

Point the server at a fork or tune the cache by adding flags to args:

"args": [
  "/ABSOLUTE/PATH/TO/dist/index.js",
  "--repo", "your-user/your-fork",
  "--branch", "main",
  "--ttl", "600000"
]

• --repo accepts owner/repo or a full github.com URL. Default: alexverdin/llm-pokedex-demo.
• --branch default: main.
• --ttl cache lifetime in ms. Default: 600000 (10 min).

OpenCode config

OpenCode reads MCP servers from an opencode.json file. Add the server under the mcp block as a local (stdio) server, pointing command at the built entry point (dist/index.js).

Config file locations (project config overrides global):

• Global: %USERPROFILE%\.config\opencode\opencode.json
• Project: opencode.json in the repo root

Use an absolute path with doubled backslashes on Windows:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pokedex": {
      "type": "local",
      "command": ["node", "C:\\ABSOLUTE\\PATH\\TO\\mcp-pokedex\\dist\\index.js"],
      "enabled": true
    }
  }
}

macOS / Linux example:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pokedex": {
      "type": "local",
      "command": ["node", "/ABSOLUTE/PATH/TO/mcp-pokedex/dist/index.js"],
      "enabled": true
    }
  }
}

Restart the OpenCode session after editing. The server's tools then appear in the agent's tool list.

Optional flags (same as above) go in the command array after the script path:

"command": [
  "node",
  "C:\\ABSOLUTE\\PATH\\TO\\mcp-pokedex\\dist\\index.js",
  "--repo", "your-user/your-fork",
  "--branch", "main",
  "--ttl", "600000"
]

Example prompts

• "List all Pokédex entries that are Fire type."
• "Get the base stats for Pikachu."
• "Compare Bulbasaur, Charmander, and Squirtle."
• "What are the three fastest Pokémon in the Pokédex?"
• "Show me the evolution chain for Charmander."
• "Search for Pokémon whose name contains 'saur'."

Troubleshooting

• Server not showing up: confirm the path in args is absolute and points at dist/index.js (not src/), and that you ran npm run build. Fully restart Claude Desktop.
• node: command not found: Claude Desktop must find node on PATH. Use an absolute path to the node binary in command if needed (e.g. /usr/local/bin/node or the output of which node / where node).
• Wrong Node version: requires Node ≥ 20 (node --version). ESM + global fetch depend on it.
• Logs:
  • macOS: ~/Library/Logs/Claude/mcp*.log
  • Windows: %APPDATA%\Claude\logs\mcp*.log
  • The server writes its own diagnostics to stderr (stdout is reserved for the MCP protocol).
• Network: the only outbound host is raw.githubusercontent.com. A 404 for an entry usually means an out-of-range id (valid ids are 001–025).

Development

npm run dev     # tsx watch mode (rebuild-free)
npm run build   # compile to dist/
npm start       # run compiled server

Testing with MCP Inspector

MCP Inspector lets you call tools and read resources directly, no Claude Desktop / OpenCode needed.

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Terminal prints a URL with an auth token, e.g.:

http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>

Open it in browser. Transport preset to stdio, command node dist/index.js. Click Connect, then:

• Tools tab — pick a tool (e.g. get_pokemon), fill args (id: "025"), Run.
• Resources tab — read pokedex://index or pokedex://pokemon/001.

To test against a fork or non-default flags, append them after the script path:

npx @modelcontextprotocol/inspector node dist/index.js --repo your-user/your-fork --ttl 600000

Ctrl+C in the terminal stops both Inspector and the server.

License

MIT — see LICENSE.