POB-MCP

by juddisjudd

Not rated
GitHub

About

Load, inspect, and optimize Path of Exile 2 builds using Path of Building's real calculation engine.

Details

Author
juddisjudd
Categories
Other

Setup

Install POB-MCP in your MCP client (Claude Desktop, Cursor, Windsurf, and others).

Repository: https://github.com/juddisjudd/pob-mcp

Follow the installation instructions in the repository README, then restart your MCP client.

pob-mcp is an MCP server. It lets an LLM load, inspect, change, and improvePath of Exile 2builds. It uses the real calculation engine fromPath of Building Community (PoE2 fork). It does not reimplement that engine.

pob-mcp runs a real, headless copy of PoB (a Lua program) as a background process. It talks to that process over a small JSON-RPC protocol. Every stat you get back is a number PoB itself calculated.

MCP client (Claude Desktop, Cursor, ...) | MCP over stdio v pob-mcp (Python) -- tools_.py, optimizer/ | JSON-RPC over stdio v lua/pob_bridge.lua (running under luajit) | dofile() v Path of Building - PoE2's own Lua source (Launch.lua, Main.lua, ...)

lua/pob_bridge.luais a fork of PoB's ownsrc/HeadlessWrapper.lua, which PoB uses for its test suite. pob-mcp does not depend on that file directly. Installed copies of PoB leaveHeadlessWrapper.luaout (seemanifest.cfg), so pob-mcp brings its own version instead. This means pob-mcp works the same way against a git checkout of PathOfBuilding-PoE2 and against an installed release build.
- A way to install a Python package.We recommend
uv— it's the fastest path and what the rest of this README shows first. Don't want another tool on your machine? Plainpipand a virtual environment work fine too; see the alternate commands below.
-
LuaJIT, a 5.1-compatible build. Put it on yourPATHasluajit, or point to it withPOB_MCP_LUAJIT. You need this separately from PoB itself: PoB's own runtime only shipslua51.dll/SimpleGraphic.dllfor its graphical app. It does not ship a command-line interpreter you can run on its own.

- Windows: install it withScoop(scoop install luajit),Chocolatey(choco install luajit), or a portable build.
- macOS:brew install luajit.
- Linux:apt install luajit, the equivalent for your distribution, or build it from source.

pob-mcp needs to know where your Path of Building - PoE2 install keeps its Lua source, because that's what the bridge process runs against. There are two ways to point it there. Note that the two have different layouts on disk — pob-mcp detects which one you're using automatically.

- Dev checkout mode.SetPOB_MCP_SOURCE_DIRto a PathOfBuilding-PoE2 git checkout — either its root folder, or itssrcfolder directly. This layout keeps the Lua source undersrc/, and keeps the native runtime (LuaJIT DLLs, zlib, the bundled Lua libraries) in a separateruntime/folder next to it.
- Release mode.SetPOB_MCP_INSTALL_DIRto the root folder of an installed release. On Windows, this is usually%APPDATA%\Path of Building Community (PoE2). An installed release puts everything in one folder —Launch.lua,Modules/,zlib1.dll, the bundledlua/libraries — instead of splitting it up. (We checked this against a real install. We didn't just guess from the repo's packaging config.)

If you don't set either variable, pob-mcp checks a few common install locations for your operating system, and gives you a clear error if it can't find one. On Windows, this already finds a normal installer-installed copy without any setup on your part.

git clone <this repo, or wherever you put pob-mcp> pob-mcp cd pob-mcp uv sync

Don't want to use uv?You don't need it. pob-mcp is a normal Python package — plainpipworks too:

git clone <this repo, or wherever you put pob-mcp> pob-mcp cd pob-mcp python -m venv .venv .venv/bin/pip install -e . # Windows: .venv\Scripts\pip install -e .
POB_MCP_SOURCE_DIR=/path/to/PathOfBuilding-PoE2 uv run pob-mcp # or, against an installed release: POB_MCP_INSTALL_DIR="C:\Users\you\AppData\Roaming\Path of Building Community (PoE2)" uv run pob-mcp

With a plainpipinstall, the same thing looks like:

POB_MCP_SOURCE_DIR=/path/to/PathOfBuilding-PoE2 .venv/bin/pob-mcp # Windows: .venv\Scripts\pob-mcp.exe

This starts the MCP server over stdio. You won't see much happen — MCP servers talk to MCP clients, not directly to you. See "Check that it works," below, for a way to try it out without a full client.

Use it with Claude Desktop, Cursor, or another MCP client

Add an entry to your client's MCP server config. For Claude Desktop, this isclaude_desktop_config.json. For Cursor, it'smcp.json.

{ "mcpServers": { "pob-mcp": { "command": "uv", "args": ["--directory", "/absolute/path/to/pob-mcp", "run", "pob-mcp"], "env": { "POB_MCP_SOURCE_DIR": "/absolute/path/to/PathOfBuilding-PoE2" } } } }

For release mode, usePOB_MCP_INSTALL_DIRinstead. Point it to the root folder of your installed release — on Windows, usually%APPDATA%\Path of Building Community (PoE2):

{ "mcpServers": { "pob-mcp": { "command": "uv", "args": ["--directory", "C:\\path\\to\\pob-mcp", "run", "pob-mcp"], "env": { "POB_MCP_INSTALL_DIR": "C:\\Users\\you\\AppData\\Roaming\\Path of Building Community (PoE2)" } } } }

Restart your client after you edit its config. You don't need to close Path of Building itself. pob-mcp only reads game data from the install folder. It never writes to it, so it runs fine alongside the app.

