Path of Building MCP Server

An MCP (Model Context Protocol) server that enables Claude to analyze, modify, and optimize Path of Building builds using PoB's actual calculation engine.

Uses an unmodified PathOfBuildingCommunity source tree with a compatible LuaJIT interpreter. The server ships its own stdio adapter that loads PoB's HeadlessWrapper.lua as a library and drives the calculation engine. It can also locate the engine and Lua modules from a supported macOS PoB installation. Some PoB revisions require a patched interpreter; see Lua bridge setup.

PoE 3.29 compatibility: This release targets Path of Building data and builds for the 3.29 league. Use a current PoB checkout for the matching tree, skills, and item data. Trade calls should always use get_leagues instead of hard-coding a challenge-league name.

☕ If you find this project helpful, consider buying me a coffee!

Features

Build Analysis (Always Available)

• List & Analyze Builds: Browse builds and extract stats, skills, items, passive trees, and notes from XML

• Compare Builds: Side-by-side build comparison

• File Watching: Real-time detection of builds saved from PoB with automatic cache invalidation

• Tree Analysis: Compare passive trees, find paths to nodes, and discover nearby notables from saved builds

High-Fidelity Calculations (Lua Bridge)

• Live Stats: Calculate stats using PoB's own engine; compare with the GUI using the same engine version, build, spec, item set, skill, and configuration

• Build Loading & Creation: Load existing builds or create new ones from scratch by class/ascendancy

• Passive Tree Editing: Set full tree allocation and see immediate stat recalculation

• Tree Specs: List, switch, create, copy, rename, and delete passive tree specs

• Node Search: Search the passive tree for nodes by name or stat text

• Character Level: Set level and watch all stats update accordingly

• Anointment Ranking: Simulate every anointable notable through PoB's live calculator and rank by DPS/EHP impact

Item & Skill Management (Lua Bridge)

• Items: Add items from PoE clipboard text, view all equipped gear

• Flasks: Toggle flasks active/inactive with immediate stat feedback

• Skills: Full gem management — create socket groups, add/remove/level/quality gems

• Batch Operations: setup_skill_with_gems and add_multiple_items for efficient workflows

Build Optimization

• Defensive Analysis: 3-layer framework (avoidance / mitigation / recovery) — evaluates EHP, spell suppression, armour/PDR, evasion, block, life regen, and leech

• Node Suggestions: Archetype-aware suggestions by goal (damage, life, ES, defense, resist)

• Passive Simulations: Rank passive upgrades and mastery choices by live stat impact

• Tree Optimization: Recommend nodes within reach of the current allocation

• Item Upgrade Analysis: Slot-by-slot upgrade recommendations based on live stats

• Shopping Specs: Describe bases and mods to look for based on the loaded build's gaps, without requiring the Trade API

• Skill Link Optimization: Detect missing "more" multipliers, penetration gaps, anti-synergies

• Budget Build Creation: Generate starter build plans with skill links, gearing strategy, and passive priorities

Build Validation

• Comprehensive Checks: Resistances, life pool, defensive layers, mana, flask immunities, accuracy, damage scaling

• Severity Classification: Critical / Warning / Info with actionable suggestions

• Dual Source: Uses Lua bridge stats when available, falls back to XML parsing

• Overall Score: 0–10 build health score for named saved builds

Configuration & Scenario Testing (Lua Bridge)

• Config State: View bandit, pantheon, enemy settings

• Toggle Conditions: Charges, buffs (Onslaught, Fortify, Leeching), boss mode

• Enemy Tuning: Set enemy level, resistances, armour, evasion for boss DPS testing

Skill Gem Analysis

• Archetype Detection: Classify builds (Elemental Bow Attack, Summoner, Critical Spell, etc.)

• Support Gem Recommendations: Ranked suggestions with DPS estimates and cost context

• Quality Validation: Identify missing quality, awakened upgrade paths, corruption targets

• Optimal Links: Auto-generate best support gem combinations for 4/5/6-link setups

• Budget Tiers: League-start, mid-league, and endgame recommendations

Build Export & Persistence

• Export: Copy builds to XML files with optional notes

• Save Tree: Write optimized passive tree back to an existing build file

• Snapshots: Versioned build history with tags, cached stat metadata, and a restore tool; restoring the active source also reloads the engine

Affix Data (No Lua Bridge Required)

• Affix Classification: Match explicit mod lines to prefixes, suffixes, and hybrid affixes

• Bench Crafts: Find crafts allowed for an item class and item level

• Affix Tiers: Look up roll ranges, required item levels, and base tags from PoB data

These tools need the corresponding data files from a PoB installation or checkout.

Currency & Market Data (poe.ninja)

