Skip to main content
Glama

dexMCP

lint test

dexMCP is a Model Context Protocol (MCP) server that wraps the community maintained pypokedex client for the PokeAPI. It exposes curated tools so MCP compatible applications can fetch Pokedex data without custom API plumbing.

Key capabilities

  • Query any Pokemon by name or national number and receive metric aware base stats.

  • Pull localized flavor text so agents can present in universe descriptions for each game version.

  • Inspect move learnsets for a chosen game so automation chains pick the right actions.

  • Map evolution chains, encounter locations, and breeding requirements without bespoke glue code.

  • Run roster analysis with coverage reports and simple moveset tips for battle planning.

Related MCP server: PokeAPI MCP Server

Available tools

  • get_pokemon

    • Required: name_or_dex

    • Optional: none

    • Returns: PokemonSummary with stats, types, height, weight, and base experience.

  • get_moves

    • Required: name_or_dex, game

    • Optional: none

    • Returns: list of Move entries with learn method and optional level.

  • get_sprites

    • Required: name_or_dex

    • Optional: side (front or back), variant (default, shiny, female, female_shiny)

    • Returns: SpriteURL containing the resolved image link.

  • get_descriptions

    • Required: name_or_dex

    • Optional: language (defaults to en)

    • Returns: mapping of game version to flavor text strings.

  • analyze_type_coverage

    • Required: names_or_dexes list

    • Optional: none

    • Returns: TypeCoverageReport summarizing defensive matchups.

  • explore_abilities

    • Required: name_or_dex

    • Optional: none

    • Returns: AbilityExplorerResult with effect text and hidden ability flag.

  • plan_evolutions

    • Required: name_or_dex

    • Optional: none

    • Returns: EvolutionReport that enumerates triggers and branching paths.

  • find_encounters

    • Required: name_or_dex

    • Optional: none

    • Returns: EncounterReport grouped by location and game version.

  • get_breeding_info

    • Required: name_or_dex

    • Optional: game to scope egg moves

    • Returns: BreedingInfo with egg groups, hatch steps, gender split, and egg moves.

  • suggest_moveset

    • Required: name_or_dex, game

    • Optional: limit (default 4), include_tm (default false)

    • Returns: MovesetRecommendation ordered by heuristic score.

Getting started

Prerequisites

  • Python 3.10 or newer.

  • uv for dependency management and running scripts.

  • An MCP aware client (or the Python mcp package) that can launch stdio servers.

  • Internet access so pypokedex can query PokeAPI the first time a Pokemon is requested.

Clone and install dependencies

git clone https://github.com/RajeevAtla/dexMCP.git
cd dexMCP
uv venv
uv sync

The runtime requirements are mcp (for FastMCP), pypokedex, requests, dspy-ai, langchain, langchain-openai, gradio, and the transitive pydantic dependency.

Run the MCP server

uv run python -m dexmcp.server

The server speaks MCP over stdio. Configure an MCP client to launch the command above and it will auto discover the tools listed earlier.

Example: run the DSPy demo agent

The repository ships dspy_client.py, a minimal DSPy client that connects to this server and calls the appropriate tools to satisfy natural language requests. Activate your virtual environment and run the curated demo suite:

uv run python dspy_client.py --demo

The agent chains several tools to:

  • Retrieve Garchomp stats and ORAS level up moves.

  • Audit defensive coverage for Pikachu, Garchomp, and Gyarados.

  • Surface Gengar abilities and Eevee evolution branches.

  • List Dratini encounter methods in FireRed and LeafGreen.

  • Summarize Sylveon breeding info and egg moves in Sword and Shield.

  • Recommend a Greninja moveset for Sun and Moon.

Provide your own prompt with:

uv run python dspy_client.py \
  "Compare Charizard and Tyranitar defensive coverage in scarlet-violet."

Add --demo alongside the prompt to run the canned sequence afterward.

Example: run the LangChain demo agent

Ensure OPENAI_API_KEY (or another provider key supported by your LangChain LLM) is present in the environment. Then launch the demo:

uv run python langchain_client.py --demo

The LangChain agent mirrors the DSPy scenarios, exercising the coverage, ability, evolution, encounter, breeding, and moveset tools.

Supply a custom prompt with:

uv run python langchain_client.py \
  "Plan a battle ready moveset for gardevoir in scarlet-violet."

Use --demo with a prompt to run it first before the guided walkthrough.

Example: run the Gradio demo

The Gradio UI wraps the LangChain agent and calls DexMCP tools over stdio. Ensure OPENAI_API_KEY (or another provider key supported by your LangChain LLM) is set.

uv run python gradio_demo.py

Optionally select a different model or share a public link:

uv run python gradio_demo.py --model gpt-4o-mini --share

Gradio hot reload

Use Gradio's reload mode to auto-restart on changes. On Windows, set GRADIO_SERVER_NAME and GRADIO_SERVER_PORT for the host/port:

set PYTHONPATH=C:\dexMCP
set GRADIO_SERVER_NAME=127.0.0.1
set GRADIO_SERVER_PORT=7860
uv run gradio gradio_demo.py

Testing

uv sync --group dev
uv run pytest

Pytest configuration (including coverage flags) lives in pyproject.toml.

Project structure

