pob-mcp 是一个 MCP 服务器。它允许 LLM 加载、检查、修改和改进 流放之路 2 的构建。它使用来自 Path of Building Community (PoE2 分支) 的真实计算引擎，而不是重新实现该引擎。
pob-mcp 运行一个真实的、无头版本的 PoB（一个 Lua 程序）作为后台进程。它通过一个小型的 JSON-RPC 协议与该进程通信。你拿到的每一个统计数据都是 PoB 自身计算出的数字。
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.lua 是 PoB 自身 src/HeadlessWrapper.lua 的一个分支，PoB 在其测试套件中使用该文件。pob-mcp 并不直接依赖该文件。已安装的 PoB 副本会排除 HeadlessWrapper.lua（参见 manifest.cfg），因此 pob-mcp 自带了自己的版本。这意味着 pob-mcp 对 PathOfBuilding-PoE2 的 git 检出和已安装的发布版本都能以相同的方式工作。
Related MCP server: poe2-mcp-server
你需要四样东西：
uv。用它来安装和运行 pob-mcp。
LuaJIT，一个兼容 5.1 的构建版本。将其放在 PATH 中，命名为 luajit，或者通过 POB_MCP_LUAJIT 指向它。你需要单独安装它，因为 PoB 自身的运行时仅提供 lua51.dll/SimpleGraphic.dll 用于其图形应用程序，并未提供可独立运行的命令行解释器。
Windows：通过 Scoop（scoop install luajit）、Chocolatey（choco install luajit）或便携版安装。
macOS：brew install luajit。
Linux：apt install luajit，或使用你发行版对应的命令，或者从源码编译。
Path of Building - PoE2 安装。可以是 git 检出（此仓库或你自己的克隆），也可以是已安装的发布版本。请参见下方“将 pob-mcp 指向 PoB 安装目录”。
zlib。pob-mcp 需要它来读取和写入构建代码，以及计算永恒珠宝数据。在 Windows 上，你已拥有它：PoB 捆绑了 zlib1.dll（对于检出版本在 runtime/ 中，对于已安装的发布版本则与其他文件放在一起）。在 Linux 和 macOS 上，如果尚未安装，请安装你系统的 zlib/libz 包（大多数系统已安装）。如果 pob-mcp 找不到 zlib，除了粘贴或共享的构建代码以及永恒珠宝计算外，其他所有功能仍能正常工作。请使用 .xml 文件加载和导出构建。
pob-mcp 需要知道你的 Path of Building - PoE2 安装目录存放 Lua 源码的位置，因为桥接进程就是针对这些源码运行的。有两种方式可以指向它。请注意，这两种方式在磁盘上的布局不同——pob-mcp 会自动检测你使用的是哪一种。
开发检出模式。将 POB_MCP_SOURCE_DIR 设置为 PathOfBuilding-PoE2 git 检出的根目录或其 src 目录。这种布局将 Lua 源码放在 src/ 下，并将原生运行时（LuaJIT DLL、zlib、捆绑的 Lua 库）放在一个单独的 runtime/ 文件夹中。
发布版本模式。将 POB_MCP_INSTALL_DIR 设置为已安装发布版本的根目录。在 Windows 上，通常是 %APPDATA%\Path of Building Community (PoE2)。已安装的发布版本将所有内容放在一个文件夹中——Launch.lua、Modules/、zlib1.dll、捆绑的 lua/ 库——而不是分散放置。（我们已根据真实安装进行了验证，并非仅凭仓库的打包配置猜测。）
如果你未设置这两个变量中的任何一个，pob-mcp 会检查操作系统上的几个常见安装位置，如果找不到，则会给出明确的错误信息。在 Windows 上，这通常无需任何设置即可找到通过普通安装程序安装的副本。
git clone <this repo, or wherever you put pob-mcp> pob-mcp
cd pob-mcp
uv syncPOB_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这将通过 stdio 启动 MCP 服务器。你不会看到太多输出——MCP 服务器与 MCP 客户端通信，而不是直接与你交互。请参见下方“检查是否正常工作”以了解无需完整客户端即可尝试的方法。
在客户端的 MCP 服务器配置中添加一个条目。对于 Claude Desktop，这是 claude_desktop_config.json。对于 Cursor，这是 mcp.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"
}
}
}
}对于发布版本模式，使用 POB_MCP_INSTALL_DIR 代替。将其指向已安装发布版本的根目录——在 Windows 上，通常是 %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)"
}
}
}
}编辑配置后重新启动客户端。你无需关闭 Path of Building 本身。pob-mcp 仅从安装目录读取游戏数据，从不写入，因此它可以与应用程序并行运行。
变量 | 作用 |
| PathOfBuilding-PoE2 git 检出的路径（其根目录或 |
| 已安装发布版本的根目录路径 |
|
|
| 加载 zlib 的路径或名称（如果 pob-mcp 无法自行找到） |
| 你的 PoB Builds 文件夹路径，用于 |
| Python 端的日志级别（默认 |
客户端连接后，从 load_build 开始。然后使用其他工具检查、修改和改进构建：
加载构建：load_build（接受 PoB 导出代码、pobb.in/Maxroll/poe.ninja pob-link/poe2db.tw/Pastebin.com/Rentry.co 链接、本地 .xml 文件路径或原始 XML 文本）、new_build、list_local_builds。
检查构建：get_stats、list_stat_keys、get_character、list_classes、get_tree_state、node_info、search_tree、get_items、get_skills、list_gems、get_config、list_config_options、sanity_check。
修改构建：alloc_node/dealloc_node、node_path_cost、select_class、equip_item_raw/unequip_item、add_socket_group、set_main_skill、add_gem/remove_gem/set_gem、list_valid_supports、set_config。
关于宝石的说明：每个宝石都有一个内部 ID，该 ID 与其显示名称不同。例如，火球的 ID 是 "Metadata/Items/Gems/SkillGemFireball"。使用 list_gems 查找正确的 ID——不要猜测。错误的猜测不会引发错误，只会静默解析失败，因此宝石不生效。职业也是如此：select_class 接受一个内部职业 ID，而不是简单的从 0 开始的索引。使用 list_classes 查找它。
改进构建：optimize_build(goal="damage"|"defence"|"balanced", scope=[...]) 在被动天赋树、辅助宝石和本地暗金物品上运行目标导向搜索。它会对每个候选改动使用 PoB 的真实引擎进行检查。请在你的 MCP 客户端中查看其完整描述，包括它有意不修改的部分。
比较或导出：compare_builds、export_build。
每个修改构建的工具也会返回更新后的 stats。你无需单独调用 get_stats 来查看修改效果。
这些是设计选择，而非缺陷：
优化器从不更改配置选项（增益、诅咒、敌人属性、地图词缀）。如果它可以更改，它可能会通过假设不现实的场景来提高自身分数。如果你想针对某个特定场景进行优化，请先自行调用 set_config。
物品和珠宝搜索仅使用 PoB 的本地数据库。 optimize_build 的 items 范围会尝试 PoB 自身捆绑的暗金数据库中的物品（针对同一位置）。它不检查交易网站价格，也不搜索稀有物品的工艺选项。
优化器不会自行搜索珠宝。 将珠宝匹配到正确的插槽目前还不够可靠。你仍然可以手动尝试特定的珠宝：使用 list_uniques_for_slot，然后使用 equip_item_raw。
优化器是贪心搜索，而非完美求解器。 它只添加天赋节点——从不移除或替换现有节点——并且一次只替换一个宝石或物品。它可能会卡在一个不错但不是最佳的答案上，而更广泛的搜索可能会击败它。
pob-mcp 无法导入实时 poe.ninja 角色档案。 它可以像其他受支持的网站一样导入 poe.ninja pob-link，但实时角色档案不同：它需要官方角色 API，而此版本尚未与该 API 通信。请先将角色导出为 PoB 代码或链接，然后使用该代码或链接。
pob-mcp 不会监视你的 Builds 文件夹的变化。 list_local_builds 会列出你调用时文件夹中的内容。当有变化时，它不会推送更新。对于 LLM 驱动的会话，再次调用该工具更简单，效果也一样好。
自动化测试（使用 uv run pytest 运行）分为两组：
完全不涉及 PoB 的测试（test_importers.py、test_optimizer_goals.py、test_optimizer_moves.py、test_locate.py）。这些测试在任何地方都可以运行——你不需要 LuaJIT 或 PoB 安装。
test_bridge_protocol.py 从开始到结束运行一个真实的桥接进程：它启动一个新构建，搜索天赋树，分配和取消分配节点，保存并重新加载，列出配置选项，并运行一个健全性检查。如果找不到 POB_MCP_SOURCE_DIR、POB_MCP_INSTALL_DIR 或 luajit 可执行文件，它会跳过自身并告诉你原因。设置这些环境变量以实际运行它。
要手动尝试桥接（无需完整 MCP 客户端）：
cd /path/to/PathOfBuilding-PoE2/src
luajit /absolute/path/to/pob-mcp/lua/pob_bridge.lua然后输入（或通过管道输入）JSON-RPC 请求，每行一个：
{"id": 1, "method": "new_build", "params": {}}
{"id": 2, "method": "get_stats", "params": {}}每个请求都应打印回一行 {"id": ..., "result": {...}}。
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/This server cannot be deployed
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Remote MCP for RunComfy: ComfyUI deployments, hosted models, LoRA training. 31 tools.
