Pokemon Go MCP

Pokemon Go MCP Server

A comprehensive Model Context Protocol (MCP) server providing real-time Pokemon Go data including events, raids, research tasks, egg hatches, and Team Rocket lineups

______________________________________________________________________

Feature Overview

Category Features Key Capabilities

Events Current Events, Event Details, Community Days Real-time event tracking, spawn data, bonuses, exclusive moves

Raids Raid Bosses, Tier Filtering, Shiny Tracking Complete raid listings, type filtering, weather boost detection

Research Field Tasks, Reward Tracking, Task Filtering Task discovery, shiny rewards, easy completion paths

Eggs Egg Pools, Distance Filtering, Shiny Tracking Distance-based filtering, regional exclusives, Adventure Sync rewards

Team Rocket Lineups, Shadow Pokemon, Encounter Rewards Complete trainer lineups, type effectiveness, shiny shadows

Cross-Platform Universal Search, Daily Priorities, Status Multi-source search, curated recommendations, cache management

______________________________________________________________________

Quick Start

Step Command Description

1. Clone git clone <repository-url> Clone the repository

2. Navigate cd pokemon-go-mcp Enter project directory

3. Install (uv) uv sync Install with uv package manager (recommended)

3. Install (pip) pip install -e . Install with pip

4. Run uv run python server.py Start the MCP server

先决条件

• Python 3.10或更高版本
• uv 包管理器（推荐）或 pip

______________________________________________________________________

Integration Options

Platform Configuration Notes

Claude Desktop Add to claude_desktop_config.json Requires absolute path to server.py

Claude Code Use claude mcp add command Or create .mcp.json manually

VS Code Create .vscode/mcp.json Supports stdio and HTTP transports

n8n Workflows Install n8n-nodes-mcp HTTP transport recommended

Docker Use docker build and docker run Supports HTTP/SSE transports

Claude桌面配置

{
  "mcpServers": {
    "pokemon-go": {
      "command": "uv",
      "args": ["run", "python", "/path/to/pokemon-go-mcp/pogo_mcp/server.py"]
    }
  }
}

Claude代码配置

# Quick add with claude mcp command
claude mcp add pokemon-go uv run python /path/to/pokemon-go-mcp/pogo_mcp/server.py

# Or manually create .mcp.json in your project directory
echo '{"servers": {"pokemon-go": {"command": "uv", "args": ["run", "python", "/path/to/pokemon-go-mcp/pogo_mcp/server.py"]}}}' > .mcp.json

VS代码配置

创建 .vscode/mcp.json 在您的工作空间中：

{
  "servers": {
    "pokemon-go-stdio": {
      "command": "uv",
      "args": ["run", "python", "/path/to/pokemon-go-mcp/pogo_mcp/server.py"]
    },
    "pokemon-go-http": {
      "type": "http",
      "url": "http://localhost:8000",
      "description": "Pokemon Go MCP Server via HTTP"
    }
  }
}

n8n工作流

1. 安装n8n MCP节点：

   npm install n8n-nodes-mcp
   # Set environment: N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

1. 配置MCP客户端节点：

- 连接类型：HTTP流式传输（推荐） - 网址： http://localhost:8000 （跑步时 MCP_TRANSPORT=http) - Headers：如果需要，可以选择身份验证标头

1. n8n的Docker部署：

   # Build and run the Pokemon Go MCP server
   docker build -t pokemon-go-mcp .
   docker run -d -p 8000:8000 -e MCP_TRANSPORT=http pokemon-go-mcp

运输方式

Transport Command Use Case

HTTP MCP_TRANSPORT=http MCP_PORT=8000 python pogo_mcp/server.py Web integrations, automation tools

SSE MCP_TRANSPORT=sse MCP_PORT=8000 python pogo_mcp/server.py Legacy systems

stdio python pogo_mcp/server.py Default, Claude Desktop

______________________________________________________________________

Showcase

______________________________________________________________________

Available Tools

Tool Name Category Description

get_current_events Events List all active and upcoming events

get_event_details Events Detailed information about a specific event

get_community_day_info Events Community Day specifics and featured Pokemon

get_event_spawns Events Pokemon spawning more frequently during events

get_event_bonuses Events Active event bonuses (XP, Stardust, etc.)

search_events Events Search events by name or type

get_current_raids Raids All current raid bosses by tier

get_raid_by_tier Raids Filter raids by tier (1, 3, 5, Mega)

get_shiny_raids Raids Only shiny-eligible raid bosses

search_raid_boss Raids Find specific Pokemon in raids

get_raids_by_type Raids Filter raids by Pokemon type

get_weather_boosted_raids Raids Raids boosted by weather conditions