• Exchange Rates: Real-time currency prices in Chaos Orb equivalent

• Arbitrage Detection: Find profitable currency trading loops

• Trade Profit Calculator: Evaluate custom trading chains

Trade API (Optional, POE_TRADE_ENABLED=true)

• Item Search: Search trade with stat filters, price range, link count

• Weighted BIS Search: Build-specific best-in-slot listings using PoB's native TradeQueryGenerator stat weights (requires POE_SESSION_ID)

• Price Checking: Min/max/median/average from recent listings

• Resistance Gear: Find affordable gear to cap resistances

• Cluster Jewels: Search trade listings by size, passives, and notables

• Shopping List: Generate a prioritized shopping list from build analysis

Related MCP server: pob2-mcp

Installation

Use Node.js 20 or later. CI runs on Node.js 20.

git clone https://github.com/ianderse/pob-mcp.git
cd pob-mcp
npm install
npm run build

Configuration

Claude Desktop Configuration

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

XML-Only (No Lua Bridge)

{
  "mcpServers": {
    "pob": {
      "command": "node",
      "args": ["/absolute/path/to/pob-mcp-server/build/index.js"],
      "env": {
        "POB_DIRECTORY": "/path/to/your/Path of Building/Builds"
      }
    }
  }
}

With the Lua Bridge

On macOS, supported PoB app locations and common builds directories are detected. The interpreter is a separate executable: POB_CMD defaults to luajit on PATH. Set it to an absolute path when needed, and ensure it supports your PoB revision.

{
  "mcpServers": {
    "pob": {
      "command": "node",
      "args": ["/absolute/path/to/pob-mcp-server/build/index.js"],
      "env": {
        "POB_LUA_ENABLED": "true",
        "POB_CMD": "/absolute/path/to/pob-compatible/luajit"
      }
    }
  }
}

For a checkout or a nonstandard engine location, also set POB_PATH in that env object. Override POB_DIRECTORY if your builds use another location:

{
  "POB_PATH": "/path/to/PathOfBuilding/src",
  "POB_DIRECTORY": "/path/to/your/Path of Building/Builds"
}

Environment Variables

Saving and restoring builds

lua_save_build writes atomically. Saving back to the file loaded into the bridge is allowed. To replace a different existing file, pass overwrite: true explicitly; otherwise choose a new name. Saved-file stats are invalidated immediately, and names with or without .xml share the same cache entry.

save_tree preserves unrelated XML elements and writes mastery selections in PoB's native format. Snapshot restore reloads the engine when that exact source file is active. If the reload fails, the response states that the file was restored but live stats are not yet synchronized. Another active build is left untouched.

Affix tools support both current Data/ModExplicit.lua and legacy Data/ModItem.lua installations. Unmatched or ambiguous explicit lines leave remaining slots unknown.

Setting Up the Lua Bridge

1. Locate the PoB engine

On macOS, the server recognizes Path of Building.app and PathOfBuilding.app in /Applications or ~/Applications. It prefers the app's writable engine under ~/Library/Application Support/PathOfBuildingMac/src, falling back to the bundle's Contents/Resources/src. It also uses the app's Lua modules.

For a checkout, clone PoB and set POB_PATH to its src/ directory:

git clone https://github.com/PathOfBuildingCommunity/PathOfBuilding.git
export POB_PATH="/absolute/path/to/PathOfBuilding/src"

With no detected app and no explicit path, the fallback is ~/Projects/PathOfBuilding/src. Set POB_DIRECTORY separately to your builds folder.

2. Choose a compatible LuaJIT interpreter

The server launches a command-line LuaJIT executable. It does not discover an interpreter inside the PoB app or bundle one with this repository.

For PoB revisions that use standard Lua syntax, system packages are sufficient:

# macOS
brew install luajit

# Ubuntu/Debian
sudo apt-get install luajit

Newer PoB sources can use compound assignment such as count += 1, which standard LuaJIT cannot parse. The revision recorded by this repo's item-format fixtures (ed354c2) uses that syntax in Modules/Main.lua. For those sources, supply a patched, PoB-compatible command-line interpreter and set POB_CMD to its path. This repository does not provide an installer for it. On Windows, a CLI executable is still required; PoB's lua51.dll alone is not a command-line interpreter.

Check the chosen interpreter against your engine before configuring the server:

export POB_CMD="/absolute/path/to/pob-compatible/luajit"
"$POB_CMD" -v
"$POB_CMD" -bl "$POB_PATH/Modules/Main.lua" > /dev/null

