Pokemon MCP Server

A Model Context Protocol (MCP) server that provides Pokemon data through standardized tools. This monorepo contains both the MCP server and data ingestion service for fetching Pokemon data from PokeAPI.

Architecture

This is a PNPM monorepo with two main packages:

• pokemon-mcp-server: MCP server that exposes Pokemon data through standardized tools
• pokemon-mcp-ingestion: Data ingestion service that fetches from PokeAPI and stores in SQLite

The system uses a shared SQLite database (data/pokemon.sqlite) for Pokemon data storage.

Features

MCP Tools Available

• get_pokemon - Get detailed information about a specific Pokemon
• search_pokemon - Search Pokemon by name, type, or other criteria
• get_strongest_pokemon - Find the strongest Pokemon by various stats
• get_pokemon_stats - Get detailed stats for a Pokemon
• compare_pokemon - Compare stats between two Pokemon
• get_type_effectiveness - Get type effectiveness information

Data Coverage

• Complete Pokemon data from PokeAPI
• Stats, types, abilities, and more
• Type effectiveness relationships
• Searchable by multiple criteria

Quick Start

Prerequisites

• Node.js 18+
• PNPM
• Git

Installation

1. Clone the repository:

git clone https://github.com/grovesjosephn/pokemcp.git
cd pokemcp

2. Install dependencies:

pnpm install

3. Set up the database:

./scripts/setup.sh

4. Build all packages:

pnpm build

Usage

Running the MCP Server

# Development mode (with hot reload)
pnpm dev

# Production mode
cd packages/pokemon-mcp-server
pnpm start

Testing with MCP Inspector

# Visual GUI testing
cd packages/pokemon-mcp-server
pnpm inspect

# CLI testing
pnpm inspect:cli

Data Ingestion

# Run data ingestion
cd packages/pokemon-mcp-ingestion
pnpm start

Claude Desktop Integration

Option 1: NPM Package (Recommended)

Install the server globally:

cd packages/pokemon-mcp-server
pnpm build
npm link

Configure Claude Desktop:

{
  "mcpServers": {
    "pokemon": {
      "command": "pokemon-mcp-server",
      "env": {
        "POKEMON_DATA_DIR": "/path/to/pokemcp/data"
      }
    }
  }
}

Option 2: Direct Node Execution

{
  "mcpServers": {
    "pokemon": {
      "command": "node",
      "args": ["/path/to/pokemcp/packages/pokemon-mcp-server/dist/server.js"],
      "env": {
        "POKEMON_DATA_DIR": "/path/to/pokemcp/data"
      }
    }
  }
}

Option 3: Development Mode

{
  "mcpServers": {
    "pokemon": {
      "command": "pnpm",
      "args": ["--filter", "pokemon-mcp-server", "start"],
      "cwd": "/path/to/pokemcp",
      "env": {
        "POKEMON_DATA_DIR": "/path/to/pokemcp/data"
      }
    }
  }
}

Development

Workspace Commands

pnpm build         # Build all packages
pnpm dev           # Run all packages in development mode
pnpm test          # Run tests for all packages
pnpm lint          # Lint all packages
pnpm format        # Format all files
pnpm format:check  # Check formatting

Server Package Commands

cd packages/pokemon-mcp-server

pnpm build         # Compile TypeScript
pnpm dev           # Watch mode with tsx
pnpm start         # Run server
pnpm inspect       # Run MCP Inspector GUI
pnpm inspect:cli   # Run MCP Inspector CLI
pnpm test          # Run tests

Ingestion Package Commands

cd packages/pokemon-mcp-ingestion

pnpm build         # Compile TypeScript
pnpm dev           # Watch mode
pnpm start         # Run ingestion
pnpm test          # Run tests

Testing

The project uses Vitest for testing:

# Run all tests
pnpm test

# Run specific package tests
pnpm --filter pokemon-mcp-server test
pnpm --filter pokemon-mcp-ingestion test

Database Schema

The SQLite database includes tables for:

• pokemon - Basic Pokemon information
• stats - Pokemon stats (HP, Attack, Defense, etc.)
• types - Pokemon types and relationships
• abilities - Pokemon abilities
• type_effectiveness - Type effectiveness relationships

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run pnpm format and pnpm lint
6. Submit a pull request

Commit Guidelines

Use conventional commit format:

<type>[optional scope]: <description>

Examples:
- feat(server): add Pokemon evolution chain tool
- fix(ingestion): handle missing species URL gracefully
- docs: update integration guide

License

MIT License - see LICENSE file for details

Links

• Model Context Protocol
• PokeAPI
• Claude Desktop