home / mcp / path of exile 2 build optimizer mcp server

Path of Exile 2 Build Optimizer MCP Server

This is a locally-run MCP attempt to make AI like Claude for Desktop or others better understand questions about Path of Exile 2. Good luck to me I guess?

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "hivemindoverlord-poe2-mcp": {
      "command": "python",
      "args": [
        "C:\\Users\\YourName\\poe2-mcp\\launch.py"
      ]
    }
  }
}

You run a Path of Exile 2 character optimization MCP server that analyzes your build, validates your gear and gem choices, and integrates with your AI assistant to give clear, actionable recommendations. It pulls data from public sources, analyzes defenses, skills, and passives, and can import/export Path of Building data to help you tune your character efficiently.

How to use

After you connect a compatible MCP client, you can ask your AI assistant to analyze and optimize your PoE2 character. You can import your character from poe.ninja, validate your support gem combinations, inspect gem data, and compare your build to top ladder players. You can also import and export Path of Building codes to trial different configurations and explanations of PoE2 mechanics to better understand the choices.

How to install

Prerequisites you need before you start:

Python 3.9 or newer must be installed
A compatible MCP client (Claude Desktop, ChatGPT Desktop, Cursor, Windsurf, etc.)
Access to your PoE2 character on poe.ninja (public profile)

# Option A: Install via PyPI (recommended)
pip install poe2-mcp

# Option B: Install from source
git clone https://github.com/HivemindOverlord/poe2-mcp.git
cd poe2-mcp
pip install -e .

Run the MCP server locally

You can run the MCP server directly from your local environment. Use the stdio configuration to launch the server with Python. This starts a local server process that your MCP client can communicate with.

# Windows example (stdio config in Claude Desktop)
{
  "type": "stdio",
  "name": "poe2_optimizer",
  "command": "python",
  "args": ["C:\\Users\\YourName\\poe2-mcp\\launch.py"]
}
```

```json
# macOS/Linux example (stdio config in Claude Desktop)
{
  "type": "stdio",
  "name": "poe2_optimizer",
  "command": "python3",
  "args": ["/Users/YourName/poe2-mcp/launch.py"]
}
```

Restart your MCP client after adding the server configuration so it can connect to the local server.

Notes on using the tool with your AI assistant

Once connected, you can ask natural language questions and the AI assistant will use the available tools to analyze your character, validate builds, or export/import Path of Building data.

Available tools

analyze_character

Full character analysis including defenses, skills, gear, and passive tree.

import_poe_ninja_url

Import character data directly from a poe.ninja URL.

compare_to_top_players

Compare your build to top ladder players to identify gaps and optimization opportunities.

analyze_passive_tree

Analyze allocated passive nodes for efficiency and synergy.

validate_support_combination

Check if a given set of support gems works together without conflicts.

validate_build_constraints

Validate your build against game rules and constraints.

inspect_support_gem

View complete data for a specific support gem.

inspect_spell_gem

View complete data for a spell gem.

list_all_supports

List all available support gems.

list_all_spells

List all available spell gems.

list_all_keystones

List keystones with full stats.

inspect_keystone

Get complete keystone details by name.

list_all_notables

List all notable passive passives with stats.

inspect_passive_node

Get details for a specific passive node.

list_all_base_items

List all base item types.

inspect_base_item

Get details for a specific base item.

inspect_mod

Get complete details for a specific item 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.

import_pob

Import Path of Building code.

export_pob

Export build to PoB format.

get_pob_code

Get PoB code for a character.

search_items

Search local item database.

search_trade_items

Search official trade site (requires authentication).