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):

Resources (2):

• pokedex://index — raw INDEX.md.

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

Related MCP server: Pokémon MCP Server

Requirements

• Node.js ≥ 20 (node --version).

• An MCP client — Claude Desktop and/or OpenCode.

Install (workshop attendees)

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.