MCP Ppsspp

What the dmang-dev/mcp-ppsspp MCP server does

The dmang-dev/mcp-ppsspp MCP server exposes PPSSPP's native debugger through the Model Context Protocol. It is intended for MCP-compatible clients that need to observe or drive a loaded PSP game. The server does not provide a separate emulator or game files; PPSSPP must already be installed and running.

Available operations cover several parts of emulator control:

• Query PPSSPP connectivity, version, loaded title, disc ID, and run state.
• Read and write PSP memory as bytes, little-endian 16-bit or 32-bit values, ranges, and null-terminated UTF-8 strings.
• Send persistent button and analog-stick state, or press a button for a specified number of frames.
• Pause, resume, reset, or advance execution by one MIPS instruction.
• Capture the current framebuffer as an inline PNG.
• Retrieve MIPS Allegrex registers and add, remove, or list CPU execution breakpoints.

How it works

An MCP client starts the server over stdio. The Node.js process then opens a WebSocket connection to PPSSPP's debugger endpoint and communicates using JSON-RPC with the debugger.ppsspp.org subprotocol. PPSSPP's own remote debugger supplies the instrumentation, so no bridge plugin needs to be loaded into the emulator.

PPSSPP must have a game loaded for game-dependent operations such as screenshots and memory inspection. The debugger connection uses the host and port shown by PPSSPP after remote debugging is enabled. The default host is 127.0.0.1; the port has no default and must be supplied.

Setup and configuration

Install the npm package globally or run it through npx:

npm install -g mcp-ppsspp
npx -y mcp-ppsspp

The dmang-dev/mcp-ppsspp MCP server requires Node.js 22 or newer and a recent PPSSPP release with the WebSocket debugger, identified in the documentation as version 1.7 or later. In PPSSPP, open Settings, Tools, Developer Tools, enable Allow remote debugger, and note the displayed port. Start the MCP server with that port in PPSSPP_PORT.

PPSSPP_HOST can change the debugger host and defaults to the loopback address. For Claude Desktop, configure mcp-ppsspp as the command and pass PPSSPP_PORT in its environment. Claude Code can register the same command with its MCP configuration.

Tools and capabilities

Memory tools use PSP addresses and support little-endian numeric reads. Range reads are limited to 64 KiB, while range writes accept a byte array. The documented memory map includes scratchpad RAM, VRAM, kernel RAM, user RAM, and hardware-register space. Kernel-mode mirrors can refer to the same physical RAM as their lower-address counterparts.

Input tools recognize PSP controls including the face buttons, directional buttons, start, select, triggers, and home. A timed button press releases automatically, while persistent button and analog state remains active until changed. Analog position is shared state and is not automatically released.

Execution stepping advances one MIPS instruction rather than one video frame. Breakpoints can be used with resume when frame-oriented control is needed. The screenshot tool returns PNG data inline, but requires a loaded game.

Limitations and notes

The dmang-dev/mcp-ppsspp MCP server does not expose native savestate save or load operations. Savestates must be managed through PPSSPP's UI keybinds. Frame advance is instruction-level only. Remote tool calls may hang or time out if PPSSPP's interface is not responding or its main loop is not dispatching WebSocket requests.

A failed connection usually means PPSSPP is stopped, remote debugging is disabled, or the configured port is incorrect. Invalid memory addresses are rejected when they fall outside PPSSPP's mapped regions. Remote button input may need a longer duration for games that poll input rapidly.

The project is released under the MIT license.