Oculus Debug MCP

A local Windows stdio MCP server that gives compatible AI assistants 32 tools, access to 86 discovered Oculus CLI commands, native VR screenshots, performance data, headset/controller diagnostics and reversible tuning controls.

Installation

Requires Windows, Python (tested with 3.13), and the Oculus/Meta Quest Link PC software. The server runs on the same Windows PC as the VR application. Meta executables and libraries are not bundled.

Clone or download this repository, then open PowerShell in its folder:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
$odt = (Get-Location).Path

For Claude Code, register it for your user account:

claude mcp add --transport stdio --scope user oculus_debug -- "$odt\.venv\Scripts\python.exe" "$odt\server.py"

Open a new Claude Code session and use /mcp to check the connection.

For Codex:

codex mcp add oculus_debug -- "$odt\.venv\Scripts\python.exe" "$odt\server.py"

Alternatively, ./install.ps1 creates the environment, installs dependencies and registers the server with Codex. Start a new task or restart the host to load the tools.

For Cursor and clients using mcpServers, merge this entry into the client's MCP configuration. Replace both example paths with the absolute path to your checkout. Cursor supports ~/.cursor/mcp.json or a project .cursor/mcp.json.

{
  "mcpServers": {
    "oculus_debug": {
      "command": "C:/path/to/oculus-debug-mcp/.venv/Scripts/python.exe",
      "args": ["C:/path/to/oculus-debug-mcp/server.py"]
    }
  }
}

VS Code uses a servers object in .vscode/mcp.json instead of mcpServers; add "type": "stdio" inside the server entry. Other local stdio MCP hosts can use the same executable and argument. Keep the checkout in place after registration. No API key or network listener is required.

See the official Claude Code, Cursor, and VS Code setup guides.

Example request:

Use oculus_debug to take a stereo screenshot and record five seconds of performance data from my running VR application. Explain any rendering or dropped-frame problems.

Save a baseline settings profile, then compare the same scene before and after a tuning change. Restore the baseline when finished.

Related MCP server: system-media-control-mcp

Tools

Screenshots

Screenshots use the installed OculusMirror.exe --Screenshot command. They capture VR content directly, without a visible desktop capture window. The MCP returns the PNG image content so the assistant can inspect it, and saves the original image and metadata locally. Generated screenshots and local verification reports are excluded from this repository.

The optional options object accepts these keys:

• Boolean flags: guardian, notifications, system_gui, disable_timewarp, symmetric_fov, disable_fov_stencil, native_resolution, flash_frame_drops, load_saved_settings.

• fov_multiplier: [horizontal, vertical], each 0.5–2.

Post-distortion mode cannot be combined with these optional flags. Use ordinary left/right/both-eye screenshots without options for an unmodified view. Some flags affect runtime rendering behavior or need an app restart. Image dimensions may be constrained by Mirror and the display.

Black frames are saved and labelled black_frame; they can mean an asleep headset, no active scene, a fade or protected content. Screenshot sequences include actual timestamps and an animated GIF. They are sequential snapshots, not high-speed video, and cannot establish the absence of brief flicker.

Verification

Development verification against a running PC VR application covered 32 tool registrations and 86 catalogue entries; a real PNG returned over MCP; SDK profiler frames; headset/controller state; runtime and Link reads; a same-value HUD write and baseline restoration; PNG/GIF sequence generation; owned Mirror start/stop; and diagnostic ZIP creation. The stereo view was visually inspected. Twelve automated tests cover capture lifetime, black/idle samples, units, type/range checks, profile comparisons and command boundaries.

Local recordings and verification reports are not distributed. Run the verification scripts below to collect evidence on your own setup.

Service interruption, deliberate hardware failures, advanced passthrough experiments and Link encoder changes were not executed during development testing. Their commands/settings were discovered and exposed; hardware support and effects remain dependent on the runtime and headset.

Interpreting captures

ok means application timing samples were present. compositor_only means the compositor produced frames but the capture had no application timing samples; this can happen while the app is idle or the headset sleeps. no_samples means no frames were captured. Missing application timings are reported as null, never as evidence of zero-cost rendering.

The reported frame rate comes from compositor event timestamps; it is not necessarily the application's frame rate. Raw timing fields are in seconds; summary rendering durations are converted to milliseconds. Compare the same scene under similar conditions and for similar durations. Lost-frame counts depend on recording duration.

Scope and limitations