get_raid_recommendations Raids Smart raid recommendations based on priorities

get_current_research Research All field research tasks and rewards

search_research_by_reward Research Find tasks by Pokemon reward

get_research_by_task_type Research Filter by task type (catch, battle, spin, etc.)

get_shiny_research_rewards Research Tasks with shiny reward potential

get_easy_research_tasks Research Quick-completion tasks for efficient farming

search_research_tasks Research Search tasks by description

get_research_recommendations Research Personalized research task recommendations

get_egg_hatches Eggs All Pokemon currently hatching from eggs

get_egg_hatches_by_distance Eggs Filter by egg distance (2km, 5km, 10km, etc.)

get_shiny_egg_hatches Eggs Shiny-eligible egg Pokemon

search_egg_pokemon Eggs Find specific Pokemon in egg pools

get_regional_egg_pokemon Eggs Region-exclusive Pokemon from eggs

get_gift_exchange_pokemon Eggs 7km gift egg Pokemon from friends

get_route_gift_pokemon Eggs 7km route gift egg Pokemon

get_adventure_sync_rewards Eggs Adventure Sync weekly walking rewards

get_egg_recommendations Eggs Smart incubation strategy recommendations

get_team_rocket_lineups Team Rocket All current Team Rocket trainer lineups

search_rocket_by_pokemon Team Rocket Find trainers using specific Pokemon

get_shiny_shadow_pokemon Team Rocket All Shadow Pokemon that can be shiny

get_rocket_encounters Team Rocket Pokemon available as encounter rewards

get_rocket_trainers_by_type Team Rocket Filter trainers by Pokemon type specialty

calculate_pokemon_weakness Team Rocket Type effectiveness against Shadow Pokemon

get_rocket_trainer_details Team Rocket Detailed information about a specific trainer

get_all_shiny_pokemon Cross-Platform All shiny Pokemon across all sources

search_pokemon_everywhere Cross-Platform Universal Pokemon search across all data

get_daily_priorities Cross-Platform Curated daily activity recommendations

get_server_status Cross-Platform Server status and data freshness information

clear_cache Cross-Platform Force fresh data retrieval from sources

______________________________________________________________________

Example Usage

获取今天的优先事项

使用 get_daily_priorities 该工具可为以下内容获取精心策划的建议：

• 要参加的活动
• 优先突袭闪亮的狩猎
• 轻松的研究任务和有价值的奖励
• 最优蛋孵化策略

寻找特定的口袋妖怪

使用 search_pokemon_everywhere 使用“Dratini”查找：

• 如果它出现在任何时事中
• 是否可用作突袭首领
• 哪些研究任务会奖励它
• 如果它能从蛋里孵化出来
• 所有来源的闪亮可用性

计划你的闪亮狩猎

使用 get_all_shiny_pokemon 要查看当前所有可用的闪亮，请执行以下操作：

• get_shiny_raids 用于突袭目标
• get_shiny_research_rewards 用于研究任务
• get_shiny_egg_hatches 鸡蛋计划
• get_route_gift_pokemon 特殊路线礼品机会
• get_shiny_shadow_pokemon Shadow Pokemon

______________________________________________________________________

Architecture

pokemon-go-mcp/
├── pogo_mcp/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main MCP server with cross-cutting tools
│   ├── api_client.py        # Local data client with caching
│   ├── types.py             # Type definitions and data classes
│   ├── utils.py             # Utility functions and formatters
│   ├── events.py            # Event-related tools
│   ├── raids.py             # Raid-related tools
│   ├── research.py          # Research-related tools
│   ├── eggs.py              # Egg-related tools
│   └── rocket_lineups.py    # Team Rocket-related tools
├── data/                    # Local JSON data files (git-ignored)
├── tests/                   # Test files
├── server.py                # Main entry point
├── pyproject.toml           # Project configuration
└── README.md                # This file

Component Technology Purpose

FastMCP MCP Framework Modern MCP server framework for easy tool registration

Custom Scraper Python Built-in scraper that collects and saves data to local JSON files

Local Data Client Python Reads data from local JSON files with smart caching

Type Safety Python Type Hints Full type hints and data validation throughout codebase

Modular Design Python Modules Separate modules for each data domain (events, raids, etc.)

______________________________________________________________________

Development

设置开发环境

# Clone repository
git clone 
cd pokemon-go-mcp

# Install with development dependencies
uv sync --all-extras --dev

# Code formatting
ruff format .

# Linting
ruff check .

# Type checking
pyright

测试

Command Description

pytest Run all tests

pytest --cov=pogo_mcp Run tests with coverage report

pytest tests/test_events_parsing.py Test specific module

______________________________________________________________________

License

This project is licensed under the MIT License - see the LICENSE file for details.