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.

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 & tweak builds from scratch: set class/ascendancy, level, skills + supports, gear, config, and the passive tree, validating every change on the engine. There's a greedy passive optimizer and an A/B compare_to.

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 (42 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(…)
• equip_item(raw) · unequip_item(slot) · list_config_options(query?)
• evaluate_build(goals) — pass/fail against numeric goals · compare_to(source) — A/B deltas
• solve_for(metric, target, lever) — root-find the modifier magnitude needed to hit a stat target
• 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) — greedy point allocation (metric="balanced" raises DPS+EHP)
• 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) — concise mechanics references (resistances, ailments, spirit, EHP, …)
• search_mods(query, item_tag?, mod_type?) / reverse_lookup(stat)
• search_uniques(query, item_type?) / get_unique(name)
• 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)
• 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.

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. This project is not affiliated with or endorsed by Grinding Gear Games.