Pokemon Pocket MCP Server

MCP server that enables AI agents (like Claude Code) to query and analyze Pokemon Pocket TCG cards using DuckDB for high-performance SQL queries.

Features

🔧 Tools (7 total)

1. search_cards - Search with flexible filters (name, type, HP, set, retreat cost, etc.)
   • Supports uniqueOnly parameter to filter out duplicate art variants
2. get_card - Get detailed info for a specific card
3. find_synergies - Find cards that work well together (same type + trainers)
   • Automatically filters out duplicates
4. find_counters - Find cards that counter a specific type (exploit weakness)
   • Automatically filters out duplicates
5. get_type_stats - Get statistics by type (count, avg HP, avg retreat cost)
6. query_cards - Run custom SQL queries against the card database
7. analyze_deck - Analyze deck composition (energy needs, type distribution)

📚 Resources (3 total)

1. pokemon://cards/all - Full card database (2,077 cards)
2. pokemon://cards/unique - Unique cards only (excludes art variants)
3. pokemon://stats/types - Type statistics and breakdowns

💡 Prompts (3 total)

1. build-deck - Build a deck around a specific card
2. counter-deck - Build a deck to counter a type/strategy
3. optimize-deck - Analyze and improve an existing deck

🖥️ CLI Mode

The package also includes a full-featured CLI for direct terminal access to the card database.

Installation

# Install globally
npm install -g pokemon-pocket-mcp-server

# Or use via npx without installation
npx pokemon-pocket-mcp-server --help

Available Commands

| Command | Description | | ----------- | ------------------------- | | search | Search cards with filters | | get | Get specific card by name | | synergies | Find synergies for a card | | counters | Find counters for a type | | stats | Show type statistics | | query | Run custom SQL query | | trainers | List all trainer cards | | analyze | Analyze deck composition |

CLI Usage Examples

# Search for Pikachu cards with table output
pokemon-pocket-mcp search --name Pikachu --output table

# Get specific card details
pokemon-pocket-mcp get --name "Charizard ex"

# Find synergies for a card
pokemon-pocket-mcp synergies --card-name "Blastoise ex"

# Show type statistics
pokemon-pocket-mcp stats --output table

# List trainer cards
pokemon-pocket-mcp trainers --limit 20

# Custom SQL query
pokemon-pocket-mcp query --sql "SELECT name, hp FROM cards WHERE hp > 150 LIMIT 10"

# Analyze a deck
pokemon-pocket-mcp analyze --card-names Pikachu,"Pikachu ex","Rare Candy"

Output Formats

All commands support three output formats via --output (or -o):

• json - Structured JSON output (default)
• table - Human-readable table format
• compact - Single-line per card format

pokemon-pocket-mcp stats --output table
pokemon-pocket-mcp search --type Fire --output compact

Getting Help

# Show all commands
pokemon-pocket-mcp --help

# Show command-specific help
pokemon-pocket-mcp search --help

Duplicate Filtering

The card database contains 2,077 total cards, but many are duplicates with different art:

• 1,890 cards with attacks (total)
• 1,068 unique cards with attacks
• 822 duplicate cards (43.5% duplicates)

What Makes a Card Unique?

Cards are considered unique based on: name, type, hp, attacks, weakness, retreat_cost

Example:

• Pikachu ex (Circle Circuit) appears 7 times across sets A1, A4b (different art, same stats) = 1 unique card
• Pikachu has 7 different versions with different attacks (Gnaw, Spark, Circle Circuit, etc.) = 7 unique cards

How to Use

search_cards (defaults to unique cards):

// Returns 7 unique Pikachu cards (default behavior)
search_cards({ name: 'Pikachu' });

// Returns all 21 Pikachu cards (including art variants)
search_cards({ name: 'Pikachu', uniqueOnly: false });

All tools filter duplicates by default:

• search_cards - Returns unique cards by default (set uniqueOnly: false to see all variants)
• find_synergies - Always returns unique cards
• find_counters - Always returns unique cards
• Resource pokemon://cards/unique - Only unique cards

See DUPLICATE_FILTERING.md for detailed documentation.

🚀 Quick Start (Recommended)

The easiest way to use this server is via the published npm package:

Setup with Claude Desktop

Add this to your Claude Desktop config:

• macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (recommended - works with any Node installation):

{
  "mcpServers": {
    "pokemon-pocket": {
      "command": "npx",
      "args": ["pokemon-pocket-mcp-server"]
    }
  }
}

Using bunx (faster, requires bun):

{
  "mcpServers": {
    "pokemon-pocket": {
      "command": "bunx",
      "args": ["pokemon-pocket-mcp-server"]
    }
  }
}

Restart Claude Desktop after adding the configuration.

Note: No installation or building needed! The package is fetched automatically and stays up-to-date.

🛠️ Development Setup

For contributors who want to modify the server:

cd mcp-server
npm install
npm run build

Then update your Claude Desktop config to point to your local build:

{
  "mcpServers": {
    "pokemon-pocket": {
      "command": "node",
      "args": ["/absolute/path/to/pokeclaude/mcp-server/dist/index.js"]
    }
  }
}

Usage Examples

Example 1: Search for Lightning Pokemon

User: Find all Lightning type Pokemon with at least 100 HP
Claude: [Uses search_cards tool]
{
  "type": "Lightning",
  "minHp": 100
}

Example 2: Build a Pikachu ex Deck

User: Build me a competitive deck around Pikachu ex
Claude: [Uses build-deck prompt]
- Finds Pikachu ex stats
- Uses find_synergies to get Lightning Pokemon
- Suggests Zapdos ex, Electrode, Magneton
- Recommends 15-18 energy cards
- Explains combo: Circle Circuit scales with bench