This connects to the installed Oculus/Meta Quest Link PC runtime. It reads controller state but does not play games, move the physical headset, inspect game source or debug standalone Quest applications. The native API uses an invisible diagnostic session, so its own IsVisible flag is not the game's visibility flag. Check tracking validity flags before using poses, and treat reported headset model names as possible compatibility identities.

The CLI stays alive throughout recording; exiting after the start command prematurely ends the capture. Output uses relative filenames because the installed CLI did not accept quoted capture paths. Captures and settings are serialized across this server's instances. Oculus's telemetry facility is shared, so avoid simultaneous recording from another Oculus tool.

Prefer get_runtime_settings and set_runtime_setting for tuning: the native API provides readback for the named runtime/HUD properties. The original CLI convenience tools retain their delivery-only reporting. pose_injection uses its supported CLI setter plus native readback because the direct property setter is read-only on this build. Reading back a property proves the stored runtime value, not the application's rendered result; verify effects with measurements/screenshots.

Runtime setting writes save a narrow baseline for the setting being changed. Full profiles also preserve ASW and user/machine Link observations. Restoration changes only differing values, removes user Link overrides that were absent at capture time, creates an undo profile, and reports individual failures. It is not atomic. Defaults are not a substitute for an unknown prior custom setting.

Link settings use the registry keys embedded in the installed Debug Tool. The API exposes raw integer values rather than guessing GUI enum labels. It verifies the user registry value and leaves the machine values alone. This does not verify the active encoder state; Link changes generally require a service restart, which is never automatic.

control_service can explicitly start/stop/restart Oculus, subject to Windows privileges. Stop/restart interrupts active VR. Advanced CLI commands include ASW experiments, passthrough diagnostics, emulation and deliberate camera failure simulation. Use them only for an intended experiment after reading command_help. The MCP never changes OpenXR runtime registrations.

Coverage boundaries

The catalogue covers every client subcommand and server command returned by this installed CLI's help. Managed telemetry start and allocator trace calls are routed through dedicated tools for correct recording lifetime and file handling. The catalogue is a snapshot of ODT 85.0.0.0.549; it should be rediscovered after substantial Oculus updates.

Features with no verified unattended interface remain available through the original GUI: ODA archive editing/viewing, the Scene View's interactive camera controls, Mirror image-stabilization/override-view menus, proximity-sensor bypass and custom trace-merge scripts. open_diagnostic_utility can open the original tools, but does not pretend to automate those features. Log Gatherer is opened interactively and no log upload is submitted. The original ETW helper scripts and application validator workflows are not run automatically.

Files and troubleshooting

Raw captures, images, profiles, CSV files, bundles and the setting audit log stay locally under captures/. Logs can include local paths and device identifiers. There is no network listener or telemetry upload in this server. CLI subprocesses have timeouts and run without a command shell. Native runtime API work is isolated in disposable worker processes.

The Meta Quest Link service must be available. In testing, sandboxed Oculus CLI execution timed out while ordinary execution connected successfully. A timeout message reports this possibility rather than claiming that no headset exists.

If Oculus is installed elsewhere, set OCULUS_DIAGNOSTICS_DIR to the folder containing OculusDebugToolCLI.exe in the MCP server environment. Installation discovery also checks the Oculus installation registry and the standard Program Files location.

Run install.ps1 from PowerShell to recreate dependencies and registration if needed. Python 3.13 was used for testing. To remove the Codex registration, run codex mcp remove oculus_debug; this preserves all captured files.

For developers:

.\.venv\Scripts\python.exe -m unittest -v
.\.venv\Scripts\python.exe .\verify_live.py
.\.venv\Scripts\python.exe .\verify_extended.py

verify_live.py takes two short recordings and reapplies the current ASW setting when it is auto or off. It saves the resulting MCP evidence to verification.json.

verify_extended.py tests the expanded tools, captures screenshots/profiler data, reapplies the existing HUD value and restores its saved baseline. It does not test service interruption or encoder changes. It saves evidence to verification-extended.json.

References

Controls were checked against the help output of the locally installed OculusDebugToolCLI.exe. Meta documents the Debug Tool's performance HUD and runtime diagnostic purpose in Oculus Debug Tool. Registration follows the official Codex MCP documentation.

Mirror options were checked against the installed binary and Meta's Compositor Mirror documentation. Native data layouts were checked against the Oculus C API header and the published ovr-sys 1.15 ABI bindings, then verified against this PC's runtime.