mcp-ppsspp is an MCP server for connecting PPSSPP (a PlayStation Portable emulator) to any MCP-compatible client (such as Claude Desktop, Claude Code, etc.). It works through PPSSPP's built-in WebSocket debugger interface, so unlike mcp-bizhawk / mcp-mgba, it does not require loading a Lua bridge plugin in the emulator—PPSSPP comes with a debugger WebSocket interface, and the server communicates with it directly via JSON.
Purpose
This server is intended for scenarios that require controlling or debugging PSP games through an MCP client. It wraps PPSSPP's debugging capabilities into a clean tool interface, allowing MCP clients to read and write PSP memory, drive games with button input, capture screenshots, set CPU breakpoints, inspect MIPS Allegrex registers, and more.
Main capabilities
- Read and write PSP memory
- Drive games with button input
- Capture screenshots
- Set CPU breakpoints
- Inspect MIPS Allegrex registers
Connection method
The connection uses the subprotocol debugger.ppsspp.org, through PPSSPP's debug port.
Usage
Prerequisites:
- PPSSPP (a newer version with the WebSocket debugger, 1.7+)
- Enable "Allow remote debugger" in PPSSPP
Set up the PPSSPP debugger:
- Launch PPSSPP and load any PSP ISO/EBOOT
- Go to Settings → Tools → Developer Tools → Allow remote debugger (check the box)
- PPSSPP will display the active host:port (for example ws://192.168.1.10:12345/debugger)
- Note the port number—you will set it later as an environment variable for the MCP server
Register with an MCP client:
- Claude Code (CLI): replace 12345 with the actual port
- Claude Desktop: edit claude_desktop_config.json, then restart Claude Desktop after editing
It can also be run via npx -y mcp-ppsspp.
PSP memory map (quick reference)
PSP is little-endian (MIPS Allegrex). The kernel-mode mirror 0x88xxxxxx maps to the same physical RAM as 0x08xxxxxx.
Button names
cross, circle, triangle, square, up, down, left, right, start, select, ltrigger, rtrigger, home.
Use cases
Suitable for development, debugging, or automation scenarios that require memory read/write, input control, screenshots, breakpoint debugging, and register inspection for PSP games in PPSSPP through an MCP client.
Limitations and notes
- No savestate API: PPSSPP's WebSocket debugger does not expose savestate.save / load. Currently, you can use PPSSPP's key bindings (F1-F8 correspond to save slots) through UI operations. In theory, it may be possible to trigger key bindings via input.buttons.press as a workaround, but this is not natively supported.
- Frame advancement is instruction-level only (cpu.stepInto). To advance a whole frame, you can set a breakpoint at the vblank handler and resume.
- The analog stick is shared state: ppsspp_send_analog updates a persistent stick position and does not release automatically.
- mcp-ppsspp has no default port—you need to read the active port from PPSSPP's Developer Tools → Allow remote debugger dialog and pass it in as PPSSPP_PORT.
- tools/list works even when PPSSPP is not connected; however, calling tools requires PPSSPP to be running with the remote debugger enabled.
Debugging with MCP Inspector
You can interactively browse and call this server's tools through MCP Inspector. If you have edited src/ since the last npm install, build first (npm run build, or keep npm run dev running).