The second command only compiles the file. An error such as '=' expected near '+' means the interpreter cannot parse that PoB revision. Passing this check establishes syntax support; the smoke checks below exercise initialization and calculations. For a detected macOS app, use its resolved src/ path as POB_PATH in this check.

3. Supply Lua modules for a checkout

A recognized macOS app supplies its own Lua modules. A standalone checkout may need native modules built for the chosen interpreter and platform. PoB's bundled Windows DLLs cannot serve as macOS or Linux modules.

For example, install lua-utf8 locally with LuaRocks configured for your LuaJIT:

luarocks --lua-version=5.1 --lua-dir=/path/to/your/luajit-prefix --local install luautf8

The bridge searches the checkout's runtime/ and ~/.luarocks/lib/lua/5.1. Follow any missing-module diagnostic for additional dependencies. Windows checkouts can use the bundled DLLs with a compatible interpreter and architecture.

The adapter uses the upstream HeadlessWrapper.lua without changing PoB source. It runs over stdio in a separate headless process. Use lua_get_capabilities for the loaded bridge's action list.

4. Verify and configure your MCP client

After building this project, run:

npm run test:smoke

The smoke tests resolve the engine the same way the server does. They exercise the adapter and MCP stdio transport: discovery, capabilities, build loading, snapshots, stats, items, skills, reversible tree mutation, configuration, and anointment ranking. Some smoke helpers invoke luajit by name, including the adapter check in this suite. Make the compatible interpreter available as luajit on PATH as well as setting POB_CMD for the server.

The additional suites are:

For the authenticated weighted trade smoke, set your POE_SESSION_ID in the shell and run:

npm run test:smoke:weighted

This also requires a compatible PoB engine, interpreter, and network access.

Finally, update the Claude Desktop configuration above and restart Claude Desktop.

Available Tools

With POB_LUA_ENABLED=true, POE_TRADE_ENABLED=true, and POE_SESSION_ID set, the server advertises 104 tools. It advertises 39 with Lua and Trade disabled, and 95 with Lua enabled and Trade disabled. Tool discovery is not a guarantee that the required engine, data files, credentials, or network service are usable.

XML-Based Tools (Always Available)

Tree Analysis Tools (Always Available)

Affix Data (Always Advertised)

These tools read PoB data files without starting the Lua bridge. They require a PoB installation or checkout containing the relevant mod tables.

Lua Bridge — Core (Require POB_LUA_ENABLED=true)

lua_set_tree class IDs: 0=Scion, 1=Marauder, 2=Ranger, 3=Witch, 4=Duelist, 5=Templar, 6=Shadow

Witch ascendancy IDs: 1=Occultist, 2=Elementalist, 3=Necromancer

Use lua_save_build before reading live edits through saved-file tools such as analyze_build or get_build_stats. validate_build without build_name can check the current in-memory build directly.

Lua Bridge — Item & Skill Management

Common equipment slot names: Weapon 1, Weapon 2, Helmet, Body Armour, Gloves, Boots, Amulet, Ring 1, Ring 2, Belt, Flask 1–Flask 5. PoB versions and builds may expose additional slots such as Ring 3 and Graft 1/2. get_equipped_items reports equipped slot names; it omits empty slots. Skill groups use their own slot list in the tool schema.

Build Optimization (Always Advertised)

Lua Bridge — Diagnostics and Advice

These tools are advertised when POB_LUA_ENABLED=true. They do not require the Trade API. analyze_cluster_jewels reads saved XML; the other diagnostic tools use the loaded engine build. suggest_crafting can use an explicit base without a loaded build and fetches crafting/currency context from network services.

suggest_optimal_nodes goals: damage, defense, life, es, resist, speed

Defensive layers:

• Avoidance — evasion, spell suppression, dodge, block

• Mitigation — armour/PDR, endurance charges

• Recovery — life regen (≥1%/s), leech, ES recharge

A build with all 3 layers is considered exceptional.

Configuration & Enemy Settings

Build Validation

For a named saved build, returns critical issues, warnings, and recommendations with an overall 0–10 health score. Uses matching Lua stats when available and falls back to XML. Omitting build_name checks the currently loaded Lua build with a smaller set of live-stat checks; that path does not produce the full XML validation or its health score.

Skill Gem Analysis

gem_upgrade_path requires a loaded Lua bridge build. The other tools read a named saved build; their DPS estimates are heuristic rather than live simulations.

Budget tiers: league_start, mid_league, endgame

Build Export & Persistence

Snapshots are stored in POB_DIRECTORY/.pob-mcp/snapshots/. Their stat metadata comes from cached <PlayerStat> entries in the saved XML. Missing cached stats display as N/A. export_build_summary requires a loaded Lua bridge build.

