Path of Building MCP Server — PoE2

An MCP (Model Context Protocol) server that enables Claude to analyze, modify, and optimize Path of Exile 2 builds using Path of Building's actual calculation engine, via the PathOfBuilding-PoE2 fork.

It is a port of pob-mcp (PoE1) to PoE2. The high-fidelity calculation half is driven by a headless luajit process running an api-stdio JSON bridge that was ported onto the PoE2 PoB codebase (PathOfBuilding-PoE2/src/API/ + HeadlessWrapper.lua hooks).

⚠️ MVP / port status

The Lua bridge foundation is ported and verified working against the PoE2 engine (ping, new build, tree get/set, live stat calc incl. Spirit, item/skill/config ops, what-if calc). The TypeScript server is a copy of the PoE1 server with PoE2-aware bridge wiring.

Validated for PoE2: the lua_* engine tools (stats, tree, items, skills, config, level), and XML build analysis (PoE2 uses the same PoB XML schema).

PoE2-native additions: list_gems queries Path of Building's own PoE2 gem database (skill + support gems, tags, gem family, requirements, max level) — use it for accurate gem info instead of the legacy heuristics below.

Engine-backed PoE2 tools to prefer: analyze_skills, suggest_supports (incl. measure_dps), list_gems, get_classes — all sourced from the PoB2 engine. The defensive analyzer and validate_build have been retuned for PoE2 mechanics (evade/block/deflect, Spirit, charms; no spell suppression).

poe.ninja currency tools are ported to the PoE2 economy endpoint and on by default (POE_NINJA_DISABLED=true to hide).

Disabled by default (PoE1-shaped, opt-in): the legacy skill-gem tools (analyze_skill_links, suggest_support_gems, find_optimal_links, validate_gem_quality, compare_gem_setups, gem_upgrade_path) — POB_LEGACY_GEM_TOOLS=true; Trade API — POE_TRADE_ENABLED=true (PoE2 trade2 endpoints; see below). Class/ascendancy ID tables in some descriptions and bandit/pantheon config (absent in PoE2) are PoE1 remnants.

PoE2 engine differences already handled in the bridge: PassiveSpec:ImportFromNodeList signature (extra className / weaponSets params), generic config passthrough (no bandit/pantheon), flask-slot validation against the actual item set, Spirit in default stat export, and stdout reserved for the JSON protocol (PoB logging redirected to stderr).

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, discover nearby notables, what-if allocation testing

High-Fidelity Calculations (Lua Bridge)

• Live Stats: Accurate stat calculation using PoB's own engine — identical to what PoB GUI shows

• 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

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

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

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 (Lua Bridge)

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

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

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

• 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

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, stat metadata, and one-click rollback

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

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

• Upgrade Finder: Identify best item upgrade candidates for your build

• Resistance Gear: Find affordable gear to cap resistances

• Cluster Jewels: Search and analyze cluster jewel setups

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

Related MCP server: codex-cli-mcp-tool

Installation

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"
      }
    }
  }
}

Full Configuration (With 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",
        "POB_LUA_ENABLED": "true",
        "POB_FORK_PATH": "/path/to/PathOfBuilding/src",
        "POB_CMD": "/usr/local/bin/luajit",
        "POB_TIMEOUT_MS": "10000"
      }
    }
  }
}

Environment Variables

Setting Up the Lua Bridge

The Lua bridge uses PoB's actual calculation engine for accurate stats.

1. Install LuaJIT

# macOS
brew install luajit

# Ubuntu/Debian
sudo apt-get install luajit

# Windows: download from https://luajit.org/ and add to PATH

2. Get the PoE2 PoB fork with the api-stdio bridge

This repo's sibling PathOfBuilding-PoE2/ already contains the ported api-stdio bridge (src/API/{Server,Handlers,BuildOps}.lua, src/utf8.lua, and the POB_API_STDIO hooks in src/HeadlessWrapper.lua). Point POB_FORK_PATH at its src/ directory.

If you are setting this up from a clean upstream clone instead, copy those src/API/ files and src/utf8.lua over, and apply the POB_API_STDIO block from src/HeadlessWrapper.lua (which also redirects PoB logging to stderr so stdout stays pure JSON).

3. Verify

luajit -v
ls /path/to/PathOfBuilding/src/HeadlessWrapper.lua

4. Update Claude Desktop config and restart Claude Desktop

