pob-mcp 0.3.1

MCP server giving AI agents real programmatic control of Path of Building Community (Path of Exile 1)

pob-mcp

Give any AI assistant real, verifiable control of Path of Building.

For Path of Exile 1, via Path of Building Community.

Paste a build link. Get a slot-by-slot upgrade analysis where every single number came out of Path of Building's own calculation engine — not a language model's guesswork.

---

The problem

Ask any AI about your Path of Exile build and it will confidently invent numbers. It has read a lot of forum posts, so the answers sound right — "that's about 40% more DPS" — but nothing was calculated. There's no way to tell a good answer from a plausible-looking wrong one.

pob-mcp removes the guessing. It runs a real, unmodified Path of Building headlessly and lets the assistant drive it. When it says a swap is worth +8,722,100 DPS, that figure came from the same engine as PoB's own item tooltips, and you can paste the resulting build into the desktop GUI to check it yourself.

The project has exactly one rule, and everything else follows from it:

Never fabricate a number. If a stat didn't come out of a real PoB calculation, it doesn't get reported. "Not computed" beats a confident guess.

---

What it looks like

You: Load https://pobb.in/xcACDMM2fFR6 and tell me what's actually holding this build back.

Trickster (Shadow), level 94 — Reap mines, tree 3_29

  Combined DPS   59,549,948        Life  3,708 (2,432 unreserved)
  Total EHP          24,247        ES    2,011      Evasion  50,859
  Resists     F 75 (+15)  C 80 (+58)  L 75 (+3)  Chaos 38
  Spell Suppression 97%             Block 25%

  _meta: enemy Pinnacle lvl 84 · Frenzy charges ON · Power charges ON

You: Is that DPS honest, or is it assuming perfect conditions?

pob_config_sensitivity()  →  what the headline number depends on

  useFrenzyCharges  ON → OFF      DPS −24,357,212      EHP    −208
  enemyIsBoss       Pinnacle→None DPS +15,659,402      EHP −12,962
  usePowerCharges   ON → OFF      DPS −12,678,059      EHP       0

41% of this build's advertised DPS evaporates without Frenzy charges. That's the kind of thing a headline number hides, and it's the first thing worth knowing.

