Skip to main content
Glama

Path of Exile 2 Build Optimizer MCP

by HivemindOverlord
OverviewInspectNewSchemaRelated ServersScore
Python
Hybrid

Path of Exile 2 Build Optimizer MCP

A comprehensive Model Context Protocol (MCP) server and web application for Path of Exile 2 character optimization, featuring AI-powered build recommendations, local game database, and intelligent upgrade suggestions.

Overview

This project combines the power of MCP servers, AI analysis, and comprehensive PoE2 game knowledge to provide players with intelligent, personalized build recommendations through natural language interaction.

Key Features

MCP Server

  • Character Data Fetcher: Pulls character information via official PoE API

  • Natural Language Interface: Ask questions like "How can I increase my lightning damage?"

  • Build Optimization: AI-powered recommendations for gear, passives, and skills

  • Rate-Limited API: Respectful API usage with intelligent caching

Local Game Database

  • Complete item database (bases, modifiers, uniques)

  • Passive skill tree data (nodes, connections, keystones)

  • Skill gems and support interactions

  • Ascendancy classes and notables

  • Crafting bench options and influenced modifiers

AI-Powered Features

  • Natural language build queries

  • Goal-based optimization (DPS, survivability, boss killing, clear speed)

  • Trade-off analysis

  • Budget-aware recommendations (low/medium/high/unlimited)

  • Meta comparison and trends

Build Calculator

  • Accurate DPS calculations with all modifiers

  • Defense analysis (EHP, mitigation, avoidance)

  • Damage breakdown by type

  • Skill interaction calculations

  • Curse and aura effectiveness

Web Interface

  • Character import via account/character name

  • Visual passive tree with optimization highlights

  • Gear slot recommendations with trade links

  • Build sharing and saving

  • Real-time calculation updates

Path of Building Integration

  • Import PoB build codes

  • Export optimized builds to PoB format

  • Sync with PoB's calculation engine

  • Support for PoB Community Fork features

Quick Start

Prerequisites

  • Python 3.9+

  • Node.js 18+ (for web interface)

  • Git

Installation

# Clone the repository cd ClaudesPathOfExile2EnhancementService # Install Python dependencies pip install -r requirements.txt # Install Node dependencies for web interface cd web npm install cd .. # Initialize the database python scripts/init_database.py # Seed with game data from poe2db.tw python scripts/seed_game_data.py # Set up trade API authentication (required for item search) pip install playwright playwright install chromium python scripts/setup_trade_auth.py

Running the Server

# Start the MCP server python src/mcp_server.py # In a separate terminal, start the web interface cd web npm run dev

Access the web interface at http://localhost:3000

Trade API Authentication

The MCP server can search the official Path of Exile trade site to recommend gear upgrades. This requires authentication to prevent bot abuse.

Automated Setup (Recommended - 2 Minutes)

# Install Playwright (one-time setup) pip install playwright playwright install chromium # Run the authentication helper python scripts/setup_trade_auth.py

What happens:

  1. Browser opens to pathofexile.com/trade

  2. You log in with your account (supports 2FA)

  3. Script automatically detects login and extracts your session cookie

  4. Cookie is saved to .env file

  5. Done! Trade search now works

See

  • Detailed step-by-step guide

  • Troubleshooting common issues

  • Security information

  • Cookie expiration details

Manual Setup (Fallback)

If the automated method doesn't work:

  1. Visit https://www.pathofexile.com/trade in your browser

  2. Log in to your account

  3. Press F12 to open DevTools

  4. Go to Application → Cookies → pathofexile.com

  5. Find the POESESSID cookie

  6. Copy its value (32-character string)

  7. Add to your .env file: POESESSID=your_cookie_value_here

Usage

Via Web Interface

  1. Navigate to http://localhost:3000

  2. Enter your account name and character name

  3. Click "Analyze Character"

  4. Review recommendations and optimization suggestions

Via MCP Protocol

from mcp_client import PoE2MCPClient async with PoE2MCPClient() as client: # Analyze character analysis = await client.analyze_character( account="YourAccount", character="YourCharacter" ) # Get natural language recommendations response = await client.query( "How can I improve my boss damage while staying tanky?" ) print(response)

Via Command Line

# Quick character analysis python cli.py analyze --account YourAccount --character YourCharacter # Natural language query python cli.py query "What gear upgrades should I prioritize?" # Build comparison python cli.py compare build1.json build2.json # Export to Path of Building python cli.py export --account YourAccount --character YourCharacter --output build.pob

Architecture

Core Components

src/ ├── mcp_server.py # Main MCP server ├── api/ │ ├── poe_api.py # Official PoE API client │ ├── poe2db_scraper.py # poe2db.tw data scraper │ ├── rate_limiter.py # API rate limiting │ └── cache_manager.py # Multi-tier caching ├── database/ │ ├── models.py # SQLAlchemy models │ ├── manager.py # Database manager │ └── migrations/ # Alembic migrations ├── calculator/ │ ├── damage_calc.py # DPS calculations │ ├── defense_calc.py # Defense calculations │ ├── modifier_calc.py # Modifier calculations │ └── build_scorer.py # Build quality scoring ├── optimizer/ │ ├── gear_optimizer.py # Gear optimization │ ├── passive_optimizer.py # Passive tree optimization │ ├── skill_optimizer.py # Skill setup optimization │ └── trade_advisor.py # Trade recommendations ├── ai/ │ ├── query_handler.py # Natural language processing │ ├── recommendation_engine.py # AI recommendations │ └── context_manager.py # Conversation context └── pob/ ├── importer.py # PoB import ├── exporter.py # PoB export └── xml_parser.py # PoB XML handling