Available Tools

The server registers 91 tools across 10 categories.

XML-Based Tools (Always Available)

Tree Analysis Tools (Always Available)

Lua Bridge — Core (Require POB_LUA_ENABLED=true)

lua_set_tree class IDs (PoE2): 1=Witch, 2=Ranger, 6=Warrior, 7=Sorceress, 8=Huntress, 9=Mercenary, 10=Monk, 11=Druid. Call get_classes for the live list (classes/ascendancies can change between PoE2 patches).

Ascendancy IDs (PoE2) — per class, e.g. Witch: 1=Infernalist, 2=Blood Mage, 3=Lich, 4=Abyssal Lich; Monk: 1=Martial Artist, 2=Invoker, 3=Acolyte of Chayula. Use get_classes for the full, current mapping.

lua_save_build is required before using file-based tools (validate_build, analyze_build, etc.) on an in-memory build.

Lua Bridge — Item & Skill Management

Slot names: Weapon 1, Weapon 2, Helmet, Body Armour, Gloves, Boots, Amulet, Ring 1, Ring 2, Belt, Flask 1–Flask 5

Lua Bridge — Build Optimization

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

Returns critical issues, warnings, and info with actionable suggestions and an overall 0–10 health score. Uses Lua bridge stats when available; falls back to XML parsing. build_name is optional — omitting it validates the currently loaded Lua bridge build.

Skill Gem Analysis (PoE2, engine-backed — preferred)

Legacy PoE1 gem tools (not registered by default)

analyze_skill_links, suggest_support_gems, validate_gem_quality, compare_gem_setups, find_optimal_links, gem_upgrade_path use a hand-coded PoE1 gem DB / archetype templates and a 6-link + Awakened-gem model that does not match PoE2. They are disabled by default; set POB_LEGACY_GEM_TOOLS=true to expose them. Prefer the engine-backed tools above.

Build Export & Persistence

Snapshots are stored in POB_DIRECTORY/.pob-mcp/snapshots/.

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)

Sourced from the PoE2 poe.ninja economy endpoint (/poe2/api/economy/exchange/current/overview?league=<League>&type=Currency), cached 5 min. Live-verified. Pass the exact, case-sensitive PoE2 league name (e.g., Runes of Aldur, Standard). Values are in Exalted Orb equivalent (PoE2's base currency), not Chaos.

Note: the PoE2 currency-exchange feed exposes a single value per currency (no separate buy/sell spread), so find_arbitrage generally returns nothing — round-trips evaluate to ~0% profit. get_currency_rates and calculate_trading_profit are the useful tools here.

Trade API Tools (Require POE_TRADE_ENABLED=true)

Ported to the PoE2 trade2 endpoints (https://www.pathofexile.com/api/trade2). Stat IDs and leagues are fetched from this base, so the stat mapper picks up PoE2 trade stats automatically.

Heads up: the official trade API is behind Cloudflare and most endpoints require a logged-in session — set POE_SESSION_ID to your POESESSID cookie. It is also strictly rate-limited. Verified working server-side (search→fetch through Cloudflare with only POE_SESSION_ID set). Note POESESSID expires periodically; refresh it if you start getting 401/403s.

Typical Workflows

Analyze an existing build

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

Build from scratch

1. lua_start
2. lua_new_build (class_name: "Witch", ascendancy: "Necromancer")
3. setup_skill_with_gems (active_gem: "Summon Skeletons", support_gems: [...])
4. lua_set_tree (nodes: [...])
5. lua_get_stats
6. lua_save_build (build_name: "MySummoner.xml")

Optimize passive tree

1. lua_load_build (build_name: "MyBuild.xml")
2. suggest_optimal_nodes (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 ← persist

Test DPS against Shaper

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

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

brew install luajit          # macOS
sudo apt-get install luajit  # Ubuntu/Debian

Or set POB_CMD to the full path (e.g., /opt/homebrew/bin/luajit).

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

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

Timed out waiting for response

• Increase POB_TIMEOUT_MS (try 20000)

• Test manually: cd "$POB_FORK_PATH" && luajit HeadlessWrapper.lua

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 fork is on the api-stdio branch and 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.

lua_save_build doesn't persist gem changes Gem modifications made via add_gem, set_gem_level, set_gem_quality are currently held in Lua memory and are not serialized back to the XML on save. This is a known limitation.

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