Note: export_build copies from the XML file, not from the Lua bridge. Use lua_save_build first if you want to export in-memory changes.

Currency & Market Data (poe.ninja)

Rates are fetched on demand and cached for 5 minutes. Pass the exact league name returned by get_leagues when Trade is enabled, or use Standard explicitly.

Trade API Tools (Require POE_TRADE_ENABLED=true)

Typical Workflows

Analyze an existing build

1. lua_start
2. lua_load_build (build_name: "MyBuild.xml")
3. validate_build (build_name: "MyBuild.xml")
4. lua_get_stats (category: "offense")

For a fast live issue scan instead of full validation, use get_build_issues. Use analyze_defenses separately when you need the detailed defensive breakdown.

Build from scratch

1. lua_start
2. lua_new_build (class_name: "Witch", ascendancy: "Necromancer")
3. setup_skill_with_gems (label: "Skeletons", active_gem: "Summon Skeletons", support_gems: ["Minion Damage Support", "Melee Physical Damage Support"])
4. set_main_skill (group_index: the index returned by step 3)
5. lua_get_tree, then lua_set_tree with your complete connected node list and any mastery_effects
6. lua_get_stats (category: "offense")
7. lua_save_build (build_name: "MySummoner.xml")

Optimize passive tree

1. lua_load_build (build_name: "MyBuild.xml")
2. suggest_optimal_nodes (build_name: "MyBuild.xml", goal: "life", points_available: 5)
3. search_tree_nodes (query: "maximum life")
4. lua_get_tree   ← copy current node list
5. lua_set_tree   ← add new nodes to the list
6. lua_get_stats  ← verify improvement
7. lua_save_build (build_name: "MyBuild.xml") ← persist

Check reachability and point cost before applying a suggestion. Simulated stat gains alone do not establish a legal allocation.

Test DPS against Shaper

1. lua_load_build (build_name: "MyBuild.xml")
2. set_enemy_stats (level: 84, fire_resist: 40, cold_resist: 40, lightning_resist: 40)
3. set_config (config_name: "enemyIsBoss", value: "Pinnacle")
4. lua_get_stats (category: "offense")

enemyIsBoss is a dropdown value, not a boolean. The bridge also maps the legacy name "Shaper" to "Pinnacle". Check whether configuration writes were accepted before interpreting the stats.

Find the best anointment and shop for upgrades

1. lua_load_build (build_name: "MyBuild.xml")
2. find_best_anointment (slot: "Amulet", focus: "both")
3. find_weighted_trade_items (league: "Standard", slot: "Amulet")   ← requires POE_TRADE_ENABLED + POE_SESSION_ID

Troubleshooting

XML Features

No builds found

• Verify POB_DIRECTORY is correct and contains .xml files

• Check file permissions

Parse errors

• Open the build in PoB GUI to verify it isn't corrupted

• Ensure PoB is up to date

Lua Bridge

luajit command not found Set POB_CMD to the absolute path of a compatible command-line LuaJIT executable. Check the interpreter requirements before using a system package; some PoB revisions require patched syntax support.

'=' expected near '+' (or another compound-assignment operator) The interpreter cannot parse the chosen PoB source. Increasing the timeout or installing a Lua module will not add syntax support. Use a compatible interpreter and verify it with the compile-only command in the setup section.

Failed to find valid ready banner POB_PATH must point to the directory containing HeadlessWrapper.lua:

ls "$POB_PATH/HeadlessWrapper.lua"   # must exist
ls "$POB_PATH/Modules/"              # must exist

Timed out waiting for response

• If startup is slow, increase POB_TIMEOUT_MS above its default (try 60000).

• Check the server's stderr for missing-module or syntax errors.

• Run npm run test:smoke:truthfulness to exercise the repo-owned adapter against the resolved engine using POB_CMD. Run commands from this project's directory.

Stats don't match PoB GUI

• Check bandit/pantheon/enemy settings with get_config

• Ensure the correct tree spec is active in the XML

• Make sure your PathOfBuilding checkout is up to date

Bridge becomes unresponsive

lua_stop → wait a moment → lua_start

If still unresponsive, restart Claude Desktop.

Nodes dropped after lua_set_tree Nodes must form a valid connected path from the class starting node. Disconnected nodes are silently dropped by PoB. Ensure all intermediate nodes are included.

Development

npm run build   # compile TypeScript
npm run dev     # watch mode

Path of Building XML Structure

PoB builds are XML files with:

• <Build>: Character info and stats

• <Tree>: Passive skill tree node allocations

• <Skills>: Socket groups and gem links

• <Items>: Equipped items

• <Notes>: Build notes

Contributing

Issues and pull requests are welcome!

Contributors

License

GPL-3.0