Path of Exile 2 Build OptimizerBLOCK
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? -- If you like what you see and would like to see continuing development, please support me with your donations here: https://buymeacoffee.com/to
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://pypi.org/project/poe2-mcp/) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT)
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 38 MCP tools for AI-powered build analysis, passive tree analysis, item mod validation, support gem validation, and Path of Building integration (including a live bridge to a running PoB instance).
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
41ec1c104408OBSERVED · 2026-10-07Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add poe2-undying-hate-calculator -- npx -y [email protected]
{
"mcpServers": {
"poe2-undying-hate-calculator": {
"command": "npx",
"args": [
"-y",
"[email protected]"
]
}
}
}Exposed tools (35)
28 read · 6 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
analyze_passive_tree | read | Analyze passive tree allocation, find paths to notables, and get recommendations. Resolves poe.ninja node IDs to full passive data including names, stats, and connections. |
check_tree_freshness | read | Self-diagnostic: compare local game-data version (data/game/version.json) against poe.ninja |
clear_cache | destructive | Clear all cached data (memory, SQLite, Redis). |
compare_to_top_players | read | Fetch top ladder players using the same skills for comparison. Returns raw data about what high-performers do differently. |
export_pob | read | Export character data to Path of Building format. |
get_available_mods | read | Get all mods that could roll on an item type. Filter by generation type (PREFIX/SUFFIX), item base class (e.g. Wand, Ring, Body Armour), and level requirements. |
get_formula | read | Get PoE2 calculation formulas for Claude to use. Covers DPS, EHP, armor, resistance, spirit, stun, crit, conversion, DoT, block. Claude performs calculations using these formulas. |
get_mod_tiers | read | Get all tier variations of a mod family (e.g., IncreasedLife1-13). Shows progression from T1 to highest tier with level requirements and values. |
get_pob_code | read | Fetch a ready-to-use PoB code from poe.ninja for a character. |
health_check | write | Run diagnostic checks on the MCP server (database, API, config). |
import_pob | write | Import a Path of Building build. Accepts a local file path (most reliable — a saved .xml build or a .txt containing the share code, auto-detected), raw uncompressed PoB XML, or an inline base64 share code. Provide exactly one of the three inputs. Returns parsed build data. |
import_poe_ninja_url | write | Import and analyze a character directly from a poe.ninja profile URL. Parses the URL to extract account and character, then fetches full character data. |
inspect_base_item | read | Get complete details for a specific base item type. |
inspect_keystone | read | Get complete details for a specific keystone by name, including all stats and effects. |
inspect_mod | read | Get complete details for a specific mod by ID, including generation type, level requirement, and stat values. |
inspect_passive_node | read | Get complete details for any passive node by name or ID. Works for keystones, notables, and small nodes. |
inspect_spell_gem | read | Get complete data for a spell gem including tags, base damage, cast time, mana/spirit cost. |
inspect_support_gem | read | Get complete data for a support gem including tags, effects, incompatibilities, spirit cost. |
list_all_base_items | read | List all base item types in the game (weapons, armor, accessories). |
list_all_keystones | read | List all keystone passive nodes with their full stats. Keystones are powerful build-defining passives with major tradeoffs. |
list_all_mods | read | List all mods with optional filtering by generation type (PREFIX, SUFFIX, IMPLICIT, CORRUPTED) and stat keywords. |
list_all_notables | read | List all notable passive nodes. Notables are medium-power passives that define build paths. |
list_all_spells | read | List all spell gems with optional filtering by element, tags, damage. |
list_all_supports | read | List all support gems with optional filtering by tags, spirit cost, etc. |
pob_get_build | read | Pull the build currently open in a running Path of Building as a PoB share code (default) or raw XML. Use |
pob_get_calcs | read | Pull computed stats (DPS, Life/ES, resistances, attributes, max hit taken) from PoB |
pob_get_passive_tree | read | Pull the allocated passive tree from the build currently open in a running Path of Building: class, ascendancy, every allocated node (id, name, keystone/notable flags, stats) and total points. Requires PoB running with the bridge addon and a build loaded. |
pob_install_addon | write | Install the MCP Bridge addon into the local Path of Building (PoE2) so the live bridge works. Auto-detects the PoB install (or pass pob_path), copies the addon, and patches Launch.lua (with a backup). The user must restart PoB afterward. Idempotent. |
pob_load_build | read | Load a build into a running Path of Building so the user can see it. Accepts a PoB share code (preferred — what players paste) or raw XML. PoB must be running with the bridge addon. |
pob_status | read | Check the live Path of Building bridge: whether PoB (PoE2) is installed, whether the MCP Bridge addon is deployed and Launch.lua is patched, and whether a running PoB is reachable on 127.0.0.1:49085 right now. Use this first before other pob_* tools. |
search_items | read | Search the local game database for items by name, type, or filters. |
search_mods_by_stat | read | Search for mods that grant a specific stat effect. Returns all mods matching the stat keyword. |
search_trade_items | read | Search the official PoE2 trade site for items. Requires POESESSID (use setup_trade_auth first). |
setup_trade_auth | write | Set up trade API authentication by extracting POESESSID via browser login. |
validate_item_mods | write | Validate if a set of mods can legally exist on an item. Checks for mod family conflicts (can |
Trust audit
BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (3 observation(s))
- Network
- declared (8 observation(s))
- Shell
- declared (2 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (20)
value = pickle.loads(value_blob)
__import__(package)
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
- http://127.0.0.1:3000
CORS_ORIGINS: str = Field(default="http://localhost:3000,http://127.0.0.1:3000")
root = ET.fromstring(xml_str.lstrip("").strip())clear_cache
decoded = base64.b64decode(code)
compressed = base64.b64decode(encoded)
_assert_build_ok(PoBImporter().import_xml_sync("" + SAMPLE_XML))mcp, fastapi, uvicorn, pydantic, pydantic-settings, sqlalchemy, alembic, aiosqlite
svg-pan-zoom, @sveltejs/vite-plugin-svelte, esbuild, svelte, vite
- **Manual Method:** Open DevTools → Cookies (see `.env.example`)
9. Open .env file
10. Open .env file
data/complete_models/active_skills.json
data/complete_models/passive_tree.json
data/complete_models/stats.json
data/game/base_items/base_items.json
data/game/mods/mods.json
Gates applied: no_behavioural_pass.
41ec1c104408full audit observations/trust-audit/mcp-server/hivemindoverlord__path-of-exile-2-build-optimizer.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-07 | 41ec1c104408 | BLOCK | D | 69 | first audit |
Questions
What is the 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? -- If you like what you see and would like to see continuing development, please support me with your donations here: https://buymeacoffee.com/to
What tools does Path of Exile 2 Build Optimizer expose?
35 in total: 28 read-only, 6 that write, and 1 that can delete or overwrite (clear_cache). Every one is listed on this page with its risk.
Is Path of Exile 2 Build Optimizer safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (69/100) and found 1 critical or high issue in the source. Each one is listed on this page with the file and line it is on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Path of Exile 2 Build Optimizer need?
No credential environment variables were found in its source, so it appears to need none.
How does Path of Exile 2 Build Optimizer run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as poe2-undying-hate-calculator at 1.0.0.
How current is this page?
The grade is for one exact copy of the source (41ec1c104408), read on 2026-10-07. The repository is watched and re-audited when it changes.