Skip to content
Back to search

ps5-mcp

MCP server payload for jailbroken PS5 — virtual DualSense, 4K native screenshots, process and klog tools, title launch, ELF loader. Any MCP client (Claude Code, Claude Desktop, Cursor, SDKs) can drive the console over HTTP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gl0ttis--ps5-mcp/badge.svg)](/listings/gl0ttis--ps5-mcp)

HTML

<a href="/listings/gl0ttis--ps5-mcp"><img src="/api/listings/gl0ttis--ps5-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 263 lines
  1. # ps5-mcp
  2. A payload for a jailbroken PS5 that **is itself an MCP server**. Send one ELF to the
  3. console's ELF loader and any MCP client (Claude Code, Claude Desktop, Cursor, the MCP SDKs)
  4. can drive and inspect the console directly over the network. Nothing runs on the host:
  5. no bridge, no stdio.
  6. - **Input:** a system-wide virtual DualSense. You can press, hold, chord, use sticks,
  7. triggers and the touchpad, and run whole timed sequences.
  8. - **Sight:** a screenshot of the whole composited screen, home screen and system dialogs
  9. included. It is cropped, scaled and JPEG/PNG-encoded on the console and returned as an
  10. MCP image. A title can also hand over its own frame through a small grab hook.
  11. - **Diagnostics:** processes (with title ids, memory, CPU, threads, memory maps, open
  12. files), a kernel-log ring buffer with cursors, regex filters and wait-for-pattern,
  13. system info, files, installed titles, launching or closing titles, and starting ELF
  14. payloads through the console's ELF loader with their output captured.
  15. ```
  16. claude mcp add --transport http ps5 http://<console-ip>:7165/mcp
  17. ```
  18. > For homebrew development on a console you own. It listens on your LAN with **no
  19. > authentication** (by design). Run it only on a network you trust.
  20. ## Tools
  21. | Tool | What it does |
  22. | --- | --- |
  23. | `pad_open` | Create the virtual pad, bind it to the foreground user, dismiss "Who's using this controller?", and (by default) disconnect the real controller so titles read this one |
  24. | `pad_close` / `pad_status` / `pad_release` | Remove the pad / show its state and counters / return to neutral |
  25. | `pad_press` | Press a button or chord (`cross`, `l1+r1`), with repeat, and an optional screenshot after |
  26. | `pad_hold` | Hold buttons, sticks (-1..1), triggers (0..1) or a touchpad finger, for a duration or until released |
  27. | `pad_sequence` | `"down*2 cross wait:1500 ls:up:400 shot"`: presses, stick moves, waits and screenshots, timed on the console and validated before the first press |
  28. | `screenshot` | `native` (default — triggers a fresh 4K compose inside SceShellUI via ptrace and reads the frame from the compositor shared memory; no pad, no gallery file, ~200 ms SceShellUI freeze), `system` (whole screen via the console's own Create-hold capture), `title` (the title's own frame via the grab hook), `latest` (newest existing capture). Supports `max_width`, `crop` (to read small text), `format`, `quality`, `grayscale` |
  29. | `system_info` | Firmware, model, temperatures, CPU clock, memory, uptime, foreground user, running title, IPs, free storage, and server state |
  30. | `list_processes` | Table or JSON of every process: pid, ppid, state, threads, CPU%, authid, title id, RSS/VSZ; filter and sort |
  31. | `process_info` | One process's threads (name, state, CPU time), and optionally its memory map and open files |
  32. | `kill_process` | Signal a process; refuses system (`Sce*`) processes unless `force=true` |
  33. | `klog_read` | Kernel log from an in-payload ring (8192 lines): `tail`, `cursor`, `filter`/`exclude` regex, `wait_ms`, `until` (wait for a line, e.g. a title's startup message) |
  34. | `fs_list` / `fs_read` | Directory listings (recursive); file reads as text, hex dump, base64, or an image for JPEG/PNG/BMP; negative offsets read the tail |
  35. | `app_list` / `app_launch` / `app_kill` | Installed titles with names, which one is running; launch by title id; close the running title |
  36. | `elf_run` | Start an ELF payload through the console's ELF loader (127.0.0.1:9021), from a file on the console or uploaded as base64 (up to 16 MiB); returns what it prints and the processes it started |
  37. | `notify` | Show a toast on the TV |
  38. | `server_shutdown` | Close the pad and end the payload (e.g. before sending a new build) |
  39. The server's `initialize` result carries an operating guide for the agent (look, act,
  40. look again; when to use each screenshot mode; etiquette), so clients that pass server
  41. instructions to the model need no extra prompt.
  42. ## Build
  43. Requirements: the [PS5 payload SDK](https://github.com/ps5-payload-dev/sdk) (default
  44. `/opt/ps5-payload-sdk`) and a C compiler plus Python 3 for the host tests.
  45. ```bash
  46. make # build/ps5-mcp.elf (PS5_PAYLOAD_SDK=/path/to/sdk to override)
  47. make PORT=7165 # change the default listening port at build time
  48. make host # build/ps5-mcp-host (same server on a mock backend, ASan+UBSan)
  49. make test # run the end-to-end suite against the host build
  50. ```
  51. ## CI and releases
  52. Versions follow [semantic versioning](https://semver.org), derived from
  53. [Conventional Commits](https://www.conventionalcommits.org) by
  54. [semantic-release](https://semantic-release.gitbook.io):
  55. | Commit | Release |
  56. | --- | --- |
  57. | `fix: ...`, `perf: ...` | patch (1.2.3 → 1.2.4) |
  58. | `feat: ...` | minor (1.2.3 → 1.3.0) |
  59. | `feat!: ...` or a `BREAKING CHANGE:` footer | major (1.2.3 → 2.0.0) |
  60. | `docs:`, `test:`, `ci:`, `chore:`, `refactor:` | no release |
  61. - **Pull requests to `main`** (`.github/workflows/ci.yml`): the PR title must be a
  62. Conventional Commit, since it becomes the squash-merge message. The payload is built
  63. with the pinned SDK (v0.45), `make test` runs, and `build/ps5-mcp.elf` is uploaded as
  64. an artifact.
  65. - **Pushes to `main`** (`.github/workflows/release.yml`): the same build and test, then
  66. semantic-release. It rebuilds the payload with the new version baked in (`make
  67. VERSION=x.y.z`, reported by `system_info` and `initialize`), tags `vX.Y.Z`, and
  68. publishes a GitHub release with notes and `ps5-mcp-X.Y.Z.elf` attached.
  69. Local builds take their version from the nearest `vX.Y.Z` tag, or `0.0.0-dev`.
  70. ## Run on the console
  71. The console needs an **ELF loader** (port 9021 in the usual chains). It should also run a
  72. **klog server** (port 3232). The payload reads the kernel log through it, and the pad needs
  73. that to learn its device id.
  74. ```bash
  75. make deploy PS5_HOST=<console-ip> # prospero-deploy to port 9021
  76. # or: nc -q0 <console-ip> 9021 < build/ps5-mcp.elf
  77. ```
  78. It listens on **port 7165** (`http://<console-ip>:7165/mcp`, and `GET /health` for a
  79. plain-text check). A second copy finds the port taken and exits. Logs go to klog and to
  80. `/data/ps5-mcp/ps5-mcp.log`. A payload's stdout is the ELF loader's socket, so the
  81. server logs through `klog_printf`.
  82. ### Connect a client
  83. ```bash
  84. claude mcp add --transport http ps5 http://<console-ip>:7165/mcp # Claude Code
  85. ```
  86. ```json
  87. { "mcpServers": { "ps5": { "type": "http", "url": "http://<console-ip>:7165/mcp" } } }
  88. ```
  89. `tests/test_sdk_client.py` drives the server with the official MCP Python SDK
  90. (`pip install mcp`). It is useful as a first check against a real console:
  91. ```bash
  92. python3 tests/test_sdk_client.py http://<console-ip>:7165/mcp # read-only checks
  93. python3 tests/test_sdk_client.py http://<console-ip>:7165/mcp --pad # open the pad, take a screenshot
  94. ```
  95. ## Design
  96. ```
  97. MCP client ──HTTP POST /mcp (JSON-RPC)──▶ ps5-mcp payload (one process)
  98. ┌──────────────────────────────┐
  99. http.c thread per connection, Content-Length │ mcp.c JSON-RPC, registry │
  100. and chunked bodies, Origin check │ tools_*.c │
  101. pad.c held state re-inserted every 8 ms, │ screen.c capture → image.c │
  102. console-side timing, one console job │ klog.c ring buffer thread │
  103. at a time (input + system shots) │ backend_ps5.c (SDK calls) │
  104. └──────────────────────────────┘
  105. ```
  106. - **Streamable HTTP, stateless.** Every request is a POST answered with
  107. `application/json`; notifications get `202`; `GET /mcp` is `405` (no server-initiated
  108. stream). Protocol versions 2024-11-05 through 2025-11-25 are negotiated. Batches are
  109. accepted. Requests with an `Origin` header are accepted only from `localhost` or from
  110. the console's own IP address. In DNS rebinding both `Origin` and `Host` carry the
  111. attacker's domain name, so such requests are refused. Non-browser clients send no
  112. `Origin` and are unaffected.
  113. - **Console-side timing.** Presses, holds and waits run on the console, not across the
  114. network. A whole `pad_sequence` is parsed and checked before anything is pressed, so a
  115. typo never leaves a menu half-navigated. Input and system screenshots share one lock;
  116. read-only tools never wait on it.
  117. - **Images processed on the console.** A 4K capture is decoded (stb_image), optionally
  118. cropped, area-averaged down (so thin UI lines and text survive), and re-encoded. A
  119. 1280-wide JPEG is about 50–200 KB instead of a multi-megabyte 4K file.
  120. - **One klog reader for everything.** A background thread keeps the kernel log in a
  121. ring with sequence numbers. `klog_read` pages through it with cursors. `pad_open`
  122. finds the new device's id and the controller table there too, so no second klog
  123. connection can race it. The line formats are SceShellCore's own format strings, read
  124. from the firmware binary (`src/pad_klog.h`).
  125. - **Portable core, two backends.** `backend_ps5.c` holds every SDK and system call.
  126. `backend_host.c` is a mock (a pad log, a test-card "screenshot" when Create is held
  127. ≥ 1 s, `/proc` processes, a heartbeat klog). The full server builds and is tested on
  128. Linux with sanitizers.
  129. ### Screenshots
  130. `mode=system` holds Create on the virtual pad for 1.2 s, the console's own "take
  131. screenshot" shortcut. It waits for the new file under `/user/av_contents/photo`, sends it,
  132. then deletes it through `sceContentDeleteByPath`, as the gallery's Delete does (file,
  133. thumbnail and database row). It takes about 3 s.
  134. `mode=title` asks the running title for its own frame through a grab hook. It takes
  135. about 1 s and leaves nothing in the gallery. The contract:
  136. 1. The server creates a request file, by default `/data/homebrew/<TITLE_ID>/ps5-mcp-grab`
  137. (`/app0/ps5-mcp-grab` from inside the title).
  138. 2. Every few frames the title tries to `unlink()` it. One system call fails on every
  139. ordinary frame. When the unlink succeeds, the title writes its next frame (JPEG or PNG)
  140. as a new file, mode 0666, in a folder of its own, by default
  141. `/data/homebrew/<TITLE_ID>/screenshots`.
  142. 3. The server sends the newest picture in that folder and deletes it.
  143. ```c
  144. static void grab_hook(void) /* call once per frame */
  145. {
  146. static int frame;
  147. if (++frame % 4 == 0 && unlink("/app0/ps5-mcp-grab") == 0)
  148. write_next_frame_to("/app0/screenshots"); /* your engine's screenshot */
  149. }
  150. ```
  151. `request_path` and `folder` override the defaults, so an existing hook with other file
  152. names works too.
  153. With **HDR on**, console captures are JPEG XR. They can't be decoded on the console, so
  154. the tool says so and leaves the capture on the console. Turn HDR off for agent sessions.
  155. #### Native capture (default)
  156. `mode=native` is the default and triggers a fresh, live 4K compose on every call. No pad,
  157. no Create hold, no file written to the gallery, and the whole composited screen is
  158. captured (home screen, system dialogs and overlays included). Typical cost is about 1.5 s
  159. end-to-end on the first call per SceShellUI PID, dropping to ~200 ms on later calls once
  160. the per-PID offsets are cached.
  161. The payload finds SceShellUI's main executable through `sysctl KERN_PROC_VMMAP`, then
  162. signature-scans the text segment for two addresses: the internal
  163. `sceScreenshotCaptureForCoreDump` function (the compose-config byte sequence
  164. `48 B? 93 00 00 00 (03|05)` lives in its prologue) and the compositor shared-memory base
  165. pointer (loaded by the `TZCNT` + `SHL 0x19` sequence in one of the compose vtable
  166. methods). A single byte in the function is patched from mode 3 (720p) to mode 5 (4K),
  167. ptrace attaches to SceShellUI, a fast-trap `pt_call` invokes the patched function
  168. synchronously inside SceShellUI, the mode byte is reverted, and ptrace detaches. The
  169. composed 3840×2160 BGRA frame lives in the compositor shared memory at a deterministic
  170. offset from the scanned base pointer; it is read out with `kernel_proc_copyout`, scaled
  171. and encoded on the console, and returned as an MCP image. The intermediate file that
  172. CoreDump's save step writes before failing its format check is `unlink()`ed on the way
  173. out, so the filesystem stays clean.
  174. All SceShellUI offsets are discovered at runtime, so the path is firmware-agnostic — no
  175. addresses are baked into the build.
  176. ## What has been verified
  177. | | Status |
  178. | --- | --- |
  179. | MCP protocol, HTTP layer, tool logic | **Tested** on the host build: `make test` (88 checks, ASan + UBSan clean) and the official MCP Python SDK client (mcp 2.3.0). The mock backend replaces only the system calls. The klog parsing, eviction choice, capture pipeline, image processing and ELF-loader protocol run the same code as on the console |
  180. | klog formats (DEVICE_ADDED, `[CIM]` controller table) | The format strings were read from SceShellCore (firmware build 1777439). Not yet observed live |
  181. | `mode=native` fresh 4K compose via ptrace + CoreDump | **Run on a 13.20 console (CFI-7119).** The default screenshot mode. Returns a live composited 3840×2160 BGRA frame on every call, scaled and encoded on the console. First call per SceShellUI PID is ~1.5 s (signature-scanning the ~47 MB eboot); later calls ~200 ms. All SceShellUI offsets are discovered at runtime so the build has no firmware-specific addresses. |
  182. | PS5 payload | **Builds and links** against the ps5-payload-dev SDK |
  183. | Console paths (`/user/av_contents/photo`, `/user/app`, appmeta `param.json` layout) | Checked against a real console's filesystem |
  184. | Read-only tools on a console | **Run on a 13.20 console (CFI-7119)** through Payload Manager: `system_info`, `list_processes`, `klog_read` work as described |
  185. | Pad and Create-hold capture on a console | **Run on a 13.20 console** with a USB DualSense and ASTRO's PLAYROOM: `pad_open` both ways (exclusive evicted the USB pad, then recreated the virtual pad so it took the first slot; the game then read it), buttons, both sticks, both triggers (held through a screenshot), `screenshot mode=system` with `crop`, `pad_sequence` with `shot`, `pad_close`, `app_launch` and `app_kill`. Touchpad input is sent without error but unconfirmed (nothing on screen showed it). Not yet run: `mode=title`, `elf_run` |
  186. Every console-facing tool returns the raw result code of each system call (for example
  187. `pad_open` reports `padInit`, `add`, `device`, `bind`, `insert_tries`), so bring-up on
  188. another firmware works from the tool output.
  189. ## Limits
  190. - Pictures are stills, not video. `mode=native` costs ~200 ms (plus a one-time ~1.5 s
  191. scan on the first call per SceShellUI PID); `mode=system` costs about 3 s. Some titles
  192. block the `system` path.
  193. - A title reads only its user's first controller slot. `pad_open` therefore disconnects
  194. the real one by default, then recreates the virtual pad so it takes that first slot (a
  195. pad keeps the slot it was given). The PS button on the real controller reconnects it. `exclusive=false` keeps it, but
  196. then only the home screen sees the virtual pad.
  197. - The pad's device id comes from the kernel log: without a klog server (or `/dev/klog`),
  198. `pad_open` can't bind the pad.
  199. - No authentication, by request. Anyone on the LAN who can reach the port can drive the
  200. console.
  201. ## Credits
  202. Prior art for the virtual pad and the Create-hold capture:
  203. [PS5 DevLoop](https://github.com/griches/PS5_DevLoop),
  204. [SplashDown](https://github.com/seregonwar/SplashDown),
  205. [Control4Free](https://github.com/MoHadiShibli/Control4Free),
  206. [OmniPad-PS5](https://github.com/diegobarbosaa/OmniPad-PS5) and
  207. [Ghostpad](https://github.com/srbraboo/Ghostpad). App launch/kill and notifications
  208. follow [ps5-payload-dev/websrv](https://github.com/ps5-payload-dev/websrv), and process
  209. listing follows the SDK's `ps` sample. Bundled: [cJSON](https://github.com/DaveGamble/cJSON)
  210. (MIT) and [stb_image / stb_image_write](https://github.com/nothings/stb) (public domain
  211. / MIT).
  212. Not affiliated with Sony Interactive Entertainment.
  213. ## License
  214. GPL-3.0-or-later. See `LICENSE`. Third-party code keeps its own license
  215. (`third_party/*/LICENSE`).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.