dmang-dev/mcp-pine

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

An MCP server for emulators that speak PINE (Protocol for Instrumentation of Network Emulators) — first-class support for PCSX2 (PS2) and RPCS3 (PS3), with target-aware tool descriptions so the agent sees the right memory map for whichever emulator it's pointed at. Exposes memory read/write and savestate control. Driven from MCP-compatible clients (Claude Desktop, Claude Code, etc.).

What you can do with it

• Read & write emulated memory — 8/16/32/64-bit, anywhere in the emulator's address space (PS2 EE for PCSX2, PPU main memory for RPCS3)
• Trigger save / load state to numbered slots
• Query game metadata — title, serial, disc CRC, version
• Inspect emulator state — running / paused / shutdown

Tool descriptions, memory-map context, and setup help are rendered per-target at startup — set PINE_TARGET=rpcs3 and every memory-tool description shows PS3 PPU addresses instead of PS2 EE addresses.

What you can't do (because PINE itself doesn't expose these):

• Send controller input
• Take screenshots
• Step / pause / reset the emulator

This makes mcp-pine well-suited for memory inspection, cheat / RAM hunting, savestate automation, and reverse engineering, but not for "play games via Claude." For input + screenshot capability on Game Boy Advance, see the sister project mcp-mgba.

How it works

+----------------+    stdio     +----------------+   PINE socket    +-----------------+
|   MCP client   |   JSON-RPC   |    mcp-pine    |  (TCP or Unix)   |    Emulator     |
|  (Claude etc.) | -----------> |   (Node.js)    | ---------------> |  (PINE server)  |
+----------------+              +----------------+                  +-----------------+

mcp-pine opens a loopback connection to the emulator's PINE server (TCP on Windows, Unix domain socket on Linux/macOS) and translates each MCP tool call into a binary PINE message.

Compatible emulators

Emulator	Platform	PINE built in?	Default slot	PINE_TARGET
PCSX2 ≥ 1.7 (setup)	PlayStation 2	✅ Yes (toggle in settings)	28011	pcsx2 (default)
RPCS3 (setup)	PlayStation 3	⚠️ Has IPC with PINE-compatible opcodes — verify before relying on it	28012	rpcs3

Other emulators implementing the PINE spec should work out of the box once you point mcp-pine at the right slot — open an issue if you've tested one and it works.

Note on DuckStation (PS1): DuckStation had PINE support from May–September 2024 but dropped it in commit 19698559. Current builds have no PINE server. If upstream brings it back, PINE_TARGET=duckstation is reserved.

Setting PINE_TARGET does two things: (1) selects the right Unix socket filename on Linux/macOS, and (2) renders all tool descriptions, memory maps, and setup help for that emulator's address space. Default is pcsx2 for back-compat.

Requirements

• An emulator with PINE enabled (see setup below)
• Node.js 22+

Install

Option A — install from npm (recommended)

npm install -g mcp-pine

Verify with mcp-pine (it prints a startup line and waits for stdio — Ctrl+C to exit).

Option B — npx (no install)

npx -y mcp-pine

Option C — clone and develop

git clone https://github.com/dmang-dev/mcp-pine
cd mcp-pine
npm install        # also runs the build via the `prepare` hook

Emulator setup

PCSX2

1. Launch PCSX2 (1.7.x Qt or newer).
2. Settings → Advanced → Enable PINE Server (the option may live under a different submenu in some builds — search the settings for "PINE").
3. Default slot is 28011. If you change it, set PINE_SLOT for mcp-pine.
4. Load any game.

That's it — no scripts, no console commands. PINE is always-on once the toggle is set.

RPCS3

RPCS3 has its own IPC implementation that mirrors PINE's opcode set, but the wire-level compatibility hasn't been thoroughly tested with this client. To try it:

1. Configuration → Advanced → Enable IPC server (or similar — check current RPCS3 docs).
2. Note the configured port.
3. Run with PINE_TARGET=rpcs3 PINE_SLOT=<port> mcp-pine.

If something doesn't work, please file an issue with details.

Register with your MCP client

Claude Code (CLI)

claude mcp add pine --scope user mcp-pine

Verify:

claude mcp list
# pine: mcp-pine - ✓ Connected

Claude Desktop

Edit claude_desktop_config.json:

Platform	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pine": {
      "command": "mcp-pine"
    }
  }
}

