mcp-ppsspp

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

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

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)

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

Replace 12345 with your actual port. Verify:

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

Claude Desktop

Edit claude_desktop_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

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

License

MIT