poe2-build-mcp

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.

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.

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) 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.

Related MCP server: poe2-mcp

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) 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) 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 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 for the full design and 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):

git clone --depth 1 --branch dev \
  https://github.com/PathOfBuildingCommunity/PathOfBuilding-PoE2.git \
  pob/PathOfBuilding-PoE2

Set up and verify:

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:

{
  "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 and poe2db. Build numbers come from the PathOfBuilding-PoE2 community fork. Mechanics pages are sourced from the PoE2 Wiki, 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.