Restart Claude Desktop after editing.

Other MCP clients

mcp-pine speaks standard MCP over stdio. Run it and connect any compatible client.

Configuration

Env var	Default	Purpose
PINE_TARGET	pcsx2	Emulator name. Known values: pcsx2, rpcs3. Selects (1) the Unix socket file prefix on Linux/macOS (<target>.sock.<slot>), and (2) the memory map and setup help shown in tool descriptions. Unknown values pass through with a generic memory map.
PINE_SLOT	target default	PINE slot — also the TCP port on Windows. Defaults: pcsx2=28011, rpcs3=28012. Set explicitly to override.
PINE_HOST	127.0.0.1	Override the host (TCP only)
PINE_SOCKET_PATH	(auto)	Override the full Unix socket path on Linux/macOS, bypassing automatic resolution

Tools

Tool	Description
pine_ping	Verify the connection by querying the emulator version
pine_get_info	Title, serial (e.g. SLUS-21274), disc CRC, game version, status
pine_get_status	Just the running/paused/shutdown state
pine_read8 / pine_read16 / pine_read32 / pine_read64	Read memory
pine_read_range	Bulk read up to 4096 bytes (client-side pipelined PINE calls)
pine_write8 / pine_write16 / pine_write32 / pine_write64	Write memory (RAM only — ROM writes are silently dropped)
pine_save_state	Trigger save state to a numbered slot (0-255)
pine_load_state	Trigger load state from a numbered slot (0-255)

See docs/RECIPES.md for end-to-end examples (RAM hunting, struct decoding, snapshot-experiment-restore).

PlayStation 2 address space (PCSX2, default target)

Range	Region
0x00100000-0x01FFFFFF	EE main RAM (32 MiB) — start here for game data
0x10000000	Hardware registers (DMA, GIF, VIF)
0x11000000	VU0 / VU1 memory
0x12000000	GS privileged registers
0x1C000000-0x1C1FFFFF	IOP RAM (2 MiB)
0x1F800000	IOP scratchpad
0x70000000	EE scratchpad (16 KiB)

Troubleshooting

Symptom	Cause / Fix
Cannot reach PINE server	Emulator isn't running, PINE isn't enabled in its settings, or the slot/port doesn't match. Check PINE_SLOT.
PINE FAIL response (0xFF)	The emulator rejected the request — most often because no game is loaded, or the address is unmapped.
Reads return zeros	Address is in an unallocated region. Try 0x00100000 first (almost always inside loaded EE RAM).
Tool calls work but values look corrupted	Check endianness expectations — PINE returns little-endian; if you're interpreting strings, use read_range-style byte reads.
PINE call timed out (10s) from pine_ping after some heavy use	PCSX2's PINE server can wedge. Its request queue is fragile — if a third-party tool pipelines too aggressively (more than ~6 in-flight requests) it silently drops requests, and from then on every reply is mis-aligned with the wrong waiting client. Symptom: even a fresh pine_ping times out. Fix: fully restart PCSX2. Reconnecting alone won't help — the corruption is on the emulator side.
pine_read_range slower than mGBA's read_range	Expected. PINE has no native bulk read, so we issue calls serially (pipelining can wedge PCSX2 — see above). Loopback TCP is fast enough that this isn't usually a problem: measured ~52 ms for a full 4096-byte read on PCSX2 v2.6.3. For workloads that need lower latency and can tolerate occasional emulator restarts, set PINE_PIPELINE_BATCH=2.

Development

npm install
npm run dev      # tsc --watch

Quick smoke test against a running PCSX2:

node .scratch/smoke.cjs

Debugging with the MCP Inspector

Browse and call this server's tools interactively with the MCP Inspector:

PINE_TARGET=pcsx2 npm run inspector

Build first if you've edited src/ since your last npm install (npm run build, or keep npm run dev running). Set PINE_TARGET (pcsx2 default, or rpcs3) and PINE_SLOT to match your emulator — e.g. PINE_TARGET=rpcs3 PINE_SLOT=28012 npm run inspector. tools/list works even without an emulator connected; calling a tool needs PCSX2 (or RPCS3) running with PINE/IPC enabled.

License

MIT

Related

• mcp-mgba — sister MCP server for the mGBA Game Boy Advance emulator (also includes button input + screenshot, which PINE doesn't expose)
• PINE protocol spec — the underlying IPC standard