PCSX2-MCP

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.

	This Git Repo	GitHub Release (zip)
Purpose	Source code only	Ready-to-run package
PCSX2 binaries	❌ Not included	✅ Pre-built `pcsx2-qt.exe` + all DLLs
PCSX2 full source	❌ Not included (see upstream)	❌ Not included
DebugServer patch	✅ `pcsx2-plugin/DebugServer.cpp` + `.h`	✅ Included (already compiled in)
MCP server source	✅ `pcsx2-mcp-server/src/`	✅ Pre-built `dist/` + `node_modules/`
Setup script	✅ `setup-mcp.bat`	✅ Included

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

Launch pcsx2-qt.exe from the extracted folder
Load a PS2 game (ISO or disc)
Restart your AI assistant (Antigravity / Claude Desktop)
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:

Antigravity / Gemini

Edit ~/.gemini/antigravity/mcp_config.json:

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

Claude Desktop

Edit %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)

Create .vscode/mcp.json in your project:

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

Tool	Description
`pcsx2_connect`	Connect to PCSX2 (auto-detects DebugServer or Pine)
`pcsx2_status`	Connection type + emulator status

Memory

Tool	Description
`pcsx2_read_memory`	Read N bytes as hex dump
`pcsx2_write_memory`	Write hex data to address
`pcsx2_read_string`	Read null-terminated string
`pcsx2_find_pattern`	Search for hex pattern (`??` wildcards)
`pcsx2_memory_diff`	Snapshot + diff memory regions

Registers

Tool	Description
`pcsx2_read_registers`	All 7 categories (GPR, CP0, FPU, VU…), full 128-bit
`pcsx2_write_register`	Write register by category + index

Disassembly

Tool	Description
`pcsx2_disassemble`	Native MIPS disassembly at address
`pcsx2_evaluate`	Evaluate expressions: `v0 + 0x100`, `gp - 4`

Breakpoints & Watchpoints

Tool	Description
`pcsx2_set_breakpoint`	Set BP with optional condition + description
`pcsx2_remove_breakpoint`	Remove by address
`pcsx2_list_breakpoints`	List all with condition/status
`pcsx2_set_watchpoint`	Watch read/write/access/onChange
`pcsx2_remove_watchpoint`	Remove watchpoint
`pcsx2_list_watchpoints`	List with hit counts
`pcsx2_clear_all_breakpoints`	Remove ALL breakpoints + watchpoints

Execution Control

Tool	Description
`pcsx2_step`	Step one instruction
`pcsx2_step_over`	Step over JAL/JALR calls
`pcsx2_continue`	Resume execution
`pcsx2_pause`	Halt emulator

System

Tool	Description
`pcsx2_get_threads`	List EE/IOP BIOS threads
`pcsx2_get_modules`	List loaded IOP modules
`pcsx2_get_backtrace`	Call stack walk — entry points, PCs, stack pointers, frame sizes
`pcsx2_game_info`	Game title/ID/version (Pine)
`pcsx2_save_state`	Save state to slot 0-9 (Pine)
`pcsx2_load_state`	Load state from slot (Pine)

PS2Recomp Integration

Tool	Description
`ps2recomp_lookup_function`	Search overrides by address or name
`ps2recomp_list_overrides`	List all function overrides

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

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

Prerequisites

Component	Requires
PCSX2	Git, CMake ≥ 3.22, Ninja, MSVC (Visual Studio 2022), Qt 6
MCP Server	Node.js ≥ 18 (includes npm)

All MCP server dependencies (@modelcontextprotocol/sdk, zod, typescript) are declared in package.json and installed automatically by npm install. You do not need to install them manually.

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 Server

cd pcsx2-mcp-server

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

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

Troubleshooting

Issue	Fix
"No Qt platform plugin"	Make sure `platforms/qwindows.dll` exists next to `pcsx2-qt.exe`
DebugServer not listening	Check PCSX2 console for `[DebugServer] Listening on 127.0.0.1:21512`
"No connection" from tools	Call `pcsx2_connect` first
Pine tools fail	Enable Pine IPC: PCSX2 Settings → Advanced → Enable Pine IPC
Breakpoints don't trigger	Game must be running (not in BIOS/menu)

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.

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
pcsx2-mcp-server		pcsx2-mcp-server
pcsx2-plugin		pcsx2-plugin
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

PCSX2-MCP

A PCSX2 modification and MCP server

⚠️ Repository vs Release — Read This First

Quick Start (3 steps)

1. Download

2. Setup

3. Use

Manual MCP Configuration

What's Inside

DebugServer (built into PCSX2)

MCP Server (Node.js bridge)

All 30 Tools

Connection & Status

Memory

Registers

Disassembly

Breakpoints & Watchpoints

Execution Control

System

PS2Recomp Integration

Example Workflows

Reverse engineering a function

Finding a memory value with diffing

Debugging a crash with call stack

Comparing with PS2Recomp

Architecture

Git Repository

GitHub Release (zip)

Building from Source

Prerequisites

PCSX2

MCP Server

Troubleshooting

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Contributors 1

Languages