Path of Exile 2 Build Optimizer MCP
Community Project Disclaimer
This is an independent, fan-made community project built out of love for Path of Exile 2. It is not affiliated with, endorsed by, or officially connected to Grinding Gear Games in any way. Path of Exile is a trademark of Grinding Gear Games. All game data and assets remain the property of their respective owners.
A Model Context Protocol (MCP) server for Path of Exile 2 character analysis and optimization. Provides 32 MCP tools for AI-powered build analysis, passive tree analysis, item mod validation, support gem validation, and Path of Building integration.
What is This?
This is an MCP server - a backend service that gives AI assistants (like Claude, ChatGPT, Cursor, etc.) the ability to analyze your Path of Exile 2 characters and provide optimization recommendations.
What it does:
- Fetches your character data from poe.ninja
- Analyzes defensive stats, skills, gear, and passive tree
- Validates support gem combinations (prevents invalid recommendations)
- Inspects spell and support gem data
- Imports/exports Path of Building codes
- Compares your build to top ladder players
- Explains PoE2 game mechanics
What you need:
- An AI assistant that supports MCP (Claude Desktop, ChatGPT Desktop, Cursor, Windsurf, etc.)
- Python 3.9+ installed
- Your PoE2 character on poe.ninja (public profile)
Quick Start
1. Install
Option A: PyPI (Recommended)
pip install poe2-mcp
Option B: From Source
git clone https://github.com/HivemindOverlord/poe2-mcp.git
cd poe2-mcp
pip install -e .
2. Connect to Your AI Assistant
Choose your platform below:
Claude Desktop Integration
Option A: Manual Configuration (Recommended for Development)
Edit your Claude Desktop config file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Add this server (replace the path with your actual installation path):
Windows:
{
"mcpServers": {
"poe2-optimizer": {
"command": "python",
"args": ["C:\\Users\\YourName\\poe2-mcp\\launch.py"],
"env": {}
}
}
}
macOS/Linux:
{
"mcpServers": {
"poe2-optimizer": {
"command": "python3",
"args": ["/Users/YourName/poe2-mcp/launch.py"],
"env": {}
}
}
}
Restart Claude Desktop. The server will appear in your MCP tools.
Option B: Download .mcpb Bundle (One-Click Install)
Pre-built MCP bundles are available for one-click installation in Claude Desktop:
- Download
poe2-mcp-1.0.0.mcpbfrom the GitHub Releases - In Claude Desktop: Settings > Extensions > Install Extension
- Select the downloaded
.mcpbfile
Note: The bundle is ~109MB as it includes all game data files. Python 3.9+ must be installed on your system.
Recommendation: For development or if you want automatic updates, use Option A (manual configuration) with
pip install poe2-mcp.
Other AI Platforms
MCP is an open standard supported by multiple AI platforms:
OpenAI ChatGPT Desktop
ChatGPT desktop app supports MCP servers. Configuration varies by version - check OpenAI's documentation for current setup instructions.
Cursor AI
Cursor supports MCP via SSE protocol. Add to your Cursor settings:
{
"mcp": {
"servers": {
"poe2-optimizer": {
"command": "python",
"args": ["/path/to/poe2-mcp/launch.py"]
}
}
}
}
Windsurf
Windsurf has a built-in MCP Plugin Store. You can either:
- Search for "poe2" in the plugin store (if published)
- Manually add the server path in settings
Claude Code (CLI)
# In your project directory
claude mcp add poe2-optimizer python /path/to/poe2-mcp/launch.py
Other Compatible Clients
- Zed Editor
- Replit
- Codeium
- Sourcegraph
- Microsoft Semantic Kernel
- Salesforce Agentforce
Check each platform's documentation for MCP server configuration.
Available Tools (32 Registered)
Once connected, you can ask your AI assistant to use these tools:
Character Analysis
| Tool | Description |
|---|---|
analyze_character | Full character analysis (defenses, skills, gear, passives) |
import_poe_ninja_url | Import character from poe.ninja URL directly |
compare_to_top_players | Compare your build to ladder leaders |
analyze_passive_tree | Analyze allocated passive nodes |
Validation & Inspection
| Tool | Description |
|---|---|
validate_support_combination | Check if support gems work together |
validate_build_constraints | Validate build against game rules |
inspect_support_gem | View complete support gem data |
inspect_spell_gem | View complete spell gem data |
list_all_supports | List all available support gems |
list_all_spells | List all available spell gems |
Passive Tree Data
| Tool | Description |
|---|---|
list_all_keystones | List all keystones with full stats |
inspect_keystone | Get complete keystone details by name |
list_all_notables | List all notable passives with stats |
inspect_passive_node | Get details for any passive node |
Base Item Data
| Tool | Description |
|---|---|
list_all_base_items | List all base item types |
inspect_base_item | Get details for a specific base item |
Item Mod Data
| Tool | Description |
|---|---|
inspect_mod | Get complete details for a specific mod by ID |
list_all_mods | List mods with filtering by type (PREFIX/SUFFIX/IMPLICIT) |
search_mods_by_stat | Search for mods by keyword (e.g., "fire", "life") |
get_mod_tiers | Show all tier variations of a mod family |
validate_item_mods | Check if mods can legally exist together on an item |
get_available_mods | List all mods available for a generation type |
Path of Building
| Tool | Description |
|---|---|
import_pob | Import Path of Building code |
export_pob | Export build to PoB format |
get_pob_code | Get PoB code for a character |
Trade & Items
| Tool | Description |
|---|---|
search_items | Search local item database |
search_trade_items | Search official trade site (requires auth) |
setup_trade_auth | Set up trade site authentication |
Knowledge & Utility
| Tool | Description |
|---|---|
explain_mechanic | Explain PoE2 game mechanics |
get_formula | Get calculation formulas |
health_check | Check server status |
clear_cache | Clear cached data |
Note: Additional tools (DPS calculator, EHP calculator, optimizers) have handlers implemented but are not yet registered. These may be enabled in future updates.
Example Usage
Once configured, just talk to your AI naturally:
"Analyze my character TomawarTheFourth from account Tomawar"
"Import this poe.ninja URL: https://poe.ninja/poe2/builds/char/..."
"Can I use Faster Projectiles and Slower Projectiles together?" (uses
validate_support_combination)
"Show me all support gems that work with projectiles" (uses
list_all_supports)
"What keystones are available for life builds?" (uses
list_all_keystones)
"Tell me about Chaos Inoculation" (uses
inspect_keystone)
"Compare my build to top Witchhunter players"
"Explain how armor works in PoE2"
"What prefixes can roll on items?" (uses
get_available_mods)
"Show me all tiers of the Strength mod" (uses
get_mod_tiers)
"Can Strength1 and Strength2 exist on the same item?" (uses
validate_item_mods)
"Search for fire resistance mods" (uses
search_mods_by_stat)
The AI will use the appropriate tools automatically.
Trade API Authentication (Optional)
For search_trade_items to work, you need to authenticate with pathofexile.com:
pip install playwright
playwright install chromium
python scripts/setup_trade_auth.py
This opens a browser for you to log in, then saves your session cookie.
Local Game Database
The server includes a local database with:
- 4,975+ passive tree nodes
- 335+ ascendancy nodes (99% coverage)
- 14,269 item modifiers (2,252 prefixes, 2,037 suffixes, 8,930 implicits)
- Complete skill gem data from Path of Building
- Support gem effects and interactions
- Base items and unique items
Data is loaded from data/ directory on startup.
Architecture
poe2-mcp/
├── launch.py # Entry point
├── src/
│ ├── mcp_server.py # Main MCP server (32 tools registered)
│ ├── api/ # External API clients
│ │ ├── poe_ninja_api.py
│ │ ├── character_fetcher.py
│ │ └── rate_limiter.py
│ ├── analyzer/ # Analysis components
│ │ ├── character_analyzer.py
│ │ └── weakness_detector.py
│ ├── calculator/ # Numeric calculations
│ │ ├── ehp_calculator.py
│ │ ├── spirit_calculator.py
│ │ └── stun_calculator.py
│ ├── data/ # Data providers
│ │ ├── mod_data_provider.py
│ │ └── fresh_data_provider.py
│ ├── optimizer/ # Optimization engines
│ │ ├── gear_optimizer.py
│ │ └── gem_synergy_calculator.py
│ ├── parsers/ # Data parsers
│ │ ├── passive_tree_resolver.py
│ │ └── specifications/ # Datc64 format specifications
│ ├── knowledge/ # Game mechanics knowledge base
│ │ └── poe2_mechanics.py
│ └── database/ # SQLite database
│ ├── models.py
│ └── manager.py
├── data/ # Game data files
│ ├── psg_passive_nodes.json
│ ├── poe2_support_gems_database.json
│ └── poe2_mods_extracted.json
└── tests/ # Test suite
Development
Running Tests
pytest tests/ -v
Running the Server Directly
# If installed via pip
poe2-mcp
# From source
python launch.py
Key Files
src/mcp_server.py- MCP server with 32 registered toolssrc/data/mod_data_provider.py- Item mod data access layersrc/calculator/ehp_calculator.py- EHP calculationssrc/optimizer/gem_synergy_calculator.py- Support gem logicdata/psg_passive_nodes.json- Passive tree databasedata/poe2_mods_extracted.json- Item modifier database (14,269 mods)
Troubleshooting
"Server not found" in Claude Desktop
- Check the path in config is absolute (not relative)
- Ensure Python is in your PATH
- Try running
python launch.pymanually to see errors
"No character found"
- Your character must be on poe.ninja (public ladder)
- Character name is case-sensitive
- Try the full poe.ninja URL with
import_poe_ninja_url
Tools return empty results
- Database may need initialization:
python launch.pyhandles this - Check
data/directory exists with JSON files
Credits
Data sources:
- poe.ninja - Character data and builds
- Path of Building (PoE2) - Skill data
- Path of Grinding - Passive tree data
MCP Protocol:
License
MIT License - See LICENSE for details.
This is a community project. Not affiliated with Grinding Gear Games.
