PCSX2

A PCSX2 modification and MCP server

Control a PS2 emulator from your AI coding assistant. Set breakpoints, read registers, disassemble MIPS, inspect memory — all via MCP tools.

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

⚠️ Repository vs Release — Read This First

This git repo does NOT contain the full PCSX2 source code. We only provide the source of our modifications to avoid wasting storage uploading 1 GB of upstream code.

Want to just USE it? → Download the latest Release zip. Everything is pre-built.

Want to modify or rebuild? → Clone this repo, then follow Building from Source below.

Quick Start (3 steps)

1. Download

Grab the latest release from GitHub Releases — extract the zip anywhere.

2. Setup

Run setup-mcp.bat — it checks Node.js and writes the MCP config for you.

Requires Node.js ≥ 18. The setup script will tell you if it's missing.

3. Use

1. Launch pcsx2-qt.exe from the extracted folder
2. Load a PS2 game (ISO or disc)
3. Restart your AI assistant (Antigravity / Claude Desktop)
4. Ask: "Connect to PCSX2 and show me the thread list"

That's it! Your AI assistant now has 30 debugging tools for PS2.

Manual MCP Configuration

If setup-mcp.bat doesn't work or you want to configure manually:

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

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

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

What's Inside

DebugServer (built into PCSX2)

A custom TCP server injected into PCSX2 that listens on port 21512. When the emulator starts, you'll see:

[DebugServer] Listening on 127.0.0.1:21512

MCP Server (Node.js bridge)

Translates MCP tool calls into DebugServer TCP commands. Also supports Pine IPC (port 28011) as fallback for basic memory R/W and save states.

All 30 Tools

Connection & Status

Memory

Registers

Disassembly

Breakpoints & Watchpoints

Execution Control

System

PS2Recomp Integration

Example Workflows

Reverse engineering a function

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

Finding a memory value with diffing

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

Debugging a crash with call stack

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

Comparing with PS2Recomp

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

Architecture

Git Repository

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 Release (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

Building from Source

# 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

cd pcsx2-mcp-server

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

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

Troubleshooting

License

• PCSX2: GPL-3.0 (same as upstream)
• DebugServer plugin: GPL-3.0 (derivative work)
• MCP Server: MIT

The GitHub Release includes a pre-built PCSX2 binary (GPL-3.0). Full source for our modifications is provided in pcsx2-plugin/ (this repo) and also bundled in the release zip under source/. The unmodified PCSX2 source is available at github.com/PCSX2/pcsx2.