poe2-build-mcp

# poe2-build-mcp [](https://github.com/MaxWilk/poe2-build-mcp/releases/latest) [](LICENSE)  > A **Path of Exile 2** build assistant for LLMs. It pairs a queryable game corpus with a > **Path-of-Building–faithful calculation engine**, so an AI can import your build, answer > questions, and theorycraft against **real, computed numbers — never invented ones.** Install it as a one-click `.mcpb` in Claude Desktop and ask things like: - *"Import this PoB code — where's my DPS bottlenecked, and what's the cheapest fix?"* - *"Build me a level-90 Witchhunter Detonate Living and make sure it caps resistances."* - *"What supports should Spark use, and how much does each one actually add?"* - *"Is this build tanky enough for endgame bosses? What's my weakest defensive layer?"* Every DPS / EHP / resistance figure it reports is computed by a real headless Path of Building, not guessed. When PoB can't model something, it says so instead of making a number up. ## Install (Claude Desktop) 1. Download the `.mcpb` for your OS from the [latest release](https://github.com/MaxWilk/poe2-build-mcp/releases/latest). 2. Open it with Claude Desktop and install it when prompted (extensions are managed under **Settings → Extensions**). 3. Start asking build questions. The first call boots the engine (a few seconds to load game data); everything after is fast. The bundle ships the PoB engine, LuaJIT, the game-data corpus, and Python deps. You need **Python 3.11+** available on your system. The corpus and engine **self-update** from validated GitHub releases into a writable user-data folder, so the data stays current without a reinstall (server *code* updates land when you install a newer `.mcpb`). See [PACKAGING.md](PACKAGING.md). ### Starting a session Once the extension is enabled, just ask a Path of Exile 2 question — Claude will reach for the tools. To kick off explicitly, pick the **`start_build_session`** prompt from Claude Desktop's prompt menu (or a task-specific one: `analyze_build`, `build_from_goal`, `audit_defenses`). In Claude Code, configure the server (see [Build from source](#build-from-source-development)) and, if you like, add a line to your `CLAUDE.md` such as *"For Path of Exile 2 build questions, use the poe2-build MCP tools."* so it prefers them automatically. ## What it can do **Import & analyze** a build from a PoB share code, a pobb.in/pastebin link, or raw PoB XML — then read back computed DPS, EHP, resistances, life/ES, and more. **Create, craft & max** builds from scratch: set class/ascendancy, level, skills, gear, config, and the passive tree, validating every change on the engine. Optimizers craft blended best-in-slot gear and jewels, auto-base and plan a whole gear set that caps resists (with an EHP floor), pick the strongest support set (engine-measured), surface build-defining uniques, and rank what to upgrade next — plus a greedy passive optimizer and an A/B `compare_to`. > From-scratch construction yields a *complete, resist-capped, engine-verified* build that clears > most endgame. The absolute 600k–1M-DPS meta ceiling comes from expert archetype synthesis, perfect > gear/uniques, and a few mechanics PoB doesn't yet model (e.g. energy-meta triggers) — for that, > `import_build` an established build and **verify + improve** it with the same tools. **Look things up** offline: items, skill/support gems, affixes, uniques, passives, ascendancies — a bundled SQLite/FTS corpus, no network needed. **Reason well**, not just compute: `build_advice` and `explain_mechanic` provide durable PoE2 optimization principles and mechanics references (see [server/BUILD_ADVICE.md](server/BUILD_ADVICE.md)) so the assistant knows *what* to change; the engine confirms the effect. **Stay current**: live currency/unique prices, corpus freshness checks, and one-click self-update. ### The toolset (64 MCP tools) *Build / compute — real Path of Building numbers:* - `import_build(source)` — PoB share code, pobb.in/pastebin link, or raw XML - `get_build_stats(keys?)` — computed stats (DPS, EHP, resistances, life/ES/mana, …) - `get_build()` / `export_build()` — full read-back / export as a PoB import code - `get_defenses()` — resists (+over-cap), EHP, and the active resistance-penalty assumption - `set_class(class, ascendancy?)` · `set_level(level)` · `set_skill(skill)` · `set_config(…)` - `add_skill_group(skill)` — add an aura/herald/buff (e.g. Archmage) that buffs the build without replacing the main skill - `equip_item(raw)` · `unequip_item(slot)` · `list_config_options(query?)` - `list_jewel_sockets()` / `equip_jewel(raw, socket?)` — list tree jewel sockets / socket a jewel - `apply_combat_profile(tier, …)` — switch on a realistic boss-fight profile (shock/curse/charges) in one call - `evaluate_build(goals)` — pass/fail against numeric goals · `compare_to(source)` — A/B deltas - `pinnacle_readiness(min_dps?, min_ehp?)` — gate a build against the endgame checklist (resists + chaos + EHP + DPS) - `list_reference_builds(query?)` / `benchmark_build()` — browse / calibrate against engine-verified reference builds (calibration only) - `solve_for(metric, target, lever)` — root-find the modifier magnitude needed to hit a stat target - `rank_levers(metric?, unit?, levers?)` — rank stat levers by marginal gain; the min/max "where to invest next" tool - `list_levers()` — the named levers `solve_for`/`rank_levers` accept - `search_passives(query?, node_type?)` / `get_passive(node)` - `alloc_passive(node)` / `dealloc_passive(node)` — allocate/route by id or name, with deltas - `optimize_passives(metric, points, goals?, require?)` — greedy allocation: one stat, `"balanced"`, or weighted `goals` (e.g. Life+Crit); can `require` nodes - `optimize_item(slot, metric?, goals?)` — craft a best-in-slot rare for one metric or a weighted `goals` blend (damage+defense); reports per-affix attainability (ilvl/tier) + craft-effort - `craft_item(slot, metric?, goals?)` — best-in-slot using the FULL crafting system: runes/soul cores + Perfect essences (beyond-pool mods) + corruptions, each engine-valued - `optimize_jewel(metric?, base?, goals?)` — craft the best rare jewel (then socket with `equip_jewel`) - `optimize_supports(metric?, goals?)` — pick the best support-gem set, measured on the engine - `rank_upgrades(metric?, goals?)` — rank gear slots by recraft gain ("what to upgrade next") - `plan_gear(dps_weight?)` — plan a whole gear set: damage-max with resists capped (cross-slot budget allocation) - `optimize_build(metric?, min_ehp?, levers?, try_uniques?, archetypes?)` — the holistic whole-build optimizer: archetype-seeded commit-and-max across tree + gear + jewels + supports (does the synthesis the per-slot tools can't); leaves the best build loaded - `scaffold_gear(pool?, target_resist?)` — fill empty defensive slots to close resist/pool gaps (baseline, not optimal) - `new_build()` — reset to a blank build (clean from-scratch start) - `engine_health()` — engine + install diagnostics (liveness, LuaJIT/tree/data/server versions) *Corpus / knowledge — bundled SQLite + FTS, no engine needed:* - `search_items(query, item_class?)` / `get_item(name_or_id)` - `find_skills(query?, gem_type?, tag?, color?)` / `get_gem(name_or_id)` / `find_supports_for(skill)` - `build_advice(topic?)` — evergreen build-optimization principles - `explain_mechanic(topic)` — our principle + the matching auto-refreshed wiki page (attributed) - `search_mechanics(query)` — full-text search the bundled wiki mechanics tier - `relevant_mechanics()` — mechanics worth reading for the *active* build + the engine damage diagnostic - `search_mods(query, item_tag?, mod_type?)` / `reverse_lookup(stat)` - `search_uniques(query, item_type?)` / `get_unique(name)` - `relevant_uniques()` — unique items + unique jewels that synergize with the *active* build (build-defining gear a rare-only build misses; corpus suggestions, verify on the engine) - `parse_item(text)` — parse an item's text → affix tiers (T1=best) + open prefix/suffix slots - `list_ascendancies(character?)` / `corpus_info()` *Live ops & self-update — network:* - `get_prices(query, kind, league?)` — poe2scout currency/unique prices · `list_price_leagues()` - `get_meta_builds(league?)` — live ascendancy popularity (poe.ninja; context, not a recommendation) - `lookup_mechanic(topic)` — fetch a mechanic/skill/item live from the PoE2 Wiki (long-tail fallback) - `check_for_updates()` / `apply_updates()` — pull validated engine + corpus releases - `check_data_version()` / `update_corpus(rebuild_from_source?)` The connector also ships an LLM-facing operating guide (delivered via the MCP `instructions` channel, from [server/ASSISTANT_GUIDE.md](server/ASSISTANT_GUIDE.md)) plus workflow prompts (`analyze_build`, `build_from_goal`, `audit_defenses`) so the assistant uses the tools cohesively. ## How it works Two layers behind one Python server: - **Compute** — a vendored [PathOfBuilding-PoE2](https://github.com/PathOfBuildingCommunity/PathOfBuilding-PoE2) fork run headless under LuaJIT as a persistent JSON-RPC subprocess (loads game data once, answers many calls cheaply). PoB is pinned to a release tag and bumped deliberately behind golden-build tests. - **Knowledge** — a bundled, read-only SQLite/FTS corpus built offline from RePoE/poe2db, plus a wiki-sourced **mechanics** tier (PoE2 Wiki). Both refresh **without a new install**: the server pulls validated corpus + engine on startup, and a scheduled CI job rebuilds the corpus from upstream when it actually changes — so game data and mechanics stay current automatically. Knowledge code never imports compute code; cross-layer orchestration lives in `server/main.py`. See [PLAN.md](PLAN.md) for the full design and [CLAUDE.md](CLAUDE.md) for engineering conventions. ## Build from source (development) Prerequisites: **Python 3.11+**, **uv** (`python -m pip install uv`), and **LuaJIT 2.1** (Windows via MSYS2: `pacman -S mingw-w64-ucrt-x86_64-luajit`; auto-detected at `C:\msys64\ucrt64\bin\luajit.exe`, override with the `POB_LUAJIT` env var). Then clone the git-ignored PoB working copy (pinned in [pob/PINNED.md](pob/PINNED.md)): ```sh git clone --depth 1 --branch dev \ https://github.com/PathOfBuildingCommunity/PathOfBuilding-PoE2.git \ pob/PathOfBuilding-PoE2 ``` Set up and verify: ```sh uv sync # create venv, install deps uv run python -m pipeline.build_corpus # build data/corpus.sqlite from RePoE (network) uv run pytest # golden-build suite (engine + corpus) uv run python scripts/smoke_mcp_client.py # full MCP protocol over stdio (all tool groups) ``` The `scripts/smoke_*.py` files cover each tool group individually; `pytest` is the pinned golden-value regression suite (see `tests/`). On Windows, run the smoke scripts with `PYTHONUTF8=1` to avoid code-page issues with some item/skill names (the server itself is unaffected). Lint/type with `uv run ruff check . && uv run mypy server`. To run from source in Claude Desktop, add to `claude_desktop_config.json`: ```json { "mcpServers": { "poe2-build": { "command": "C:\\Users\\<you>\\AppData\\Roaming\\Python\\Python312\\Scripts\\uv.exe", "args": ["run", "--directory", "W:\\GitHub\\poe2-build-mcp", "python", "-m", "server.main"] } } } ``` ## Data & credit Game data is GGG's IP, redistributed as *derived* data within established community-tool norms — with credit to the [RePoE fork](https://repoe-fork.github.io/poe2/) and poe2db. Build numbers come from the [PathOfBuilding-PoE2](https://github.com/PathOfBuildingCommunity/PathOfBuilding-PoE2) community fork. Mechanics pages are sourced from the [PoE2 Wiki](https://www.poe2wiki.net/), licensed **CC BY-NC-SA 3.0**; they're kept in a separate, attributed corpus tier (each entry carries its source link + license). This is a free, non-commercial tool, and is not affiliated with or endorsed by Grinding Gear Games.