Web Interface

web/ ├── src/ │ ├── components/ │ │ ├── CharacterImporter.tsx │ │ ├── PassiveTree.tsx │ │ ├── GearRecommendations.tsx │ │ ├── BuildComparison.tsx │ │ └── NLQueryInterface.tsx │ ├── api/ │ │ └── client.ts # API client │ ├── state/ │ │ └── store.ts # State management │ └── utils/ │ └── calculations.ts # Client-side calcs ├── public/ │ └── assets/ # Static assets └── package.json

Database Schema

Core Tables

  • items: All item bases and types

  • modifiers: Item modifiers and their values

  • passive_nodes: Passive tree nodes

  • passive_connections: Tree node connections

  • skills: Skill gems data

  • supports: Support gem data

  • uniques: Unique item data

  • ascendancies: Ascendancy classes

  • crafting: Crafting bench recipes

User Tables

  • saved_builds: User-saved builds

  • build_snapshots: Historical build versions

  • optimization_history: Past optimizations

API Integration

Official PoE API

  • Character data retrieval

  • Account information

  • Ladder rankings (with rate limiting)

  • Stash tab data (optional)

Rate Limiting Strategy

# Configurable rate limits RATE_LIMITS = { 'official_api': { 'requests_per_minute': 10, 'burst': 3, 'backoff': 'exponential' }, 'poe2db': { 'requests_per_minute': 30, 'cache_duration': 3600 # 1 hour } }

Caching Strategy

  1. L1 Cache: In-memory (5 minutes)

  2. L2 Cache: Redis (1 hour)

  3. L3 Cache: SQLite (persistent)

AI Integration

Natural Language Queries

# Example queries queries = [ "How can I increase my lightning damage?", "What's the best chest armor for my budget?", "Should I respec for more defense?", "Which passive nodes give the most DPS?", "How do I transition to CI?", "What uniques work well with my build?" ]

Context-Aware Responses

The AI maintains context about:

  • Current character state

  • Previous questions

  • Build goals

  • Budget constraints

  • Playstyle preferences

Development

Running Tests

# Run all tests pytest # Run specific test suite pytest tests/test_calculator.py # Run with coverage pytest --cov=src tests/

Code Quality

# Format code black src/ tests/ # Lint flake8 src/ tests/ # Type checking mypy src/

Database Migrations

# Create migration alembic revision --autogenerate -m "description" # Apply migrations alembic upgrade head # Rollback alembic downgrade -1

Configuration

Configuration is managed via environment variables and config.yaml:

# config.yaml server: host: 127.0.0.1 port: 8080 workers: 4 database: url: sqlite:///data/poe2_optimizer.db pool_size: 10 api: poe_api_rate_limit: 10 poe2db_rate_limit: 30 enable_caching: true ai: provider: anthropic # or openai model: claude-sonnet-4-20250514 max_tokens: 4096 temperature: 0.7 web: port: 3000 enable_build_sharing: true max_saved_builds_per_user: 50 features: enable_trade_integration: true enable_pob_export: true enable_ai_insights: true

Security & Privacy

  • No Credential Storage: Uses OAuth flow for PoE account access

  • Local-First: All character data cached locally

  • Optional Cloud Sync: Encrypted cloud backup (opt-in)

  • Rate Limit Enforcement: Prevents API abuse

  • Data Encryption: All saved builds encrypted at rest

Performance

  • Sub-second Analysis: Most character analyses complete in <500ms

  • Parallel Calculations: Multi-threaded build calculations

  • Intelligent Caching: Reduces API calls by 90%+

  • WebSocket Updates: Real-time updates without polling

  • CDN Assets: Static assets served via CDN

Contributing

This is a personal project, but contributions are welcome!

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests

  5. Submit a pull request

Roadmap

Phase 1 (Current)

  • MCP server foundation

  • Basic character analysis

  • Local database setup

  • API integration with rate limiting

Phase 2

  • Build calculator engine

  • Gear optimization

  • Passive tree optimization

  • Web interface MVP

Phase 3

  • AI natural language queries

  • Path of Building integration

  • Trade integration

  • Build sharing

Phase 4

  • Advanced AI insights

  • Meta trend analysis

  • Build version tracking

  • Mobile app

License

Private project for personal use.

Credits

Built with data from:

  • poe2db.tw - Comprehensive PoE2 game data

  • poe.ninja - Meta builds and economy data

  • Path of Exile 2 by Grinding Gear Games

Built for the PoE2 community | Report Issues

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Related Resources

New MCP Servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/HivemindOverlord/poe2-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server