AI导哈

PS2模拟器调试工具

PCSX2-MCP是一个为PS2模拟器PCSX2提供调试功能的工具，允许通过AI编码助手控制模拟器，设置断点、读取寄存器、反汇编MIPS代码等。

  • by hkmodd
  • JavaScript
  • 本地部署
  • 41 星标
  • 更新于
在 GitHub 查看 hkmodd/PCSX2-MCP

使用说明

PCSX2-MCP

PCSX2改装及MCP服务器

通过AI编码助手控制PS2模拟器。 设置断点、读取寄存器、反汇编MIPS、检查内存——所有这些都是通过MCP工具完成的。

┌─────────────┐    stdio (MCP)    ┌─────────────────────┐    TCP:21512    ┌─────────────────┐
│ AI Assistant │ ◄──────────────► │  pcsx2-mcp-server   │ ◄────────────► │  PCSX2 Emulator │
│ (Antigravity │                  │  (Node.js bridge)    │                │  + DebugServer   │
│  Claude etc) │                  │                      │ ◄────────────► │  + Pine IPC      │
└─────────────┘                  └─────────────────────┘    TCP:28011    └─────────────────┘

⚠️ 存储库与发布版——先读一下

此git仓库不包含完整的PCSX2源代码。 我们只提供修改的来源，以避免浪费存储空间上传1GB的上游代码。

此Git Repo GitHub发布（zip）
目的 仅源代码 准备运行包
PCSX2二进制文件 ❌ 不包括 ✅ 预建 pcsx2-qt.exe +所有DLL
PCSX2完整源代码 ❌ 不包括在内（见 上游) ❌ 不包括在内
DebugServer补丁 ✅ pcsx2-plugin/DebugServer.cpp + .h ✅ 已包含（已编译）
MCP服务器源 ✅ pcsx2-mcp-server/src/ ✅ 预建 dist/ + node_modules/
安装脚本 ✅ setup-mcp.bat ✅ 包括

只想使用它吗？ → 下载 最新版本 拉链。一切都是预先构建的。

想要修改或重建吗？ → 克隆此仓库，然后按照以下步骤操作 从源头构建 在......下面

快速入门（3个步骤）

1.下载

获取最新版本 GitHub 发布 --把拉链拉到任何地方。

2.设置

跑 setup-mcp.bat --它检查Node.js并为您编写MCP配置。

需要 Node.js ≥ 18. 安装脚本会告诉你它是否丢失。

3.使用

  1. 发射 pcsx2-qt.exe 从提取的文件夹中
  2. 加载PS2游戏（ISO或光盘）
  3. 重启你的人工智能助手（反重力/克劳德桌面）
  4. 问： “连接到PCSX2并向我显示线程列表”

就是这样！你的AI助手现在已经 30个调试工具 对于PS2。

手动MCP配置

如果 setup-mcp.bat 不起作用或您想手动配置：

Antigravity / Gemini

编辑 ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "pcsx2": {
      "command": "node",
      "args": ["<path-to-extracted>/pcsx2-mcp-server/dist/index.js"],
      "disabled": false
    }
  }
}
Claude Desktop

编辑 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "pcsx2": {
      "command": "node",
      "args": ["<path-to-extracted>/pcsx2-mcp-server/dist/index.js"]
    }
  }
}
VS Code (Copilot / Continue.dev)

创建 .vscode/mcp.json 在您的项目中：

{
  "servers": {
    "pcsx2": {
      "command": "node",
      "args": ["<path-to-extracted>/pcsx2-mcp-server/dist/index.js"]
    }
  }
}

里面有什么

DebugServer（内置于PCSX2中）

注入PCSX2的自定义TCP服务器，用于监听 端口21512。当模拟器启动时，您将看到：

[DebugServer] Listening on 127.0.0.1:21512

MCP服务器（Node.js网桥）

将MCP工具调用转换为DebugServer TCP命令。还支持 松树IPC （端口28011）作为基本存储器R/W和保存状态的回退。

全部30个工具

连接和状态

工具 说明
pcsx2_connect 连接到PCSX2（自动检测DebugServer或Pine）
pcsx2_status 连接类型+仿真器状态

记忆