With a plainpipinstall(nouv), pointcommandstraight at the executable pip created in your virtual environment instead — noargsneeded:

{ "mcpServers": { "pob-mcp": { "command": "C:\\path\\to\\pob-mcp\\.venv\\Scripts\\pob-mcp.exe", "env": { "POB_MCP_INSTALL_DIR": "C:\\Users\\you\\AppData\\Roaming\\Path of Building Community (PoE2)" } } } }

(On macOS/Linux, that's/path/to/pob-mcp/.venv/bin/pob-mcp.)

Once your client is connected, start withload_build. Then use the other tools to inspect, change, and improve the build. Every tool that changes the build also returns its updatedstats, so you don't need a separateget_statscall to see the effect of a change. Each tool's full description (parameters, behavior, edge cases) shows up in your MCP client — the lists below are just names and a one-line summary, to help you find the right one.

A note on ids: gems and classes are identified by an internal id, not their display name. Fireball's gem id, for example, is"Metadata/Items/Gems/SkillGemFireball", andselect_classtakes an internal class id, not a simple 0-based index. Uselist_gemsandlist_classesto look these up rather than guessing — a wrong gem id doesn't raise an error, it just silently fails to resolve, so the gem does nothing.

A build can hold several named passive tree specs and several named gear sets, and switch between them. Once you switch one, every other tool (get_tree_state,get_items, and so on) acts on the one you switched to.

- The optimizer never changes configuration options(buffs, curses, enemy stats, map mods). If it could, it could raise its own score by assuming an unrealistic scenario. Callset_configyourself first if you want to optimize for one specific scenario.
- Item and jewel search only uses PoB's local database.Theitemsscope ofoptimize_buildtries items from PoB's own bundled unique database, for the same slot. It doesn't check trade-site prices, and it doesn't search rare-item crafting options.
- The optimizer doesn't search jewels on its own.Matching a jewel to the right socket isn't reliable enough yet. You can still try a specific jewel by hand: uselist_uniques_for_slot, thenequip_item_raw.
- The optimizer is a greedy search, not a perfect solver.It only adds tree nodes — it never removes or replaces existing ones — and it only swaps one gem or item at a time. It can get stuck on a good-but-not-best answer that a wider search might beat.
- pob-mcp can't import a live poe.ninja character profile.It can import a poe.ninja
pob-linkjust like any other supported site, but a live character profile is different: it needs the official character API, and this version doesn't talk to that API yet. Export the character to a PoB code or link first, and use that instead.
- pob-mcp doesn't watch your Builds folder for changes.list_local_buildslists what's there when you call it. It doesn't push updates when something changes. For an LLM-driven session, calling the tool again is simpler, and works just as well.

Automated tests (run withuv run pytest) come in two groups:

- Tests that don't touch PoB at all (test_importers.py,test_optimizer_goals.py,test_optimizer_moves.py,test_locate.py). These run anywhere — you don't need LuaJIT or a PoB install.
- test_bridge_protocol.pyruns a real bridge process from start to finish: it starts a new build, searches the tree, allocates and deallocates nodes, saves and reloads, lists config options, and runs a sanity check. If it can't findPOB_MCP_SOURCE_DIR,POB_MCP_INSTALL_DIR, or aluajitexecutable, itskips itself and tells you why. Set those environment variables to actually run it.

To try the bridge by hand, without a full MCP client:

cd /path/to/PathOfBuilding-PoE2/src luajit /absolute/path/to/pob-mcp/lua/pob_bridge.lua

Then type (or pipe in) JSON-RPC requests, one per line:

{"id": 1, "method": "new_build", "params": {}} {"id": 2, "method": "get_stats", "params": {}}

Each one should print back a{"id": ..., "result": {...}}line.

pob-mcp/ lua/ json.lua # self-contained JSON codec for the bridge protocol pob_bridge.lua # the headless PoB bridge + JSON-RPC loop src/pob_mcp/ server.py # MCP server entrypoint, tool registration bridge.py # subprocess + JSON-RPC client for pob_bridge.lua locate.py # finds a PoB install + luajit sites.py # pobb.in/Maxroll/poe.ninja/etc. URL -> build code importers.py # unifies code/URL/file/XML into one load_build path tools_.py # MCP tool definitions, grouped by area optimizer/ # goal-directed build search tests/

Transaction-complete hotel booking over MCP — 300K+ properties, real hotel confirmation numbers, loyalty points, secure checkout. Hotels are merchant of record. Builders set their own booking fee via Stripe Connect. Built on proven distribution infrastructure.

An MCP server for AI video generation. MCP server for AI video generation. Lets Claude, ChatGPT, OpenClaw , Hermes & other agents create AI videos and publish them to YouTube, TikTok, Instagram etc..

Institutional research and manager diligence reports on hedge funds, venture capital and private equity managers. Summary of filings, personnel changes, media screening and social signals delivered to you in minutes.

ALTER - identity infrastructure for the AI economy

D2C eCommerce fulfillment platform: manage orders, inventory, shipments, campaigns, and billing via AI agents

Apigene MCP Gateway is the runtime layer that connects AI agents to APIs and MCP servers via Model Context Protocol.

MCP to interface with multiple blockchains, staking, DeFi, swap, bridging, wallet management, DCA, Limit Orders, Coin Lookup, Tracking and more.

MCP server for Bitnovo Pay integration with AI agents. Provides cryptocurrency payment capabilities through Bitnovo Pay API. Features include payment creation, status checking, QR code generation, and webhook management with support for multiple tunnel providers (ngrok, zrok, manual).

Shop for gift cards, esims, phone topups. Pay with cards and crypto.

You built it, now get users! GoToMarket MCP server

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.