pob-mcp — Path of Building MCP server

An MCP server that runs Path of Building Community (Path of Exile 1) headlessly, so Claude (or any MCP client) can read builds, get real PoB numbers, test changes and export the result.

pip install pathofbuilding-mcp

It also needs a checkout of the Path of Building source; see Setup.

It doesn't re-implement any game math: it boots PoB's own Lua code inside an embedded LuaJIT (via lupa), so every number matches what the PoB app shows for the same build and config.

Tools

Reading and evaluating

Changing and optimising

Creating builds

Working with PoB's Builds folder

Together these let you and the agent work on the same build: edit in PoB, save, and the agent picks the change up; or let the agent save and press F5 in PoB.

Edit operations

Used by compare_changes and apply_changes. Several edits can go in one call.

Gem names work with or without the "Support" suffix.

Setup

1. Get the PoB source (the installed app lacks the headless support files):

   git clone https://github.com/PathOfBuildingCommunity/PathOfBuilding
   

   git pull it whenever PoB updates for a new league.

2. Install this package (Python 3.10+) from PyPI:

   pip install pathofbuilding-mcp
   

   pip install -U pathofbuilding-mcp updates it. For development, clone this repo and use pip install -e . so code changes take effect without reinstalling.

   This pulls in mcp, lupa and pillow (for tree pictures). lupa ships its own LuaJIT, so there's nothing else to install — no system Lua, no luarocks.

3. Add it to Claude Desktop (claude_desktop_config.json):

   {
     "mcpServers": {
       "path-of-building": {
         "command": "pathofbuilding-mcp",
         "env": { "POB_PATH": "C:\\Users\\you\\PathOfBuilding" }
       }
     }
   }
   

   If pathofbuilding-mcp isn't on PATH, use "command": "python", "args": ["-m", "pob_mcp"]. For Claude Code: claude mcp add pob -e POB_PATH=/path/to/PathOfBuilding -- pathofbuilding-mcp.

POB_PATH can point at the checkout or its src folder; --pob-path works too. If unset, the server looks in ~/PathOfBuilding.

Example prompts

• "Load https://pobb.in/xxxx and tell me my weakest defensive layer."
• "What are the best 5 notables for my next points, by DPS per point? And for EHP?"
• "Which support in my main 6-link is weakest, and what should replace it?"
• "I need 10 points for a respec. Which notables cost me the least damage?"
• "Is anything wrong with this build?"
• "Which of these three notables gives the most DPS per point: …?"
• "Compare my current ring with this one: (pasted item text)."
• "Swap Controlled Destruction for Elemental Focus in my main link and show the difference against a Pinnacle boss."
• "Apply those changes and give me the new share code."
• "Create a level 95 Elementalist Arc build with a Tabula Rasa, cap my resists, and give me the share code."
• "Make a Deadeye Lightning Arrow build that balances damage and EHP, then tell me what gear to look for."

How it works

MCP client ⇄ stdio ⇄ server.py (FastMCP/MCPServer)
                         │  one worker thread
                         ▼
                  engine.py ── lupa (embedded LuaJIT 2.1)
                         │
                  bridge.lua ── boots PoB (Launch.lua, Modules, Classes, Data)
                                and exposes a small JSON API

• The first call takes ~5 seconds while PoB loads its data (the server starts this in the background as soon as it launches). After that, calls are fast; a what-if comparison takes well under a second.
• rank_passives and rank_support_gems use PoB's internal "misc calculator", the same fast path behind its node power heatmap and its gem-list DPS sort. Ranking every notable within 8 points takes a few seconds; ranking supports takes under a second.
• compare_changes snapshots the build as XML, applies the edits, recalculates, diffs the stats and reloads the snapshot, so the loaded build is never changed.
• Stats depend on the build's Configuration tab (enemy type, conditions, charges…). Use get_config to see assumptions and set_config edits to change them.

Compatibility shims (bridge.lua)

• PoB's bundled LuaJIT accepts compound assignment (x += 1, s ..= t). Stock LuaJIT doesn't, so those lines are rewritten on load. Only files that fail to parse are touched.
• PoB's C lua-utf8 module is replaced with stdlib string functions (only used for thousands separators and text-box caret movement).
• Inflate/Deflate use Python's zlib.
• Nothing is written to stdout except MCP traffic; PoB's console output goes to stderr.

Passive tree routing

get_tree_map gives the agent the tree in a form it can reason about. Of the tree's ~2,900 nodes, the map keeps notables, keystones, jewel sockets, the class start and the small passives where paths branch (~970 points); every unbranched run of small passives becomes one edge with its length and stats:

50338 N Ballistics +5 | 20% increased Projectile Speed; 20% increased Projectile Damage; +20 to Dexterity
465 J Projectile Damage and Attack Speed +2 | 4% increased Attack Speed; 10% increased Projectile Damage
465-50338 3 | 3x 4% increased Attack Speed

The whole main tree is ~13k tokens with names only; a 10-point region around the current tree with full stats is ~7k. find_routes and allocate_path use the same pathing rules as PoB: no passing through class starts, no continuing out of a mastery, no crossing between the main tree and an ascendancy.

New builds without a level use PoB's auto-level mode, so the level (and level-based stats) follows the points allocated. Pass a level to new_build to plan at a fixed level.