工具 说明
pcsx2_read_memory 读取N个字节作为十六进制转储
pcsx2_write_memory 将十六进制数据写入地址
pcsx2_read_string 读取以null结尾的字符串
pcsx2_find_pattern 搜索十六进制模式(?? 通配符）
pcsx2_memory_diff 快照+差异内存区域

寄存器

工具 说明
pcsx2_read_registers 全部7个类别（GPR、CP0、FPU、VU…），全128位
pcsx2_write_register 按类别+索引写入寄存器

反汇编

工具 说明
pcsx2_disassemble 地址处的本地MIPS反汇编
pcsx2_evaluate 计算表达式： v0 + 0x100, gp - 4

断点和观察点

工具 说明
pcsx2_set_breakpoint 使用可选条件+描述设置BP
pcsx2_remove_breakpoint 按地址删除
pcsx2_list_breakpoints 列出所有条件/状态
pcsx2_set_watchpoint 观看读/写/访问/更改
pcsx2_remove_watchpoint 移除观察点
pcsx2_list_watchpoints 列出点击次数
pcsx2_clear_all_breakpoints 删除所有断点+观察点

执行控制

工具 说明
pcsx2_step 第一步说明
pcsx2_step_over 跳过日航/日航电话
pcsx2_continue 恢复执行
pcsx2_pause 停止模拟器

系统

工具 说明
pcsx2_get_threads 列出EE/IOP BIOS线程
pcsx2_get_modules 列出加载的IOP模块
pcsx2_get_backtrace 调用堆栈遍历——入口点、PC、堆栈指针、帧大小
pcsx2_game_info 游戏名称/ID/版本（Pine）
pcsx2_save_state 将状态保存到插槽0-9（Pine）
pcsx2_load_state 从插槽加载状态（Pine）

PS2恢复集成

工具 说明
ps2recomp_lookup_function 按地址或姓名进行搜索覆盖
ps2recomp_list_overrides 列出所有函数重写

示例工作流程

逆向工程功能

> "Connect to PCSX2"
> "Disassemble 40 instructions at 0x001000E0"
> "Set breakpoint at 0x001000E0 with condition v0 == 5"
> "Continue and wait for breakpoint"
> "Read registers"
> "Read 256 bytes at the address in a0"

使用差分查找内存值

> "Take a memory snapshot of 0x200000, size 4096"
  (do something in the game)
> "Diff the snapshot to find changes"

使用调用堆栈调试崩溃

> "Pause the emulator"
> "Get the backtrace"
> "Disassemble the function at entry 0x00125bf4"
> "Read registers to see what went wrong"

与PS2Recomp相比

> "Look up function at 0x0072e5c0 in PS2Recomp"
> "Set breakpoint at 0x0072e5c0 in PCSX2"
> "Step through and compare register values"

建筑

Git仓库

PCSX2-MCP/                       ← source code only, lightweight
├── pcsx2-plugin/
│   ├── DebugServer.cpp          ← our custom patch for PCSX2 (this is the only PCSX2 modification)
│   └── DebugServer.h
├── pcsx2-mcp-server/
│   ├── src/index.ts             ← MCP server source (TypeScript)
│   ├── src/debug-server-client.ts
│   ├── src/pine-client.ts
│   ├── package.json
│   └── tsconfig.json
├── README.md
├── setup-mcp.bat
└── package-release.ps1

GitHub发布（zip）

PCSX2-MCP-v1.0.0-win64/          ← ready to run, everything pre-built
├── pcsx2-qt.exe                 ← PCSX2 with DebugServer already compiled in
├── *.dll                        ← Qt + runtime dependencies
├── platforms/                   ← Qt platform plugins
├── resources/                   ← PCSX2 shaders, GameDB, etc
├── pcsx2-mcp-server/
│   ├── dist/index.js            ← compiled MCP server
│   └── node_modules/            ← pre-installed dependencies
├── source/
│   ├── DebugServer.cpp          ← patch source (GPL compliance)
│   └── DebugServer.h
├── setup-mcp.bat
└── README.md

从源头构建

Only needed if you want to modify PCSX2 or the MCP server

先决条件

组件 需要
PCSX2 Git、CMake≥3.22、Ninja、MSVC（Visual Studio 2022）、Qt 6
MCP服务器 Node.js ≥18（含npm）

所有MCP服务器依赖项(@modelcontextprotocol/sdk, zod, typescript)在声明中 package.json 并由自动安装 npm install确实如此 不 需要手动安装它们。

PCSX2

# 1. Clone the upstream PCSX2 source (we don't include it in this repo to save space)
git clone https://github.com/PCSX2/pcsx2.git pcsx2-src
cd pcsx2-src

# 2. Copy our DebugServer patch into the PCSX2 source tree
cp ../pcsx2-plugin/DebugServer.cpp pcsx2/DebugTools/
cp ../pcsx2-plugin/DebugServer.h pcsx2/DebugTools/

# 3. Add to CMakeLists.txt (in pcsx2/DebugTools/)
# Add DebugServer.cpp and DebugServer.h to the source list

# 4. Build with CMake + Ninja + MSVC
cmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target pcsx2-qt

MCP服务器

cd pcsx2-mcp-server

# Install all dependencies (MCP SDK, Zod, TypeScript, etc.)
npm install

# Compile TypeScript → dist/index.js
npm run build

故障排除

问题 修复
“没有Qt平台插件” 确保 platforms/qwindows.dll 存在于旁边 pcsx2-qt.exe
DebugServer未侦听 检查PCSX2控制台是否 [DebugServer] Listening on 127.0.0.1:21512
工具中的“无连接” 呼叫 pcsx2_connect 首先
Pine工具失败 启用Pine IPC:PCSX2设置→ 高级→ 启用Pine IPC
断点不会触发 游戏必须正在运行（不在BIOS/菜单中）

许可证

  • PCSX2：GPL-3.0（与 上游)
  • DebugServer插件：GPL-3.0（衍生作品）
  • MCP服务器：MIT

GitHub版本包括一个预构建的PCSX2二进制文件（GPL-3.0）。我们修改的完整来源见 pcsx2-plugin/ （此仓库）并捆绑在发布压缩包中 source/未经修改的PCSX2源可在以下网址获得 github/PCSX2/PCSX2.

相关 MCP