convez.ai
MCP ServerAutomaçãoAvançado
dmang-dev

MCP PPSSPP

dmang-dev/mcp-ppsspp

Controle emulador PSP via Claude sem plugins adicionais

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe o emulador PPSSPP (PlayStation Portable) através da interface WebSocket nativa do debugger. Permite ler/escrever memória PSP, controlar jogos com entrada de botões, capturar screenshots, definir breakpoints e inspecionar registradores MIPS.

Instalação

$npx convez-ai dmang-dev/mcp-ppsspp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
12
Forks
3
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
v0.1.4
Issues abertas
11
Contribuidores
1

Casos de uso

  • Automação de testes em jogos PSP
  • Análise dinâmica de código de máquina (MIPS Allegrex)
  • Manipulação de estado de jogo para exploração de exploits

Veredito

Ferramenta altamente especializada para quem trabalha com emulação PSP e debugging de baixo nível. Integração limpa via WebSocket nativo do PPSSPP, sem necessidade de plugins adicionais, mas requer conhecimento profundo de arquitetura de emuladores.

README

A tradução para o português deste README ainda está na fila.

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.

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 varDefaultPurpose
PPSSPP_HOST127.0.0.1WebSocket host to dial
PPSSPP_PORT(required)WebSocket port — see PPSSPP's debugger settings

Tools

ToolDescription
ppsspp_pingVerify connectivity (returns version)
ppsspp_get_infoTitle, disc ID, version, run state
ppsspp_read8 / ppsspp_read16 / ppsspp_read32Read u8 / u16-LE / u32-LE from PSP memory
ppsspp_write8 / ppsspp_write16 / ppsspp_write32Write to PSP memory
ppsspp_read_rangeRead up to 64 KiB as a byte array
ppsspp_write_rangeWrite byte array to memory
ppsspp_read_stringRead null-terminated UTF-8 string
ppsspp_press_buttonsSet persistent PSP button state
ppsspp_press_buttonPress a button for N frames + auto-release
ppsspp_send_analogSet analog stick position
ppsspp_pause / ppsspp_resumePause / resume emulation
ppsspp_stepStep one MIPS instruction
ppsspp_resetSoft-reset the loaded game
ppsspp_screenshotCapture framebuffer as inline PNG
ppsspp_get_registersRead all MIPS Allegrex registers
ppsspp_breakpoint_add / _remove / _listCPU execution breakpoints

PSP memory map (cheat sheet)

RangeRegion
0x00010000 - 0x00013FFFScratchpad (fast 16 KiB SRAM)
0x04000000 - 0x041FFFFFVRAM (2 MiB GE video memory)
0x08000000 - 0x087FFFFFKernel RAM (8 MiB, low half)
0x08800000 - 0x09FFFFFFUser 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

SymptomCause / Fix
PPSSPP_PORT must be set on startupSet the env var to the port shown in PPSSPP's Developer Tools dialog
WebSocket connection failedPPSSPP isn't running, "Allow remote debugger" isn't checked, or you have the wrong port
Tool calls hang / time outCheck the PPSSPP UI is responding; the WebSocket request requires PPSSPP's main loop to dispatch
Invalid address on memory opsAddress is outside the PSP's mapped regions (user RAM is 0x08800000+, not 0x00000000+)
Screenshot returns no dataNo game loaded — boot an ISO/EBOOT first
Buttons don't seem to do anythingPPSSPP'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

Ver o original no GitHub

Bom para

Relacionados