How an agent creates a build

1. new_build with an ascendancy and level.
2. search_gems, then a create_socket_group edit with set_main for the main skill, plus groups for auras, movement and so on.
3. Gear: search_uniques + equip_unique, or search_item_bases + list_item_mods + create_rare with exact affixes, which guarantees an item that can exist (right mod pool, item level, 3 prefixes / 3 suffixes, one mod per group).
4. Ascendancy notables, keystones and must-have notables. For control over the route, look at the area with get_tree_map, compare options with find_routes, and allocate the chosen one with an allocate_path edit; allocate_node takes the shortest path.
5. auto_allocate_passives for the remaining points, then set_mastery (each costs a point).
6. get_warnings, then fix_gaps for resists and attributes.
7. Optionally plan_leveling, trade_search per slot and price_check for the uniques.
8. export_build for the share code, or save_to_pob.

auto_allocate_passives is greedy: it picks the best notable per point one step at a time, which is fast and usually good, but it doesn't plan long paths toward distant clusters. Guide it by allocating a few target notables first, or using avoid. A full tree takes 15–40 seconds; if it reaches its time limit, the progress is kept and calling it again continues.

Online features

trade_search, price_check, popular_builds, load_ladder_build and import_character use the internet; everything else runs offline.

• Prices come from poe.ninja. Responses are cached for 15 minutes, matching how often poe.ninja updates, and requests identify the app. poe.ninja asks that published apps route requests through their own backend; for personal use on your own machine this is that backend. Leave these tools unused if you'd rather not call poe.ninja.
• Trade searches are returned as links to open in your browser. pob-mcp doesn't query the trade site itself.
• Character import uses the same public profile pages as PoB's Import tab, so the profile's Characters tab must be public. Account names need their #1234 suffix.

Build-designer skill

skills/pob-build-designer/ is a Claude skill that teaches build making: picking a concept with enough power, scaling damage through the right buckets, layering defenses against community benchmarks, realistic gear, and spotting inflated PoB numbers. It drives the tools above step by step and reads game data live (list_ascendancy_notables, list_keystones, list_item_mods, ...) instead of hard-coding it. The knowledge is paraphrased from r/PathOfExileBuilds and r/pathofexile threads listed in references/sources.md.

The server also serves the guide itself, so any MCP client can use it: the read_build_guide tool returns SKILL.md or one reference section, the design_build and review_build prompts start a session with the method loaded, and each section is a pob-guide://<section> resource. Set POB_MCP_GUIDE=0 to switch this off.

Install it in Claude Code by copying the folder to ~/.claude/skills/ (or a project's .claude/skills/), or upload the packaged pob-build-designer.skill in the Claude app under Settings → Capabilities → Skills. evals/ holds two test briefs.

Benchmark: rebuilding real ladder trees

bench/tree_rebuild.py measures how well the optimiser rebuilds real characters. For each PoB build it records the original's main DPS and max hit per damage type, wipes the tree with reset_tree (keeping ascendancy, keystones, socketed jewels and the route to distance-scaling jewels such as Split Personality; gear, gems and config stay), and lets auto_allocate_passives spend the same points: maximise the DPS while reaching 98% of every original max hit, the original's spell suppression and block chances, and keeping mana, life and attribute requirements valid. Each strategy (targets-first, blend, slack, repair) is tried and the best feasible tree kept. Results are measured after a save and reload. A rebuild matches at ≥ 90% of the DPS with every max hit ≥ 95%.

python bench/tree_rebuild.py --pob-path ~/PathOfBuilding builds/*.xml --out results.json \
    --strategies slack,repair,targets-first --lns-rounds 20 --save-dir rebuilt/

Use load_ladder_build (or poe.ninja directly) to collect builds. On 19 random geared ladder characters (one per ascendancy, November 2026) the optimiser matches 17 and beats the original on 9. The two left (Gladiator 82%, Hierophant 85% of the DPS, both at every max-hit target) are trees where the defense targets compete with damage for the same few points. bench/results/README.md has the per-build numbers.

Testing

pip install -e ".[test]"
POB_PATH=/path/to/PathOfBuilding pytest            # offline tests (~1 min)
POB_PATH=/path/to/PathOfBuilding pytest -m online  # poe.ninja check

The suite drives PoB through every tool area using test builds that ship with PoB, plus one test that starts the real server over stdio. .github/workflows/test.yml runs it on every push and weekly against the latest PoB, so a league update that breaks something shows up quickly.

Limitations

• popular_builds reads poe.ninja's undocumented build API (protobuf search results and binary string dictionaries). It works against the site as of November 2026 and may need updating if poe.ninja changes its format; errors then say the format changed.

• PoE1 / PoB Community only (not PoB for PoE2).

• No character import from the PoE website (load a build code or XML instead).

• Timeless jewel seeds can't be set with the edit ops; edit them in PoB or paste the jewel with equip_item.

• create_rare with free-text mods only warns about mods that can't roll (or errors with strict); use affixes for guaranteed-valid items. Influence, veiled, fractured and essence mods aren't in the pool; one bench craft can be added with crafted.

• fix_gaps fills free suffixes on rare gear and cheap tree nodes; it doesn't replace existing mods or swap uniques.

• Weapon swap slots are hidden from list_item_slots.