PS5 MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PS5 MCP launch Astro's Playroom and take a snapshot of the screen"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PS5 MCP
See and control a jailbroken PS5 from an MCP agent or your keyboard, with live HDMI video and audio. macOS only for now, Windows and Linux support is planned.
Requirements
A jailbroken PS5, currently firmware 13.60. Payload Manager and PS5 Web File Manager are recommended (see Console services).
An HDMI capture card connected to the Mac, with HDCP disabled on the PS5 (Settings → System → HDMI → Enable HDCP).
macOS 14 or later, with network access to the console.
To build: Xcode with a signing account, Homebrew, Python 3.12+, and the tools installed below. The payload uses PS5 Payload SDK v0.43 and LLVM 18.1.8.
Console services
Controlling the console needs only padd running, however it was loaded. These payloads add padd Start/Stop, the
game/app list, Install, and file transfers:
Service | Port | Used for |
Payload Manager (v0.5.2 tested) | 8084 | Deploying |
PS5 Web File Manager (v1.9 tested; Payload Manager can load it) | 8888 | Verifying the |
zftpd (v1.6.0 FTP-only | 2120 |
|
Without them, load padd.elf with any ELF loader.
PS5 MCP expects Web File Manager on port 8888; it moves to the next free port when 8888 is taken.
To add zftpd, download zftpd-ps5-v1.6.0.elf from its
releases, rename it to zftpd.elf, and add it to Payload Manager's
library with uv run ps5mcp install zftpd.elf (or Payload Manager's web page). Do not run it yourself: push and
pull start it when they first need it. Without zftpd, push is slower and pull copies single files only.
Related MCP server: vcctrl-mcp
How it works
paddis a payload running on the PS5. It creates a virtual DualSense and accepts controller input over TCP port 9305.The PS5 MCP app captures HDMI video and audio, owns the connection to
padd, and provides keyboard controls, payload Start/Stop, status, and install/uninstall. It talks to Payload Manager and Web File Manager only for the tasks listed above.The MCP server connects agents to the app's local API. Multiple agent sessions and the keyboard can share the console.
Setup
brew install llvm@18 ffmpeg mpv uv xcodegen
make bootstrap # pinned SDK and Python environment
make check # lint, tests, payloads, and the macOS release appThe release app is built at build/PS5 MCP.app. It is signed ad hoc, so macOS asks for its permissions again after
each rebuild. To keep them, sign with your Apple team: make app DEVELOPMENT_TEAM=… APP_BUNDLE_ID=… or
app/Configuration/LocalSigning.xcconfig (copy the .example). Quit the app before rebuilding.
No make target contacts the console.
Usage
Point it at the console:
export PS5_HOST=192.168.1.20(your PS5's IP address). There is no default. The CLI commands also take--host. In the app, set the address in Settings (⌘,). The app saves it and reconnects to it at once. When the app starts,--hostandPS5_HOSTwin over the saved address.Open the app:
uv run ps5mcp vieworopen --env PS5_HOST=$PS5_HOST "build/PS5 MCP.app". Allow camera, microphone, local network, and Documents access when prompted.Start
paddwith Start oruv run ps5mcp padd start, once per console boot. The app answers the user-selection dialog automatically. If your DualSense turns off, press its PS button and select your user again.Control the console from the app window or connect an MCP client (see MCP clients).
Stop
paddwith Stop oruv run ps5mcp padd stopbefore turning off the console. Killing it through Payload Manager can leave a phantom controller until reboot.
The MCP server starts the app when needed, headless by default (PS5MCP_VIEW=1 shows the window).
Closing an MCP session leaves the app running; quitting the app releases input and leaves padd running.
MCP clients
Every client runs the same server from this checkout: uv run --project <repo> ps5mcp-server, with PS5_HOST set.
Use the full path to uv (command -v uv) if the client does not have Homebrew on its PATH.
Claude Code:
claude mcp add ps5 -e PS5_HOST=192.168.1.20 -- uv run --project /path/to/ps5-mcp ps5mcp-serverCodex: add this to ~/.codex/config.toml (or run
codex mcp add ps5 --env PS5_HOST=192.168.1.20 -- uv run --project /path/to/ps5-mcp ps5mcp-server and add the
timeouts after). Installs and file transfers can take minutes, longer than Codex's default tool timeout.
[mcp_servers.ps5]
command = "/opt/homebrew/bin/uv"
args = ["run", "--project", "/path/to/ps5-mcp", "ps5mcp-server"]
startup_timeout_sec = 60 # the first start can launch the app
tool_timeout_sec = 600 # install, push, and pull
[mcp_servers.ps5.env]
PS5_HOST = "192.168.1.20"Other clients that read a JSON config: see examples/mcp.json.
Check the setup with claude mcp list or codex mcp list, then /mcp in a session. Agents from all clients share
the console through the same claim and queue (see Sharing the console). A running session
keeps the server code it started with; restart it after updating this checkout.
Live window and keyboard
The window shows live video, audio, and connection status. The sidebar has these controls:
padd: Start and Stop.
Console: Home, close the running game/app, and Release all input (⌘.).
Launch: pick an installed game/app and launch it (⌘L). The list comes from PS5 Web File Manager and is cached in
titles/; ↻ reloads it.Capture: record your input (⌘R) and save a snapshot as PNG (⌘S).
Recordings: pick a saved recording and play it. These are the same files that agents use with
play_recording.Install: install a
.pkgpackage or add an.elfpayload to Payload Manager (and run it), and uninstall checked games/apps (padd 1.3). For titles ShadowMountPlus manages, uninstalling also deletes their source folder or image through ShadowMountPlus, so its next scan does not install them again.
Holding a key holds its button and gives you priority over agents; releasing it returns control.
Toggle the sidebar with ⌥⌘S, video with ⌥⌘V, and audio with ⌥⌘M. Video and audio preferences
persist. Hiding video keeps capture running; closing the window silences audio but keeps the app and API running.
Quit with ⌘Q or uv run ps5mcp capture stop.
Keys | Pad |
Arrows | D-pad |
Enter / Space | Cross |
Backspace / Esc | Circle |
| Square / Triangle |
Q / E, Z / C | L1 / R1, L2 / R2 |
WASD, IJKL | Left stick, right stick |
Tab, T | Options, touchpad click |
H | Home screen |
Features
MCP tools
Feature | Tools |
Capture and status |
|
Controller input |
|
Console apps |
|
File transfer |
|
Visual automation |
|
Recording |
|
Sharing |
|
Input tools can return a frame with snapshot_after_ms. home suspends the game like the PS button;
use press("circle") to back out of system screens. A game takes input only from the controller that launched it,
so launch games with launch to control them through the MCP.
Sharing the console
Several agents can use the console. An agent calls claim_console(reason) so that other agents cannot press
buttons, run console commands, or install until it calls release_console(). Another agent that calls
claim_console joins a queue. With wait_s, the call returns when the console is free for that agent.
A claim ends when its session closes, or after 10 minutes without a tool call. The sidebar shows the agent that has
the console and the number of agents in the queue. The keyboard and the window's buttons always work. The CLI (ps5mcp pad, ps5mcp padd) is blocked like any agent.
File transfer
push(local_path, remote_path) copies a file or folder from this Mac to the console, and
pull(remote_path, local_path) copies one back. Console paths are absolute. A path names the destination itself;
end it with / to copy into that folder. Folders are copied recursively. A file with the same size and a
destination that is not older is skipped (force=True copies it anyway). A shorter, newer destination resumes
when its last 64 KB match the source; otherwise the file is copied again.
Transfers use FTP through zftpd on port 2120. If zftpd is not running, the tool starts it from Payload Manager's
library. Starting it counts as a console action, so it is refused while another agent has claimed the console.
zftpd cannot be stopped remotely: it runs until the console restarts, and loading it again replaces the running
copy. Without zftpd, push sends files one at a time through Web File Manager, and pull copies single files only.
Native uploads set eboot.bin, .prx and .sprx files to 0755 and read back the remote
execute bits. Other files with source execute bits are also restored when the upload contains native
binaries; ordinary assets are left alone. This check runs even for skipped and resumed files. A rejected
SITE CHMOD or an unreadable/incorrect remote mode fails the upload. Native executable uploads require
zftpd: Web File Manager cannot provide this permission guarantee.
For folders containing eboot.bin and a PS5 sce_sys/param.json with titleId, push then polls
ShadowMount's /api/v1/games until that title is installed, managed, and available from the uploaded
source path (up to 90 seconds). Its API must be reachable from this Mac: allow LAN access in ShadowMount's
settings, and use PS5MCP_SMP_PORT if its port differs from 10101. The default console-local listener
cannot be reached by this check. Failure reports that files may already be uploaded and readiness is
unverified; retrying repairs permissions and checks registration again. Within this MCP server session,
launch blocks titles whose upload is still running or failed its checks. Other sessions and the console's
own launcher do not share this guard. Uploads without a recognized manifest report registration as
unverified. These checks prevent the reported execute-permission failure; they do not prove a title will boot.
The .pkg installer follows a separate Web File Manager upload and install-task path; it does not upload
unpacked title executables through FTP. Package installs have not been validated for this reported issue.
Existing titles are not changed automatically. A read-only permission audit can use FTP MLSD's
unix.mode or Unix LIST for eboot.bin and native modules, then scope any repairs to the identified files.
Variable | Effect |
| Remove the |
| Never start zftpd (for example, during experiments that must not load extra payloads) |
| zftpd's port (default 2120) |
| ShadowMount's API port for native-title registration checks (default 10101) |
Browser viewing
uv run ps5mcp stream serves live MJPEG video at http://127.0.0.1:8090/ (about 10 fps).
Add --bind 0.0.0.0 to view from another machine, or set PS5MCP_STREAM_PORT=8090 to start it with the MCP server.
Recording
Record keyboard input with uv run ps5mcp control --record menu-dance (Ctrl-C to finish), then replay it
with uv run ps5mcp play menu-dance. Agents can use the recording tools above.
You can also record and play from the app window. Recordings and templates live in ~/.local/state/ps5-mcp/.
Other commands
uv run ps5mcp snapshot -o frame.png # capture a frame
uv run ps5mcp pad press right # send a button press
uv run ps5mcp pad home suspend # return to the home screen
uv run ps5mcp pad close # close the running game
uv run ps5mcp pad launch PPSA06654 # launch a title
uv run ps5mcp pad uninstall PPSA06654 # uninstall a title (padd 1.3)
uv run ps5mcp install game.pkg # install a package (or an .elf payload; --run starts it)
uv run ps5mcp push build/title /data/homebrew/FAKE00001 # copy a folder to the console (zftpd)
uv run ps5mcp pull /data/playden/logs ./logs/ # copy a folder from the console (--no-start, --force)
uv run ps5mcp padd status # payload version, uptime, and counters
uv run ps5mcp latency # measure input-to-frame latencyFor development without a capture card, use --video synthetic or --video file:PATH when launching the app,
or set PS5MCP_VIDEO for the server. Close QuickTime/OBS before capturing: only one process can own the card.
The ffmpeg fallback is available with uv run ps5mcp capture start --backend ffmpeg, followed by
uv run ps5mcp view --backend ffmpeg. Run it from a regular terminal with camera and microphone permission.
Hardware runs
These commands contact the console. Quit the app before running soak or killtest.
uv run ps5mcp padd soak --minutes 10
uv run ps5mcp padd killtestRuns are archived in results/ with firmware, loader version, payload hash, logs, and snapshots.
Unfinished runs stay marked incomplete.
Development
Findings · App API · Virtual-pad ABI · Wire protocol · PS button and app control
License
MIT, see LICENSE. The virtual-pad interface values come from FGG-XSense and the launch parameter layout from zftpd; this code is a separate implementation.
100% vibecoded
This project is 100% vibecoded with AI coding agents. It's experimental, may contain bugs, and comes with no guarantees. Use at your own risk.
Available Tools
28 toolsclaim_consoleA
Reserve the PS5 so other agents cannot drive it until you call release_console().
reason: what you are doing, shown to other agents and in the app window. If another agent holds the console you join the queue; with wait_s > 0 (up to 600) this waits for your turn. Calling it again keeps your place, so call it again to keep waiting. The claim lapses after idle_timeout_s (10..3600, default 600) without a tool call from you, and when this session or the app ends; status() shows claim.held_by_you. Looking (snapshot, status) needs no claim; humans at the keyboard always win.
Inputs: reason (required), wait_s, idle_timeout_s.
close_appA
Close the running game or app (unsaved progress is lost). The console returns to the home screen.
Inputs: snapshot_after_ms.
holdC
Hold several buttons together for duration_ms, then release them.
Inputs: buttons (required), duration_ms (required), snapshot_after_ms.
homeA
Go to the PS5 home screen (stands in for the PS button, which the pad cannot send).
method: "suspend" (suspend the running game, as the PS button does), "system" or "shellcore". From system screens such as Settings, press circle instead.
Inputs: method, snapshot_after_ms.
installA
Install a file from this Mac onto the console (refused while another agent has claimed it).
path: a .pkg package (uploaded through Web File Manager to /data/ps5-mcp/pkg, then installed; can take minutes) or an .elf payload (added to Payload Manager's library). run=True also starts the .elf once.
Inputs: path (required), run.
launchA
Launch an installed title by id (e.g. PPSA01325). list_apps() shows what is installed.
A game takes input only from the controller that launched it: launch it here to control it, because a game the user started with their own controller ignores this pad (and one launched here ignores theirs).
Inputs: title_id (required), snapshot_after_ms.
list_appsC
Installed title ids (from /user/app on the console).
Inputs: no named parameters.
list_recordingsC
Saved recordings with their length.
Inputs: no named parameters.
list_templatesC
Saved template names.
Inputs: no named parameters.
play_recordingC
Replay a saved recording with its original timing (up to 5 minutes).
Inputs: name (required), snapshot_after_ms.
pressB
Press and release one button (e.g. cross, circle, up, options). Optionally return a frame afterwards.
Inputs: button (required), hold_ms, snapshot_after_ms.
pullA
Copy a file or folder from the console to this Mac.
Uses FTP through zftpd (port 2120), starting it from Payload Manager when it is not running (that start is refused while another agent has claimed the console); without zftpd, only single files can be copied. If local_path is an existing folder or ends with "/", the item is copied into it. Unchanged files are skipped and partial ones resumed; force=True copies everything again.
Inputs: local_path (required), remote_path (required), force.
pushA
Copy a file or folder from this Mac to the console (refused while another agent has claimed it).
Uses FTP through zftpd (port 2120), starting it from Payload Manager when it is not running; without zftpd, files go one at a time through Web File Manager. remote_path is absolute and names the destination itself; end it with "/" to copy into that folder. Unchanged files (same size, not newer here) are skipped and partial ones resumed; force=True sends everything again. Native executables/modules are chmodded to 0755 and remote execute bits verified, including skipped files (requires zftpd). Native title folders with a PS5 manifest also wait for ShadowMount registration through its LAN-accessible API (port 10101 or PS5MCP_SMP_PORT). Failed title uploads block launch in this server session until push succeeds.
Inputs: local_path (required), remote_path (required), force.
record_startA
Start recording every input (agent tools and the keyboard in the viewer) as timed steps.
Inputs: no named parameters.
record_stopB
Stop recording and save it under name (letters, digits, - and _).
Inputs: name (required).
release_allA
Release every button and centre the sticks (agent and keyboard).
Inputs: no named parameters.
release_consoleA
Give up your claim on the PS5 (or your place in the queue); the next agent in the queue gets it.
Inputs: no named parameters.
save_templateB
Save a region of the current frame (full 1920x1080 coordinates) as a template for wait_for.
Inputs: x (required), y (required), name (required), width (required), +1 more.
sequenceA
Run timed states in order, then release everything.
Each step: {"buttons": [...], "lx"/"ly"/"rx"/"ry": -1..1, "l2"/"r2": 0..1, "duration_ms": N}. A step with no inputs is a pause. Total duration is capped at 60 s.
Inputs: steps (required), snapshot_after_ms.
show_viewerA
Open the live video window for a human (keyboard in that window drives the console too).
Inputs: no named parameters.
snapshotB
Current PS5 screen as a JPEG (scaled to max_width; the source is 1920x1080).
Inputs: max_width.
statusC
Payload link, payload version and counters, capture state and frame age.
Inputs: no named parameters.
stickC
Deflect the left or right stick. x, y in -1..1 (left/up negative), then return to centre.
Inputs: x (required), y (required), side (required), duration_ms (required), +1 more.
touchpadC
Click the touchpad. Coordinates are sent but not yet delivered by padd (touch mapping is unknown).
Inputs: x, y, duration_ms, snapshot_after_ms.
triggerC
Pull L2 or R2 (side: left/right) to value 0..1, then release.
Inputs: side (required), value (required), duration_ms (required), snapshot_after_ms.
uninstall_appsA
DESTRUCTIVE: uninstall installed titles by id (e.g. ["PPSA01325"]); their data is deleted.
Only uninstall what the user asked for by name. For titles ShadowMountPlus manages, their source folder or image is deleted too (otherwise it installs them again). The console refuses while a game is running; close_app first. Removal finishes in the background after each request is accepted. Needs padd 1.3 or later.
Inputs: title_ids (required).
wait_forB
Wait until a saved template appears on screen (or disappears, with gone=true).
Matching is normalised cross-correlation over the whole frame; score 1.0 is identical. Returns where it was found, the score and the frame.
Inputs: template (required), gone, min_score, timeout_ms.
wait_for_changeB
Wait until the screen changes (mean luma difference >= threshold on a 32x18 grid); returns the new frame.
Inputs: threshold, timeout_ms.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Tools are mostly distinct by resource and action: input primitives, capture, recordings, templates, app/file management, and console arbitration. Some overlap exists (hold vs sequence, home vs close_app, wait_for vs wait_for_change), but descriptions clarify boundaries well enough.
Names are consistently lowercase snake_case, with clear verb_noun or verb patterns for compound tools such as list_apps, claim_console, and wait_for_change. A few single-word or noun names (home, status, snapshot) break the verb pattern slightly but remain readable and conventional.
28 tools is high for an MCP server; many tools could be grouped by lifecycle area such as recordings, templates, file transfer, and console claims. Although the PS5 control domain is broad, the set is heavy and exceeds the 25-tool threshold for too many tools.
The surface covers core PS5 control lifecycle: input, screen capture/waiting, recording, templates, app launch/close/install/uninstall, file transfer, and console arbitration. Minor gaps remain, such as no delete operations for saved recordings/templates and no text-entry support, but these are workaround-able.
Related MCP Connectors
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Remote MCP server for AI.TV creators — delegate account operations to your AI agent over MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to work inside a live Unreal Editor for Fortnite session: write and compile Verse, place and wire Creative devices, edit Scene Graph entities, manipulate actors and assets, take screenshots, run playtests, and read editor logs via MCP.MIT
- FlicenseNot gradedqualityBmaintenanceEnables MCP clients to remotely control a real retro or legacy computer, including keyboard and mouse input, video capture, audio, power cycling, and file transfer, so agents can run tests against physical hardware.9-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to interact with real terminal sessions across local and remote hosts, driving multi-turn interactive programs like TUIs, REPLs, and SSH prompts through MCP.72MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to operate and view the Vega Virtual Device through MCP: press remote keys, take screenshots, record video with sound, wait for screen changes, and check the TV safe area.21 npmMIT