# dmang-dev/mcp-ppsspp [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/dmang-dev/mcp-ppsspp  
**GitHub Stars:** 8  
**npm Downloads (last month):** 103  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/dmang-dev-mcp-ppsspp

## Description
Drive PSP games through PPSSPP's built-in WebSocket debugger interface — no plugin needed. Memory r/w (u8/u16/u32/range/string), input (buttons + analog), pause/resume/step, screenshot, MIPS Allegrex registers, CPU execution breakpoints. The richest debugger surface in the family thanks to PPSSPP's native instrumentation.

## Tools
Capabilities this server exposes over MCP:

- **ppsspp_ping** — Verify connectivity (returns version)
- **ppsspp_get_info** — Title, disc ID, version, run state
- **ppsspp_read8** — Read u8 / u16-LE / u32-LE from PSP memory
- **ppsspp_write8** — 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** — 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** — CPU execution breakpoints

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-ppsspp": {
    "command": "npx",
    "args": ["-y","mcp-ppsspp"],
    "env": {
      "PPSSPP_PORT": ""
    }
  }
}
```

**Requires environment variables:** `PPSSPP_PORT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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`:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/dmang-dev-mcp-ppsspp/readme_