README - pokemcp by grovesjosephn

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

Clone the repository:

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

Install dependencies:

pnpm install

Set up the database:

./scripts/setup.sh

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

Fork the repository
Create a feature branch
Make your changes
Add tests
Run pnpm format and pnpm lint
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