Pokemcp

🚀 Pokemon MCP Server

A Model Context Protocol (MCP) server that offers Pokemon data via standardized tools. This monorepo includes both the MCP server and a data ingestion service for retrieving Pokemon data from PokeAPI.

🚀 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

✨ Features

MCP Tools Available

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

Data Coverage

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

🏗️ Architecture

This is a PNPM monorepo with two main packages:

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

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

📚 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