BLACK SOULS MCP
A Windows-only MCP bridge that reads BLACK SOULS / BLACK SOULS II internal state and drives the game through its native input loop.
Inspect live scene, player, party, message, menu, battle, map, event, and scene-detail state.
Read game variables, switches, inventory/equipment, party stats, learned skills, and save slots.
Launch, monitor, diagnose, or forcefully terminate the game process.
Send allowlisted inputs, multi-step input sequences, waits, dashes, and text skips.
Navigate with pathfinding, interact with nearby events, advance dialogue, and choose dialogue options.
List battle options and execute battle commands such as attack, skill, magic, item, guard, or flee.
Save and load specific save slots through in-game menu navigation.
Maintain AI scratchpad notes, long-term game knowledge, goals, and session logs.
Check bridge health and evaluate scenario completion conditions for the eval runner.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@BLACK SOULS MCP check game status and launch if ready"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
一个同时支持 BLACK SOULS 和 BLACK SOULS II 的 MCP。让 Claude Code / Codex 这类 agent 直接接入用户选中的游戏。纯娱乐。
原理很简单:读游戏内部对象拿状态,再把动作送进游戏自带的按键输入循环。不截图、不模拟鼠标、也不需要图片模型,所以非图像模型也能用。bs1 的寻路、对话、菜单和战斗曾实机校准;bs2 已实测读档、存档、对话、寻路、交互,以及 ATB 战斗的胜利结算、逃跑和不可用选项拦截,战斗中使用道具和多次行动尚未实测。
本仓库只包含桥接程序与 MCP 源码,不包含、不下载、也不分发游戏本体、存档、素材、密钥或解包后的商业游戏数据。使用前请自行准备合法获得的游戏文件。
能干嘛?
接入后,MCP 客户端能拿到:
场景、地图、坐标、朝向、通行信息
附近事件、消息、选项菜单
队伍等级、生命、魔力、异常状态、金钱
战斗阶段、双方单位、当前可用指令
也能操控角色:移动、确认、取消、翻页、冲刺、Ctrl 文本快进,或者一次提交一整套连续动作,比如"向上跑三步,再打开菜单看装备"。
dash_up/down/left/right 会在同一帧组合方向与游戏的 Shift/冲刺键;text_skip 对应 Ctrl,可用 repeat 连续保持。
共 37 个工具,按用途分组:
分组 | 工具 | 用途 |
进程与诊断 |
| 选择 bs1 / bs2、检查文件与桥接、启动或强制结束游戏、列出存档与诊断 |
状态读取 |
| 场景、角色、消息、菜单、战斗;附近或大范围地图;事件页与触发条件;场景深层状态 |
游戏数据 |
| 变量、开关、背包物品与装备、队伍详细属性和技能 |
输入 |
| 白名单键盘动作、多步连续动作、等待某个游戏条件成立 |
高层动作 |
| 自动寻路与交互、按真实窗口列出当前可用指令和技能/道具/目标索引、提交一次战斗输入(不承诺整回合结算;魔法与换装备仅在游戏实际提供该指令时可用)、推进对话并选择选项、保存与读取 |
AI 记忆 |
| 会话便签、长期游戏知识库、目标层级、持久会话日志,跨上下文重置保留;bs1 / bs2 分别存放 |
评测 |
| 供 |
Related MCP server: Hotkeyless AHK MCP
工作原理
桥接脚本每秒约更新 10 次状态;地图仅在位置或地图变化时生成新快照。命令由游戏主线程逐帧处理,不依赖窗口焦点,也不依赖视觉识别。查询类命令(变量、开关、背包、全图等)走同一条通道即时应答,不占用帧步进。
输入只经过游戏自身的移动 / 事件 / 菜单 / 战斗处理逻辑,接口不会直接改生命、物品、变量或剧情开关。命令带着进程 ID、启动代次、帧号和命令编号,旧状态和重复命令会被拒绝;快照损坏会自动跳过;游戏在后台被 RPG Maker 暂停时,桥接能恢复键盘循环,不抢前台窗口。
跟截图 OCR和鼠标模拟比,差在哪?
截图 / OCR 方案 | 鼠标模拟方案 | BLACK SOULS MCP | |
状态来源 | 图像识别,容易看错、看漏 | 图像识别 | 直接读游戏内部对象,逐帧精确 |
需要窗口置顶 / 前台 | 通常需要 | 需要 | 不需要,后台也能恢复输入循环 |
是否联网 | 常需要视觉模型服务 | 视实现而定 | 纯本地 stdio,不开端口 |
输入路径 | 模拟点击 / 按键 | 模拟点击 | 走游戏原生输入循环,帧同步 |
会不会误改存档 / 剧情 | 视实现而定 | 视实现而定 | 不直接改生命、物品、变量、剧情开关 |
快速开始
想让 AI agent 帮你安装,可以把下面这段话复制给它:
请帮我在 Windows 上安装 black-souls-mcp:https://github.com/yk4464/black-souls-mcp
先克隆仓库,完整阅读 README 的「快速开始」,再按它的步骤操作。要求:
1. 检查 Node.js 18+ 和 Python 3.11+;缺少时告诉我,不要自行安装。
2. 先问我用的是 BLACK SOULS(bs1)还是 BLACK SOULS II(bs2),以及原版游戏安装在哪个目录。
3. 游戏必须来自我自己合法拥有的副本。不要下载游戏,也不要去别处找游戏文件。
4. 把原版复制到 runtime/game(bs1)或 runtime/game2(bs2),之后只操作这个副本,绝不修改 Steam 原版目录。
5. bs2 必须先把 Game.rgss3a 全量解包到副本目录,确认成功后才能改名为 Game.rgss3a~。
6. 按 README 用 patch_rvdata2_binary.py 把桥接注入副本的 Data/Scripts.rvdata2,并保留备份。
7. 运行 install.ps1 前先停下来问我:它会修改 ~/.codex/config.toml(会自动备份)。bs2 要加 -Game bs2。
8. 如果我用的不是 Codex,就按我的 MCP 客户端自己的方式注册 dist/index.js 和 install.ps1 写入的那些环境变量。
9. 装完运行 .\check.ps1 -IncludeRuntime(bs2 加 -Game bs2),把结果告诉我,并提醒我重启 MCP 客户端。
任何一步失败或不确定时,停下来把原始错误给我看,不要绕过检查。或者按下面的步骤手动安装。
平台 | Windows 10/11 |
Node.js | Node.js 18 或更新版本 |
Python | Python 3.11+(仅用于桥接脚本写入工具) |
游戏副本 | 自己的 BLACK SOULS 或 BLACK SOULS II 游戏副本 |
脚本档 | 已从自己的副本准备好 |
支持引擎 | RPG Maker VX Ace / RGSS3 |
传输方式 | 本地 |
游戏版本 | bs1 / bs2 各有一个内置 |
发布方式 | 从源码安装;当前未发布 npm 包 |
1. 获取源码并检查
git clone https://github.com/yk4464/black-souls-mcp.git
Set-Location .\black-souls-mcp
npm.cmd ci
npm.cmd run check2. 准备独立运行目录
默认目录结构:
runtime/
├─ game/
│ ├─ Game.exe
│ ├─ Game.ini
│ ├─ Game.rgss3a~
│ └─ Data/Scripts.rvdata2
├─ game2/
│ ├─ Game.exe
│ ├─ Game.ini
│ ├─ Game.rgss3a~
│ └─ Data/Scripts.rvdata2
└─ backup/runtime/ 已被 Git 忽略。准备步骤概述:把自己的游戏副本复制到 runtime/game/,确保 Data/Scripts.rvdata2 已解出(可用 scripts/extract_rgss3a_file.py),然后用桥接写入工具把 rgss/BlackSoulsBridge.rb 注入脚本档:
python .\scripts\patch_rvdata2_binary.py .\runtime\game\Data\Scripts.rvdata2 .\rgss\BlackSoulsBridge.rb --backup .\runtime\backup\Scripts.rvdata2.bakpatch_rvdata2_binary.py 只用 Python 标准库,保持原字节布局,优先使用;备选的 patch_rvdata2.py 需要先 python -m pip install -r requirements-tools.txt。
准备 bs2:把自己的 BLACK SOULS II 整份副本复制到 runtime/game2/,先将 Game.rgss3a 全量解包到该目录,再改名为 Game.rgss3a~。不能只解出 Scripts.rvdata2 就改名,否则游戏读取不到归档里其余资源。全量解包会覆盖同名散放文件(归档优先),逐项打印有差异的文件及总数;已发现某些 bs2 副本有 3 张同名 PNG 不一致,不能盲目保留散放版本:
python .\scripts\extract_rgss3a_file.py .\runtime\game2\Game.rgss3a --all .\runtime\game2
Rename-Item -LiteralPath .\runtime\game2\Game.rgss3a -NewName 'Game.rgss3a~'
python .\scripts\patch_rvdata2_binary.py .\runtime\game2\Data\Scripts.rvdata2 .\rgss\BlackSoulsBridge.rb --backup .\runtime\backup\Scripts2.rvdata2.bak两部游戏若已注入旧版桥接,也需用当前 rgss/BlackSoulsBridge.rb 重新注入;旧桥接不包含真实窗口列表和整数按钮映射。以上命令仅适用于你自己的游戏副本,勿在游戏运行时改写。
3. 安装到 Codex
Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1安装脚本会先备份当前用户的 Codex config.toml,再写入 black_souls MCP 注册。完成后重启 Codex。
使用外部目录:
.\install.ps1 `
-RuntimeRoot 'D:\BlackSoulsRuntime' `
-GameDir 'D:\BlackSoulsRuntime\game'只有 bs2 副本时用 .\install.ps1 -Game bs2;同时准备两部时,注册会保留 BLACK_SOULS_DIR、BLACK_SOULS2_DIR 及各自指纹。在 MCP 内先调用 black_souls_select_game(不传 game)查看准备情况,再传 {"game":"bs1"} 或 {"game":"bs2"} 切换;游戏运行中不能切换。选择写入 runtime/active_game.txt,MCP 重启后保留,优先级高于安装时的 BLACK_SOULS_GAME 默认值。自定义 bs2 路径传 -Game2Dir。
4. 验证
重启 Codex 后先调用:
请调用 black_souls_status,检查游戏文件和桥接状态。随后可以依次调用:
black_souls_launch
black_souls_get_state
black_souls_get_map连续动作参数示例:
{
"steps": [
{ "action": "move_up" },
{ "wait_frames": 12 },
{ "action": "confirm" }
]
}加速移动与文本:
{
"steps": [
{ "action": "dash_up", "repeat": 3 },
{ "action": "text_skip", "repeat": 30 }
]
}仅对独立 MCP 游戏副本启用可选的引擎快进:在游戏目录下创建
BridgeRuntime/frame_rate.txt,内容写一个 30–120 的整数。有效配置会跨 MCP 游戏重启保留;删除此文件即恢复游戏启动时帧率;
black_souls_get_state 的 frame_rate 字段返回实际值。快进只缩短真实游戏帧等待,不直接改魂、
属性、掉落、敌人或剧情。调高前应先保存并用少量战斗验证先手、伤害与结算;高难度仍可能导致死亡和掉魂。
游戏版本指纹与环境变量
获取自己的 Game.exe SHA-256:
(Get-FileHash -Algorithm SHA256 -LiteralPath '.\runtime\game\Game.exe').Hash然后在当前终端指定:
$env:BLACK_SOULS_GAME_EXE_SHA256 = '<YOUR_SHA256>'bs2 对应 runtime/game2/Game.exe 和 BLACK_SOULS2_GAME_EXE_SHA256。各自的指纹设为空字符串会跳过比较,但仍会检查必需文件是否存在;只有确认文件来源后才应这样做。
变量 | 说明 |
| 运行目录;默认 |
| bs1 独立游戏目录,默认 |
| bs1 的 |
| bs2 独立游戏目录,默认 |
| bs2 的 |
| 初始游戏 bs1 / bs2;持久选择文件优先 |
| 单元测试临时目录 |
| 可选的集成测试最少存档数 |
限制与故障提示
游戏资源准备与解包方式取决于发行版本,因此未做成自动下载流程
RPG Maker 在后台可能暂停键盘循环;服务使用已核对进程和路径的 Windows 消息恢复循环,不模拟鼠标,也不把窗口切到前台
命令超时后若提示"游戏可能已经接收",应先读取最新状态,再决定是否重试,避免重复动作
本项目仅面向本机可信目录,不应把
BridgeRuntime放到其他用户可写的位置
卸载与回滚
.\uninstall.ps1
.\rollback.ps1两者只处理 Codex 注册及其配置备份,不删除游戏或存档。指定某个备份进行回滚:
.\rollback.ps1 -ConfigBackup 'D:\BlackSoulsRuntime\backup\config.toml.before-black-souls-....bak'测试
npm.cmd run check # 构建、MCP 握手、工具发现与合成测试
npm.cmd run test:integration # 需要已准备的运行目录
npm.cmd run test:live # 启动游戏并执行真实键盘输入
.\check.ps1 -IncludeRuntime # 检查源码、游戏副本和 Codex 注册
.\check.ps1 -IncludeRuntime -Game bs2 # 只读核对 bs2 的准备目录与指纹
node evals\runner.mjs menu_navigation # 运行一个评测场景(需要真实游戏)真实测试会改变当前游戏会话中的位置或菜单,但不会主动保存。运行前仍建议保留自己的存档副本。
安全与隐私
服务只使用本地
stdio,不会监听网络端口命令动作使用固定白名单,并限制队列、步骤和总帧数
仓库忽略游戏、存档、运行快照、日志、依赖缓存和构建产物
提交问题前请移除个人路径、存档内容和游戏文件
安全问题请通过 GitHub Security Advisory 私下报告;其他问题使用 Issues。
参与贡献
请先阅读 CONTRIBUTING.md。package.json 中保留 private: true,用于防止误发布到 npm;这不影响 GitHub 上的 MIT 开源源码。
许可证与声明
本仓库源码采用 MIT License。
BLACK SOULS、RPG Maker、相关名称和游戏资产归各自权利人所有;本项目是非官方社区工具,与游戏作者、发行商及引擎厂商无隶属关系。
Available Tools
36 toolsblack_souls_advance_dialogueB
Advance active dialogue until it ends or a choice appears, optionally selecting a choice.
Inputs: timeout_ms, choice_index, max_advances. Returns: data
black_souls_battle_actionA
Execute one battle turn in a single call: pick the command (attack / skill(特技) / magic(魔法) / guard / item / flee), the list index, and the enemy target; menu navigation is closed-loop against the real cursor. Indices come from black_souls_battle_options; a choice the battler cannot afford is refused before any input is spent. Returns resulting party (including MP/TP) and enemy state.
Inputs: action (required), item_index, timeout_ms, enemy_index, +1 more. Returns: data
black_souls_battle_optionsARead-onlyIdempotent
List everything the acting battler can do this turn: top-level commands, the full contents of every skill and magic submenu (name, MP/TP cost, whether it is usable right now, description), usable battle items with counts, and living enemy targets. Every entry carries the exact index to pass to black_souls_battle_action, so call this before choosing a battle action instead of guessing.
Inputs: no named parameters. Returns: data
black_souls_eval_statusARead-onlyIdempotent
Check scenario completion conditions against live game state. Used by the eval runner; returns pass/fail per condition.
Inputs: check_conditions (required). Returns: data
black_souls_get_eventARead-onlyIdempotent
Inspect an event's pages, trigger conditions, active page, and self-switches.
Inputs: event_id (required). Returns: data
black_souls_get_full_mapARead-onlyIdempotent
Request map tiles, passability, regions, terrain tags, and events up to radius 20. The scan runs inside one game frame: radius 6 is cheap, radius 20 freezes the game for about a second, so prefer 12 or less.
Inputs: radius. Returns: data
black_souls_get_inventoryARead-onlyIdempotent
Read the party's current inventory: consumable items, weapons, and armors with counts.
Inputs: no named parameters. Returns: data
black_souls_get_mapBRead-onlyIdempotent
Read the current nearby map tiles, passability, and events directly from RGSS3.
Inputs: no named parameters. Returns: data
black_souls_get_party_detailARead-onlyIdempotent
Read detailed party stats, equipment, and learned skills.
Inputs: no named parameters. Returns: data
black_souls_get_scene_detailARead-onlyIdempotent
Read deeper state for the active map, battle, or menu scene.
Inputs: no named parameters. Returns: data
black_souls_get_stateARead-onlyIdempotent
Read current scene, player, party, message, windows, and battle state directly from RGSS3.
Inputs: no named parameters. Returns: data
black_souls_get_switchesARead-onlyIdempotent
Read RPG Maker boolean switches by ID. Request up to 64 IDs per call.
Inputs: ids (required). Returns: data
black_souls_get_variablesARead-onlyIdempotent
Read RPG Maker game variable values by ID. Request up to 64 IDs per call.
Inputs: ids (required). Returns: data
black_souls_goals_readARead-onlyIdempotent
Read the persistent objective hierarchy and active goal.
Inputs: no named parameters. Returns: data
black_souls_goals_set_activeAIdempotent
Choose the gameplay goal currently being pursued, or clear it.
Inputs: id (required). Returns: data
black_souls_goals_writeBIdempotent
Create or update a persistent gameplay goal.
Inputs: id (required), notes (required), title (required), status (required), +4 more. Returns: data
black_souls_healthARead-onlyIdempotent
Comprehensive bridge health check with diagnosis and recommended recovery action.
Inputs: no named parameters. Returns: data
black_souls_inputB
Inject one allowlisted virtual RPG Maker input into the normal game input loop.
Inputs: action (required), repeat, timeout_ms. Returns: data
black_souls_input_sequenceA
Inject up to 200 allowlisted inputs and frame waits as one ordered sequence.
Inputs: steps (required), timeout_ms. Returns: data
black_souls_interactB
Walk up to and interact with a nearby event, optionally selected by ID.
Inputs: event_id, timeout_ms. Returns: data
black_souls_killADestructiveIdempotent
Forcefully terminate the running BLACK SOULS process. Safe to call when game is not running.
Inputs: no named parameters. Returns: data
black_souls_launchB
Launch the independent BLACK SOULS MCP edition and wait for its in-game bridge. The window is minimized after launch by default so real keyboard input cannot leak into the game; inputs keep working through the background wake path.
Inputs: wait_ms, minimize_window. Returns: data
black_souls_list_savesARead-onlyIdempotent
List independent MCP-edition save slots and metadata without modifying them.
Inputs: no named parameters. Returns: data
black_souls_loadA
Load a save slot from the title screen or the in-game menu and return the resulting state.
Inputs: slot (required), timeout_ms. Returns: data
black_souls_memory_deleteBIdempotent
Delete one long-term memory entry.
Inputs: key (required), category (required). Returns: data
black_souls_memory_readARead-onlyIdempotent
Read long-term game knowledge, optionally filtered by category.
Inputs: category. Returns: data
black_souls_memory_writeCIdempotent
Store or update one long-term game knowledge entry.
Inputs: key (required), value (required), source (required), category (required), +1 more. Returns: data
black_souls_saveA
Trigger an in-game save to a specific slot (0-indexed) by injecting menu navigation inputs. Only works from Scene_Map.
Inputs: slot (required), timeout_ms. Returns: data
black_souls_scratchpad_readARead-onlyIdempotent
Read the AI agent's current session scratchpad.
Inputs: no named parameters. Returns: data
black_souls_scratchpad_writeB
Update notes, flags, or recent actions in the session scratchpad.
Inputs: flags, notes, append_action. Returns: data
black_souls_session_log_appendC
Append a significant gameplay event to the persistent session log.
Inputs: summary (required), event_type (required), frame, scene. Returns: data
black_souls_session_log_readBRead-onlyIdempotent
Read the most recent persistent session log entries.
Inputs: last_n. Returns: data
black_souls_situationARead-onlyIdempotent
Get a concise snapshot of the current game situation, contextual action suggestions, and warnings.
Inputs: no named parameters. Returns: data
black_souls_statusARead-onlyIdempotent
Inspect the BLACK SOULS MCP edition and live RGSS3 bridge status.
Inputs: no named parameters. Returns: data
black_souls_waitCRead-only
Wait until a game condition becomes true before proceeding.
Inputs: condition (required), timeout_ms. Returns: data
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 36 tools
Each tool has a clearly distinct purpose, covering process management, state inspection, input, memory, goals, navigation, battle, and dialogue. Even tools like black_souls_get_state and black_souls_situation differ in detail and focus.
All tools consistently follow the verb_noun pattern with the 'black_souls_' prefix, e.g., black_souls_kill, black_souls_get_state, black_souls_input_sequence. The naming is uniform and predictable.
With 36 tools, the set is comprehensive and each tool serves a specific purpose for game interaction. While it is on the higher end, the complexity of the game justifies the number. A slight reduction could still maintain completeness.
The tool set covers all major game operations: launch/stop, state reading, input, save/load, navigation, battle, dialogue, memory/goals, and evaluation. There are no obvious gaps for the intended use case.
Maintenance
Related MCP Connectors
A simple MCP server built with FastMCP and python
MCP server to assist with JxBrowser development.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server to interact with Obsidian via the Local REST API community plugin.134,535MIT
- AlicenseAqualityCmaintenanceMCP server for Hotkeyless AHK HTTP API. It lets your agent control your whole computer using hotkeys.42MIT
- AlicenseAqualityBmaintenanceMCP server for the mGBA Game Boy Advance emulator. Read and write GBA memory, inject button presses, take screenshots, save/load state, and step the emulator through a Lua bridge.1835 npm7MIT
- AlicenseBqualityCmaintenanceMCP server that reads and writes RPG Maker XP project .rxdata files, enabling AI assistants to create and edit actors, items, skills, maps, events, and scripts, and render map previews, by describing what you want.6572 npm4MIT