.
|-- dexmcp/
|   |-- abilities.py       # Ability lookup helper
|   |-- api.py             # PokeAPI + pypokedex helpers and caching
|   |-- breeding.py        # Egg group and breeding helpers
|   |-- coverage.py        # Type coverage analysis
|   |-- encounters.py      # Wild encounter lookups
|   |-- evolution.py       # Evolution chain traversal
|   |-- models.py          # Pydantic schemas
|   |-- moveset.py         # Moveset recommendation logic
|   |-- pokemon.py         # Core Pokemon lookup helpers
|   `-- server.py          # FastMCP server and tool wrappers
|-- assets/
|   `-- logo.png           # Logo used in the README banner
|-- dspy_client.py         # DSPy demo agent that consumes the server
|-- gradio_demo.py         # Gradio + LangChain demo UI
|-- langchain_client.py    # LangChain demo agent for the same tools
|-- LICENSE.md             # MIT License
|-- README.md

Data source and caching

pypokedex wraps PokeAPI and caches responses on disk under the user cache folder. The first lookup for a Pokemon may take a second while data is fetched; subsequent calls are served from the local cache.

License

DexMCP is distributed under the MIT License. See LICENSE.md for full terms.

Available Tools

10 tools
analyze_type_coverageA

Summarize defensive type coverage for a roster.

Args: names_or_dexes: Pokemon names or dex numbers to analyze.

Returns: Coverage report with matchup counts and notable weaknesses.

Inputs: names_or_dexes (required). Returns: Summary of defensive coverage for a roster.

explore_abilitiesA

Retrieve ability details for a Pokemon.

Args: name_or_dex: Pokemon name or national dex number.

Returns: Ability names and effect text details.

Inputs: name_or_dex (required). Returns: Ability listing for a Pokemon.

find_encountersA

Find wild encounter locations for a Pokemon.

Args: name_or_dex: Pokemon name or national dex number.

Returns: Encounter locations grouped by version and method.

Inputs: name_or_dex (required). Returns: Encounter locations grouped by area and version.

get_breeding_infoA

Summarize breeding details for a Pokemon.

Args: name_or_dex: Pokemon name or national dex number. game: Optional game identifier for egg move filtering.

Returns: Breeding info including egg groups, hatch steps, and egg moves.

Inputs: name_or_dex (required), game. Returns: Breeding metadata including egg groups and egg moves.

get_descriptionsA

Fetch localized Pokedex flavor text.

Args: name_or_dex: Pokemon name or national dex number. language: Language code for flavor text.

Returns: Mapping of game version to flavor text.

Inputs: name_or_dex (required), language. Returns: object

get_movesA

List the learnset for a Pokemon in a specific game.

Args: name_or_dex: Pokemon name or national dex number. game: PokeAPI game identifier (e.g., "scarlet-violet").

Returns: Moves the Pokemon can learn in the requested game.

Inputs: game (required), name_or_dex (required). Returns: result

get_pokemonA

Fetch a Pokemon summary for the given identifier.

Args: name_or_dex: Pokemon name or national dex number.

Returns: Summary stats, typing, and measurements for the Pokemon.

Inputs: name_or_dex (required). Returns: High-level Pokemon summary used by tool responses.

get_spritesA

Resolve a sprite URL for a Pokemon.

Args: name_or_dex: Pokemon name or national dex number. side: Sprite side ("front" or "back"). variant: Sprite variant (e.g., "default", "shiny").

Returns: Sprite URL with the requested side and variant.

Inputs: name_or_dex (required), side, variant. Returns: Sprite URL metadata for a Pokemon.

plan_evolutionsA

Enumerate evolution paths that include the Pokemon.

Args: name_or_dex: Pokemon name or national dex number.

Returns: Evolution paths and triggers.

Inputs: name_or_dex (required). Returns: Collection of evolution paths for a Pokemon.

suggest_movesetA

Recommend a moveset for a Pokemon in a game.

Args: name_or_dex: Pokemon name or national dex number. game: PokeAPI game identifier to scope learnsets. limit: Maximum number of recommendations to return. include_tm: Whether to include TM moves.

Returns: Ranked move recommendations based on simple heuristics.

Inputs: game (required), name_or_dex (required), limit, include_tm. Returns: Ranked moveset recommendations for a Pokemon.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 10 tools

    Disambiguation4/5

    Tools largely target distinct aspects of Pokemon data. The only potential confusion is between get_moves (full learnset) and suggest_moveset (recommendations), but descriptions clearly differentiate them.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case, using varied verbs (get, find, analyze, etc.) that reflect their actions.

    Tool Count5/5

    10 tools is well-scoped for a Pokedex server, covering key data domains without unnecessary redundancy.

    Completeness4/5

    Covers most common Pokemon queries including stats, moves, abilities, evolutions, breeding, encounters, sprites, and type coverage. Minor gaps like a search tool or more detailed stat breakdowns, but core workflows are well covered.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that provides Pokémon information by connecting to the PokeAPI, enabling users to query detailed Pokémon data, discover random Pokémon, and find Pokémon by region or type.
      4
      16
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that interfaces with PokeAPI to provide Pokémon information to LLM applications through JSON-RPC over stdio.
      ISC
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP (Multi-Agent Conversation Protocol) Server that provides an interface to access Pokémon data through the PokéAPI, enabling agents to retrieve information about Pokémon species, abilities, moves, and more via natural language.
      -