Example 3: Counter Mewtwo ex Decks

User: What beats Mewtwo ex?
Claude: [Uses find_counters tool]
{
  "targetType": "Psychic"
}
→ Returns Darkness and Metal types (Mewtwo's weakness)
→ Suggests Weavile ex, Melmetal, Gengar

Example 4: Analyze Existing Deck

User: Analyze this deck: Charizard ex, Moltres ex, Arcanine ex, Professor Oak
Claude: [Uses analyze_deck tool]
{
  "cardNames": ["Charizard ex", "Moltres ex", "Arcanine ex", "Professor Oak"]
}
→ Type distribution: 100% Fire
→ Energy needs: Heavy Fire requirement
→ Suggests adding evolution basics (Charmander, Growlithe)

Example 5: Custom SQL Query

User: Show me all Pokemon with 0 retreat cost and at least 100 HP
Claude: [Uses query_cards tool]
SELECT name, type, hp, attacks
FROM cards
WHERE retreat_cost = '0'
  AND CAST(hp AS INTEGER) >= 100
  AND attacks != ''
ORDER BY CAST(hp AS INTEGER) DESC

Advanced Usage

Find Synergies

// Finds cards that work well with Charizard ex
{
  "cardName": "Charizard ex"
}
// Returns:
// - Other Fire types (Moltres ex, Arcanine ex)
// - Trainer cards
// - Cards with complementary energy costs

Type Statistics

// Get breakdown of all types
{
} // No parameters needed
// Returns:
// {
//   "type": "Fire",
//   "count": 150,
//   "avg_hp": 95.5,
//   "avg_retreat_cost": 1.8
// }

Data Quality

• ✅ 2,077 total cards from 12 sets (A1-A4b, P-A)
• ✅ 100% verified via spot checks (47+ cards manually validated)
• ✅ Zero parsing errors on names, types, HP values
• ✅ Complete attack data including:
  • Normal damage attacks (e.g., "Slash: 60")
  • Effect-only attacks (e.g., "Stoke:")
  • Variable damage (e.g., "Hydro Pump 40+:")
  • Multipliers (e.g., "Circle Circuit: 30x")

Database Schema

CREATE TABLE cards (
  id VARCHAR,              -- UUID primary key
  set_code VARCHAR,        -- A1, A2, A3, etc.
  set_name VARCHAR,        -- "Genetic Apex", etc.
  card_number VARCHAR,     -- Card number in set
  name VARCHAR,            -- Card name
  type VARCHAR,            -- Fire, Water, Grass, etc. (empty for trainers)
  hp VARCHAR,              -- Hit points
  rarity VARCHAR,          -- Rarity level
  abilities VARCHAR,       -- Pokemon abilities
  attacks VARCHAR,         -- Attack details
  weakness VARCHAR,        -- Weakness type
  resistance VARCHAR,      -- Resistance type
  retreat_cost VARCHAR,    -- Retreat cost (0-4)
  image_url VARCHAR,       -- Card image URL
  card_url VARCHAR         -- limitlesstcg.com URL
);

Example Deck Building Workflow

1. Choose main attacker: get_card("Pikachu ex")
2. Find synergies: find_synergies("Pikachu ex") → Get Lightning Pokemon
3. Check counters: find_counters("Lightning") → See what beats you
4. Search support: search_cards({ type: "Lightning", maxHp: 80 }) → Find bench sitters
5. Analyze composition: analyze_deck([...cardNames]) → Check energy needs
6. Optimize: Use prompt "optimize-deck" for AI suggestions

SQL Query Examples

-- Highest HP Pokemon by type
SELECT type, name, hp
FROM cards
WHERE type != ''
GROUP BY type
ORDER BY CAST(hp AS INTEGER) DESC;

-- Cards with 0 retreat cost
SELECT name, type, hp, attacks
FROM cards
WHERE retreat_cost = '0' AND attacks != '';

-- Most common weaknesses
SELECT weakness, COUNT(*) as count
FROM cards
WHERE weakness != ''
GROUP BY weakness
ORDER BY count DESC;

-- Cards from latest set
SELECT name, type, hp
FROM cards
WHERE set_code = 'A4b'
ORDER BY CAST(card_number AS INTEGER);

Development

# Run in dev mode
npm run dev

# Type check
npm run typecheck

# Build
npm run build

# Run built version
npm start

Architecture

• MCP SDK: @modelcontextprotocol/sdk v1.0.4 for protocol implementation
• DuckDB: @duckdb/node-api v1.4.0 - High-performance in-memory SQL database with TypeScript support
• CSV Import: Loads pokemon_pocket_cards.csv on startup into memory
• Transport: stdio (standard input/output) for Claude Desktop integration
• Type Safety: Full TypeScript types for DuckDB operations
• BigInt Handling: Automatic JSON serialization via getRowObjectsJson()

Troubleshooting

Server not appearing in Claude Desktop

1. Check config file location: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Verify path to dist/index.js is absolute
3. Restart Claude Desktop completely
4. Check logs: ~/Library/Logs/Claude/

DuckDB errors

• Ensure CSV file exists at ../pokemon_pocket_cards.csv relative to dist/index.js
• Check CSV formatting (should be UTF-8 encoded)

Permission errors

chmod +x dist/index.js

Data Source

Cards scraped from limitlesstcg.com/pocket using the scraper in ../scraper.ts.

Quality reports:

• ../SPOT_CHECK_REPORT.md - Manual verification results
• ../COMPREHENSIVE_QA_REPORT.md - DuckDB analysis results

License

MIT