Skip to main content
Glama
dmang-dev

mcp-ppsspp

by dmang-dev
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

mcp-ppsspp

npm version npm downloads CI License: MIT Snyk Socket Bundlephobia npmgraph

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.

Related MCP server: chrome-devtools-mcp

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

  1. Launch PPSSPP, load any PSP ISO/EBOOT

  2. Settings → Tools → Developer Tools → Allow remote debugger (check the box)

  3. PPSSPP will show the active host:port (e.g. ws://192.168.1.10:12345/debugger)

  4. 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

Install Server
A
license - permissive license
A
quality
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
<1hResponse time
0dRelease cycle
5Releases (12mo)
Commit activity

Resources

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dmang-dev/mcp-ppsspp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server