mcp-ppsspp

An MCP server that exposes PPSSPP — the PlayStation Portable emulator — to any MCP-compatible client (Claude Desktop, Claude Code, etc.) via PPSSPP's built-in WebSocket debugger interface.

Read and write PSP memory, drive games with button input, capture screenshots, set CPU breakpoints, inspect MIPS Allegrex registers — all through a clean tool interface. No bridge plugin needed; PPSSPP's debugger is built into the emulator.

How it works

Code

+------------------+    stdio     +------------------+   WebSocket    +------------------+
|   MCP client     |   JSON-RPC   |    mcp-ppsspp    |   JSON-RPC     |     PPSSPP       |
| (Claude / etc.)  | ===========> |     (Node.js)    | =============> |    (debugger)    |
+------------------+              +------------------+                +------------------+

Unlike the mcp-bizhawk / mcp-mgba bridges (which need a Lua plugin loaded into the emulator), PPSSPP ships with its own debugger WebSocket interface — we just speak JSON to it. No plugin to install.

The connection uses subprotocol debugger.ppsspp.org on PPSSPP's debugger port.

Requirements

PPSSPP (recent version with WebSocket debugger — 1.7+)
Node.js 22+
"Allow remote debugger" enabled in PPSSPP

Install

Terminal

npm install -g mcp-ppsspp

Or npx -y mcp-ppsspp.

Set up PPSSPP's debugger

Launch PPSSPP, load any PSP ISO/EBOOT
Settings → Tools → Developer Tools → Allow remote debugger (check the box)
PPSSPP will show the active host:port (e.g. ws://192.168.1.10:12345/debugger)
Note the port number — you'll set it as an environment variable for the MCP server

Register with your MCP client

Claude Code (CLI)

Terminal

claude mcp add ppsspp --scope user --env PPSSPP_PORT=12345 mcp-ppsspp

Replace 12345 with your actual port. Verify:

Terminal

claude mcp list
# ppsspp: mcp-ppsspp - ✓ Connected

Claude Desktop

Edit claude_desktop_config.json:

config.json

{
  "mcpServers": {
    "ppsspp": {
      "command": "mcp-ppsspp",
      "env": { "PPSSPP_PORT": "12345" }
    }
  }
}

Restart Claude Desktop after editing.

Configuration

Env var	Default	Purpose
`PPSSPP_HOST`	`127.0.0.1`	WebSocket host to dial
`PPSSPP_PORT`	(required)	WebSocket port — see PPSSPP's debugger settings

Tools

Tool	Description
`ppsspp_ping`	Verify connectivity (returns version)
`ppsspp_get_info`	Title, disc ID, version, run state
`ppsspp_read8` / `ppsspp_read16` / `ppsspp_read32`	Read u8 / u16-LE / u32-LE from PSP memory
`ppsspp_write8` / `ppsspp_write16` / `ppsspp_write32`	Write to PSP memory
`ppsspp_read_range`	Read up to 64 KiB as a byte array
`ppsspp_write_range`	Write byte array to memory
`ppsspp_read_string`	Read null-terminated UTF-8 string
`ppsspp_press_buttons`	Set persistent PSP button state
`ppsspp_press_button`	Press a button for N frames + auto-release
`ppsspp_send_analog`	Set analog stick position
`ppsspp_pause` / `ppsspp_resume`	Pause / resume emulation
`ppsspp_step`	Step one MIPS instruction
`ppsspp_reset`	Soft-reset the loaded game
`ppsspp_screenshot`	Capture framebuffer as inline PNG
`ppsspp_get_registers`	Read all MIPS Allegrex registers
`ppsspp_breakpoint_add` / `_remove` / `_list`	CPU execution breakpoints

PSP memory map (cheat sheet)

Range	Region
`0x00010000` - `0x00013FFF`	Scratchpad (fast 16 KiB SRAM)
`0x04000000` - `0x041FFFFF`	VRAM (2 MiB GE video memory)
`0x08000000` - `0x087FFFFF`	Kernel RAM (8 MiB, low half)
`0x08800000` - `0x09FFFFFF`	User RAM (24 MiB, where most game state lives)
`0xBC000000+`	Hardware registers

PSP is little-endian (MIPS Allegrex). Kernel-mode mirrors at 0x88xxxxxx map to the same physical RAM as 0x08xxxxxx.

PSP buttons

cross, circle, triangle, square, up, down, left, right, start, select, ltrigger, rtrigger, home.

Troubleshooting

Symptom	Cause / Fix
`PPSSPP_PORT must be set` on startup	Set the env var to the port shown in PPSSPP's Developer Tools dialog
`WebSocket connection failed`	PPSSPP isn't running, "Allow remote debugger" isn't checked, or you have the wrong port
Tool calls hang / time out	Check the PPSSPP UI is responding; the WebSocket request requires PPSSPP's main loop to dispatch
`Invalid address` on memory ops	Address is outside the PSP's mapped regions (user RAM is `0x08800000+`, not `0x00000000+`)
Screenshot returns no data	No game loaded — boot an ISO/EBOOT first
Buttons don't seem to do anything	PPSSPP's input has the buttons but they may not "feel" right via remote input if the game polls fast; try `ppsspp_press_button` with a longer `duration`

Limitations

No savestate API — PPSSPP's WebSocket debugger doesn't expose savestate.save / load. Use PPSSPP's keybinds (F1-F8 for slots) via the UI for now. Could be hacked by using input.buttons.press to trigger the keybind, but not native.
Frame-advance is instruction-level only (cpu.stepInto). To advance a whole frame, set a breakpoint at the vblank handler and resume.
Analog stick is shared state — ppsspp_send_analog updates the persistent stick position; not auto-released.

Development

Terminal

npm install
npm run dev      # tsc --watch — autobuilds on src/ changes

Debugging with the MCP Inspector

Browse and call this server's tools interactively with the MCP Inspector:

bash

PPSSPP_PORT=<port> npm run inspector

Build first if you've edited src/ since your last npm install (npm run build, or keep npm run dev running). mcp-ppsspp has no default port — read the active one off PPSSPP's Developer Tools → Allow remote debugger dialog and pass it as PPSSPP_PORT. tools/list works even without PPSSPP connected; calling a tool needs PPSSPP running with the remote debugger enabled.

License

MIT