(The same conversation can rank every support gem's measured contribution — on this build, levelling the active gem turns out to be worth six times the best support upgrade. Every figure is a real calculation with that gem removed or levelled.)

You: Find me upgrades — and tell me what gets worse, not just what improves.

pob_find_upgrades()  →  1,478 real calculations in 6.0s, 0 failed
                        ranked by combined score, verbatim output

   1. Flask    Replica Rumi's Concoction   DPS          +0    EHP  +17,900
   2. Flask    Vorana's Preparation        DPS  +6,616,661    EHP   +1,093
   3. Boots    Legacy of Fury              DPS  +8,722,100    EHP     −972
   4. Ring 2   Kalandra's Touch            DPS  +6,287,099    EHP     −131
   5. Flask    Progenesis                  DPS          +0    EHP   +4,426
   6. Flask    Starlight Chalice           DPS  +3,783,608    EHP   +1,093
   7. Flask    Rumi's Concoction           DPS          +0    EHP   +3,965
   8. Ring 2   The Taming                  DPS  +4,783,763    EHP     −131
   9. Weapon 2 Replica Mistwall            DPS −13,316,941    EHP  +14,330
  10. Belt     The Arkhon's Tools          DPS +14,607,821    EHP   −8,841

Look at rows 9 and 10. The Arkhon's Tools is the single biggest DPS gain in the run — and it costs 8,841 EHP. Replica Mistwall is the mirror image: a third of your damage traded away for a third more effective health. Neither is "the answer"; both are decisions, and you can only make them if the cost is on the table.

That's why the top of the list is a flask that adds no damage whatsoever. The ranking weighs offence and defence together rather than sorting by DPS and hoping you notice the footnotes.

---

Why this and not a chatbot

	Asking an AI directly	pob-mcp
Where numbers come from	The model's training data	Path of Building's calc engine
Can you verify a claim?	No	Yes — pob_export() → paste into the GUI
Knows your gear and tree	Only what you paste	Loads your actual build
Handles your league's tree	Assumes whatever it saw	Uses the build's own tree version
Defensive trade-offs	Usually ignored	Reported on every recommendation
Hidden assumptions	Invisible	Surfaced by pob_config_sensitivity()

---

Install

The only thing you need first is Path of Building Community itself — download the latest if you don't have it. Installer or portable zip, either works. (If you play Path of Exile, you already have it.)

No Python, no clone, no build step, and on Windows nothing else at all — pob-mcp ships its own copy of everything else it needs.

1. Add it to your AI client — pick your route

Claude Desktop or Cowork — download one file Grab the .mcpb bundle (e.g. pob-mcp-0.3.0.mcpb) from the latest release, then in Claude: Settings → Extensions → Advanced settings → Extension Developer → select the file That's it. A settings form appears where you can point it at your Path of Building folder, but leave it blank — it finds your install automatically.

Claude Code, Cursor, Zed, Continue… — one command claude mcp add pob --scope user -- uvx pob-mcp Needs the free uv tool (itself a one-command install) — it fetches everything else, Python included. That's it on Windows. On Linux/macOS there are two extra steps — see the Linux / macOS notes below. JSON-config form for other clients below.

2. Try it

Whichever route you took, start a new session — registration doesn't affect one already running — and ask:

Load https://pobb.in/xcACDMM2fFR6 and give me the headline DPS and EHP.

You should get about 59.5M Combined DPS and 24,247 EHP. Done. (The first call takes a few seconds while Path of Building loads its data; after that, calculations are fast. If anything looks wrong, ask it to "run pob_status" — that reports exactly what was found and what wasn't.)

Command-line clients in detail

Claude Code — one command. uv fetches the server, its dependencies and a Python runtime on first run:

claude mcp add pob --scope user -- uvx pob-mcp

Cursor, Zed, Continue, or any other MCP client — add this to its MCP config. (Claude Desktop works this way too, but the .mcpb extension above is easier and is the only route that also covers Cowork.)

{
  "mcpServers": {
    "pob": {
      "command": "uvx",
      "args": ["pob-mcp"]
    }
  }
}

Don't have uv? Install it — one command on every platform — or use the pip route below.

Prefer pip?

pip install pob-mcp
claude mcp add pob --scope user -- pob-mcp

Needs Python 3.10+ already installed. uvx is the easier route mainly because it supplies Python itself and keeps the install isolated.

"LuaJIT not found"

On Windows you shouldn't see this at all — both the .mcpb extension and the PyPI package ship their own copy of LuaJIT. If you do see it, or you're on Linux/macOS where LuaJIT comes from your package manager:

1. Install it: winget install DEVCOM.LuaJIT / brew install luajit / sudo apt install luajit, then restart your MCP client (not just the terminal — clients keep the PATH they started with).
2. Or point at a specific binary:

   claude mcp add pob --scope user -e POB_LUAJIT="C:\path\to\luajit.exe" -- uvx pob-mcp
   

3. Or drop a luajit binary at ~/.pob-mcp/luajit/ and it will be found with no configuration at all.

"Path of Building not found" — tell it where yours is

pob-mcp searches the usual install locations and any folder named Path of Building*. If yours is somewhere unusual, say so. POB_SRC is the folder containing Launch.lua:

claude mcp add pob --scope user -e POB_SRC="D:\Games\Path of Building Community" -- uvx pob-mcp

The error message lists every location it checked.

Linux / macOS — one extra build step

Path of Building only ships a Windows build of the small lua-utf8 native module, so compile it once (upstream PoB's own test suite does the same):

git clone --depth 1 https://github.com/starwing/luautf8.git /tmp/luautf8
mkdir -p ~/.pob-mcp/lib
gcc -O2 -fPIC -shared $(pkg-config --cflags luajit) \
    /tmp/luautf8/lutf8lib.c -o ~/.pob-mcp/lib/lua-utf8.so

Then register with the extra paths — MCP clients don't inherit your shell:

claude mcp add pob --scope user \
  -e POB_ZLIB=/lib/x86_64-linux-gnu/libz.so.1 \
  -e POB_LUA_CPATH="$HOME/.pob-mcp/lib" \
  -e POB_SRC="/path/to/your/PathOfBuilding" \
  -- uvx pob-mcp

Can't find zlib? ldconfig -p | grep libz. Running PoB under Wine works too.

Linux is tested and covered by CI. macOS should work identically but nobody has confirmed it — reports welcome.

All settings — every option is optional

Variable	What it's for
POB_SRC	Your Path of Building folder (the one with Launch.lua). Set if auto-detection fails.
POB_LUAJIT	Path to the luajit executable. Overrides the bundled copy and PATH lookup.
POB_BUILDS	Your PoB Builds folder, if the auto-detected one is wrong
POB_ZLIB	Path to zlib. Automatic on Windows; required on Linux/macOS.
POB_LUA_CPATH	Extra directories to search for native Lua modules
POB_MCP_CACHE	Where fetched builds are cached. Default ~/.pob-mcp/cache, 1-hour TTL.
POB_MCP_TIMEOUT	Seconds before a call gives up. Default 180; the slow analysis tools always get at least 600.
POB_MCP_USER_AGENT	Override the User-Agent sent when fetching builds from share sites

Full walkthrough and every error explained: docs/SETUP.md.

pob-mcp is strictly additive. It reads PoB's own files and injects what it needs at runtime — it never writes into your installation, and CI proves the folder is byte-identical after a full test run.

Path of Building itself writes Data/TimelessJewelData/*.bin caches on first use, exactly as the desktop app does. That's upstream behaviour, not ours.

Using it

Just talk normally — there's no syntax to learn and no need to name the tools. Paste a build link and ask. The assistant picks the right calls itself.

Start here

Load https://pobb.in/YOUR_BUILD and give me a health check.

That gets you the headline numbers, and it's the fastest way to confirm everything is wired up.

Want the whole review in one go? The server ships a review_build prompt — in clients that support MCP prompts it shows up as a slash command (type / and look for review_build) and runs the full workflow: honest-numbers check first, then gems, tree, upgrades, trade links, and a share code to verify. The four questions it automates are worth knowing on their own:

The four questions worth asking

1. Are my numbers honest?

Is my DPS assuming perfect conditions? What does it depend on?

Most build exports quietly assume full charges and a specific enemy. On the example build above, 41% of the advertised DPS disappears without Frenzy charges. Ask this first — it changes how you read everything else.

2. What should I upgrade?

What are my best upgrades? Rank them by measured delta, and tell me what gets worse, not just what improves.

Searches every unique that fits, ranked by real calculation. The "what gets worse" phrasing matters — it's how you find the +14.6M DPS belt that costs you 8,841 EHP, instead of being told it's simply "the best".

3. What's dead weight?

Which support gem in my main link contributes least? Any allocated tree nodes doing nothing?

Frequently finds a gem worth less than levelling your active skill, or passives you pathed through and forgot.

4. What do I actually buy?

Generate a trade search for better boots for this build.

Weights the search by your build's calculated mod values and anchors the minimums to what you're already wearing.

Try things before committing to them

What if I swapped Legacy of Fury in, dropped Increased Critical Damage for Elemental Focus, and took the two nodes near Flash Freeze? Show me the deltas.

Batch what-ifs are the workhorse. Nothing changes until you say so, and pob_reset() puts everything back.

The one habit worth forming

Export that and give me the share code.

Paste it into desktop Path of Building and check the number yourself. The whole design assumes you'll want to — and if the GUI ever disagrees with what you were told, that's a bug worth reporting.

If a recommendation looks wrong

Two things catch most surprises:

• Wrong main skill. Exports are often saved with a utility skill selected (an item-granted effect, a curse, a movement skill), which zeroes the damage numbers. Ask "what's my main socket group?" — and if it's wrong, "set my main skill to X".
• Zero delta isn't the same as useless. Stun thresholds, ailment immunity and flask masteries don't show up in DPS or EHP. A change measuring 0/0 may still be doing something the metrics can't see.

---

Common questions

Does this work with any AI model, or just Claude?

Any client that speaks MCP. The server is a plain stdio MCP server — Claude Code, Claude Desktop, Cursor, Zed, Continue, and anything else implementing the protocol. The command is the same everywhere; the JSON-config form is in the install section above.

One honest caveat: the numbers are identical whatever model you use, because Path of Building computes them. The model only affects the quality of the reasoning wrapped around those numbers — which combinations it thinks to try, and how well it explains the trade-offs.

Do I need an account, API key, or login?

No. None. No sign-up, no API key, no OAuth, no telemetry. The server runs locally as a subprocess and talks to your client over stdin/stdout.

It makes exactly two kinds of outbound request, neither authenticated:

• Fetching a build you asked for, from a supported share site (pobb.in, pob.codes, Maxroll, poe.ninja, pastebin, pastebinp, rentry, poedb.tw), via their public read endpoints — cached on disk for an hour, with a descriptive User-Agent as pobb.in's API docs request.
• The current league name, once a day, from GGG's public api.pathofexile.com/leagues endpoint.

It never touches the unofficial trade search API, never sends your build anywhere, and works fully offline if you hand it a local XML file.

Is it safe to point at my real Path of Building?

Yes. pob-mcp is strictly additive — it loads PoB's own files and injects what it needs at runtime. It never writes to your installation, and CI asserts the PoB directory is byte-for-byte unchanged after a full test run.

(PoB itself writes Data/TimelessJewelData/*.bin decompression caches on first use, exactly as the desktop app does. That's upstream behaviour, not ours.)

---

The 17 tools

Loading and reading

Tool	What it does	Read-only
pob_load_build(source)	Build link (pobb.in, pob.codes, Maxroll, poe.ninja, pastebin, pastebinp, rentry, poedb.tw — the same sites PoB's import box accepts), share code, XML file, raw XML — or the name of a build saved in your own PoB	—
pob_list_builds()	The builds saved in your own PoB, any of which loads by name	✓
pob_get_stats(sections?)	Computed stats — offence, defence, resistances, charges, attributes	✓
pob_get_build_detail(section)	Items by slot, skill groups and links, allocated tree, config flags	✓
pob_status()	Health check: which PoB, LuaJIT and build are in use — works with nothing loaded	✓

Changing things

Tool	What it does	Read-only
pob_simulate(scenarios)	The workhorse. Batch what-ifs — items, gems, tree nodes, config, flasks — without committing. Returns every changed stat with better/worse semantics.	✓
pob_apply(changes)	Commit changes to the session	—
pob_reset()	Restore the build as loaded	—
pob_export()	Share code for the current state — paste into the GUI to verify	✓

Analysis

Tool	What it does	Read-only
pob_find_upgrades(slot?)	Every unique that fits, ranked by measured delta, defensive cost attached	✓
pob_anoint()	Every anointable notable enchanted onto your amulet, ranked by real delta, oil recipe attached	✓
pob_watchers_eye()	Watcher's Eye mods for your active auras, each simulated in your jewel socket	✓
pob_analyze_gems()	Per-support contribution, and +1 level / +quality upside	✓
pob_analyze_tree()	Weakest allocated nodes, best adjacent pickups, mastery-choice check, per-jewel contribution	✓
pob_config_sensitivity()	Which assumptions the headline numbers secretly rest on	✓
pob_search_nodes(keyword)	Search the build's own passive tree version	✓
pob_trade_links(...)	Weighted trade searches and direct unique/gem links	✓

Every tool carries honest MCP annotations, so clients can bulk-approve the read-only set instead of prompting on every call. Nothing here is destructive — "not read-only" means it changes the in-memory session, which pob_reset() undoes. Only pob_load_build and pob_trade_links ever touch the network. There's also one MCP prompt, review_build, which packages the whole workflow.

Every numeric response carries _meta — PoB version, tree version, main skill, charge and boss configuration. Numbers without their assumptions are a trap.

Trade links that mean something

pob_trade_links() doesn't just search for an item name. For an equipment slot it drives Path of Building's own Trade Query Generator: every candidate mod is scored through your build's real calculator, and the search minimums are anchored to the item you're already wearing — so results should actually beat what you have.

pob_trade_links(slots=["Gloves"])

  league        Allflame   (example — the current league is auto-detected, 24h cache)
  stat weights  CombinedDPS ×1.0 · TotalEHP ×0.5   (override with stat_weights)
  → https://www.pathofexile.com/trade/search/…?q=…

Want a purely defensive search? stat_weights=[{"stat":"TotalEHP","weight":1.0}].

This builds URLs only. It opens nothing, buys nothing, and never queries the unofficial trade API — you click the link and shop yourself.

---

Accuracy, stated honestly

Simulation deltas run through calcs.getMiscCalculator — the same machinery behind PoB's own item-hover tooltips. That's the engine; pob-mcp only drives it.

• Verified against external ground truth. The primary test build reproduces 91 of 91 stats that its author's desktop GUI embedded in the export — resistances, EHP, and 59,549,948 Combined DPS — and this one is enforced by the test suite (agreement within 0.5%; in practice the figures match exactly). Two older-league minion builds were additionally measured by hand at 76/87 and 70/85, every mismatch consistent with cross-league balance changes; those two figures are a one-off measurement, not a standing assertion.
• Your numbers come from your Path of Building. Whatever version you have installed is the version used, and every response reports it in _meta, so a figure is never ambiguous about which PoB produced it. The published examples above were measured on 2.66.2.
• High confidence for anything the 85 tests cover.
• Medium confidence for exotic archetypes outside the test corpus — self-trigger loops, aura stacking. Simulation state restoration had one nasty class of bug (cross-gem srcInstance writes) caught only because a test spotted a 12.4M discrepancy. Comparable latent cases may exist.
• When it matters, check it. pob_export() then import into the GUI. That path is deliberately first-class.

Known limits

• Keystone and ascendancy removal can't be measured — PoB's quick calculator silently ignores it, and the GUI's own hover has the same blind spot. We exclude those from rankings rather than report a misleading zero.
• No prices or availability. Upgrade results are numeric, not shopping advice.
• Jewels that rewrite tree nodes (timeless jewels and kin) are reported "not computed" in the jewel scan rather than guessed. Ordinary masteries and jewels are auto-evaluated by pob_analyze_tree().
• Unmet attribute requirements are flagged, not priced in. PoB computes every number as if the gear were wearable; results that would break your Str/Dex/Int carry an attrWarning saying exactly what's missing.
• A zero DPS/EHP delta doesn't mean useless — stun tech, ailment immunity and flask masteries are invisible to those two metrics.
• No live GUI sync. Headless by design.

---

Tests

You don't need these to use pob-mcp — they're here so you can check the claims above rather than take them on trust. From a clone of this repo:

python -m pytest tests/

85 tests, about a minute:

• unit — share-code decode, URL parsing, tool registration, saved-build name resolution (incl. path-traversal attempts)
• external truth — a real build's GUI-exported stats, reproduced 91/91
• regression — 7 archetypes incl. two minion builds, pinned to one PoB version; anoint, Watcher's Eye, mastery/jewel analysis and attribute warnings against real calcs
• adversarial — corrupt XML, dead links, bogus slots, killing the engine mid-session
• trade — link construction and the PoB-driven weighted query generator

CI runs the suite on Ubuntu and Windows, against both PoB layouts on each, and asserts the Path of Building directory is unmodified afterwards.

---

Credits

This project is a thin layer on other people's excellent work. It would not exist without any of the following, and I'm grateful to all of them.

Path of Building Community

@PathOfBuildingCommunity — everything here is a remote control for their calculation engine. Years of meticulous, unglamorous work reverse-engineering and maintaining Path of Exile's damage formulas. Every number pob-mcp reports is theirs; the hard part was already done. Originally created by Openarl, and carried forward since by the community fork's maintainers and contributors. MIT licensed.

If you find this tool useful, go star Path of Building and consider contributing there — it helps far more players than this ever will.

The headless API groundwork

@ianderse — author of PR #9505, "Add headless JSON-RPC API for programmatic PoB access", and of ianderse/pob-mcp. pob_mcp/bridge/pob_ops.lua is adapted directly from that PR's BuildOps.lua (MIT, unchanged apart from an attribution header). He worked out the build-operation layer first; this project started from it rather than reinventing it.

Please go support PR #9505. A merged upstream headless API would benefit every tool in this space, and it's been open a long time.

(Note on licensing: ianderse also maintains a pob-mcp repository under GPL-3. This project takes only the MIT-licensed upstream PR #9505, not that repository. NOTICE.md sets out exactly what the two codebases share, how that was measured, and a correction to an earlier claim that was measured wrongly.)

Everyone else

• @Dav1dde — pobb.in / pasteofexile, where most build links live, and one of the few community services with a properly documented public API. Build loading leans on it.
• Mike Pall — LuaJIT, which runs the whole engine, fast.
• @starwing — luautf8, the native module PoB needs and that Linux/macOS users build from source.
• @atty303 — pob-web runs unmodified PoB in the browser via WebAssembly. Studying how it hosts PoB without forking it shaped this project's "never modify the install" approach.
• @brather1ng and the RePoE maintainers — game data extraction the whole third-party ecosystem depends on.
• Grinding Gear Games — for Path of Exile, and for tolerating a rich third-party tool ecosystem around it.

Disclaimer

This product isn't affiliated with or endorsed by Grinding Gear Games in any way.

Path of Exile is a trademark of Grinding Gear Games.

---

Contributing

Bug reports, archetype coverage, and macOS confirmation are all genuinely useful. Please read CONTRIBUTING.md first — especially the "never fabricate a number" rule, which is enforced in review.

Further reading: docs/SETUP.md · docs/ARCHITECTURE.md · docs/pob-internals.md · docs/DECISIONS.md · docs/KNOWN_UNKNOWNS.md

Licence

MIT — see LICENSE. Third-party notices in NOTICE.md.