Codex Computer Run MCP server

Codex Computer Run MCP Server

Codex Computer Run MCP Server gives Codex and other MCP-capable agents direct control over a signed-in desktop session. It exposes focused tools for screenshots, mouse movement, clicks, scrolling, keyboard shortcuts, Unicode text entry, metadata-based window targeting, bounded filesystem organization, and local Git workflows, plus a bundled Codex Skill for safe desktop-use workflows.

It is implemented in C# on net10.0 using ModelContextProtocol 2.2.0. Package versions are calculated by MinVer from v-prefixed Git tags, with a 1.2 minimum major/minor version. Release builds stamp the MCP manifest with the package version. The package targets plain net10.0 so it can be distributed as a .NET tool. Windows uses native Win32 APIs; Linux and macOS use best-effort command-backed adapters.

Quick Install

Click to install in your preferred environment:

Note:

• These install links are prepared for the intended NuGet package identity CP.CodexComputerRun.Mcp.Server.
• If the latest package has not been published yet, use the manual source-build or published-executable configuration below.
• Run the server from the signed-in desktop session you want to control. Windows desktop automation must be launched from Windows, not WSL.
• Linux X11 sessions use xdotool and wmctrl where available. Wayland sessions use wdotool for pointer, keyboard, and window actions, plus a compositor-compatible screenshot command such as grim, gnome-screenshot, or KDE's spectacle. Install the command-line tools in the same signed-in graphical session as the MCP server.
• macOS support uses screencapture, pbcopy, and osascript; pointer actions require cliclick. Screen Recording and Accessibility permissions may be required by macOS.

What Codex Computer Run Helps With

Codex Computer Run gives an agent a minimal, fast desktop-control layer for:

• Observe the full desktop via PNG screenshots with an optional red cursor halo on Windows.
• Point the real cursor at absolute virtual-screen coordinates, instantly or along a visible timed path.
• Click left, right, or middle mouse buttons where supported, including repeated clicks. The built-in macOS adapter supports left and right clicks.
• Scroll the wheel at the current cursor position or supplied coordinates.
• Press single keys and keyboard shortcuts such as ctrl+l or ctrl+shift+escape.
• Enter Unicode text through the platform's preferred text-entry path.
• Inspect cursor position and visible top-level windows.

The server is designed for Codex computer-use workflows where the MCP client controls the active desktop.

Platform Support

Windows remains the primary implementation. Linux and macOS support keeps the same MCP tool surface but depends on external desktop commands that must be available inside the active graphical session.

Area	Current behavior
Version	MinVer from Git tags (minimum major/minor 1.2)
Target framework	net10.0
Windows	Native Win32 implementation with virtual-screen capture, a red cursor halo in screenshots, direct Unicode SendInput, cursor position, and visible top-level window enumeration
Linux	Command-backed adapter using xdotool/wmctrl on X11 or wdotool on Wayland, with compositor-compatible screenshot commands
macOS	Command-backed adapter using screencapture, pbcopy, osascript, and cliclick; macOS middle-click automation is not supported by the built-in adapter
Unsupported OS	Deterministic unsupported-platform errors instead of silent no-ops
Session requirement	Signed-in interactive desktop session
Transport	MCP stdio

Do not run this server from WSL to control a Windows desktop. Building from WSL through Windows dotnet.exe can work, but the MCP server itself must be launched by a Windows MCP client or Windows PowerShell session.

Linux Wayland

Wayland sessions are detected from XDG_SESSION_TYPE=wayland or WAYLAND_DISPLAY. Install wdotool for desktop input and window actions, and install a screenshot utility supported by the compositor (for example, grim on wlroots compositors, gnome-screenshot on GNOME, or spectacle on KDE Plasma). The MCP server must inherit the graphical session environment.

Compositors control which desktop information they expose. cursor_position reports an actionable unsupported error when the compositor does not provide the global pointer position; move_mouse still moves to its target and falls back to a direct move when it cannot query a starting point. On GNOME, wdotool window discovery and other window controls require its companion Shell extension; its portal input backend may show a first-use permission prompt. Screenshot bounds are derived from the captured PNG when compositor geometry is unavailable. Exact rectangular screenshots require grim; GNOME Screenshot and Spectacle are used for full-desktop capture. Multi-monitor Wayland coordinate layouts have not been verified; screenshot bounds are currently reported from image size at origin (0, 0).

Some Wayland backends do not expose a process ID for each window. In that case, window discovery, title matching, activation, and closing still work; process-name filters cannot match those windows.

Codex Protocol

When this server is active, agents should follow this operating protocol:

1. Call screenshot first when visual context matters.
2. Use cursor_position before relative manual reasoning about the current pointer location.
3. Use list_windows to identify visible applications before focusing or interacting with them.
4. Use move_mouse, click, scroll, press_key, hotkey, and type_text only when the intended foreground application is known.
5. Prefer type_text for text entry because Windows uses direct Unicode input without changing the clipboard; Linux/macOS use their available native text-entry fallback.
6. Keep screenshots small in conversation by setting include_image to false when only dimensions, platform metadata, or a saved path are needed.

Codex Skill

The repository and NuGet package include a Codex Skill at skills/codex-computer-run. The skill teaches Codex the observation-first workflow, safety rules, and exact MCP tool names for this server.

When the packaged server starts, it installs or refreshes the bundled skill in CODEX_HOME/skills/codex-computer-run, or %USERPROFILE%\.codex\skills\codex-computer-run when CODEX_HOME is unset. Automatic installation requires the Codex home directory to exist. Files supplied by the package are refreshed when their contents change, so updating the MCP server and starting it also updates the skill. Keep personal customizations in a separate skill because bundled files are managed by the server. Installation diagnostics go to standard error, and installation failures do not prevent MCP startup.

Manual install from a globally installed tool:

dotnet tool install --global CP.CodexComputerRun.Mcp.Server --version 1.*
codex-computer-run-mcp-server --install-codex-skill

Manual install from source:

dotnet run --project .\src\CodexComputerRunMCPServer\CodexComputerRunMCPServer.csproj -- --install-codex-skill

Set CODEX_HOME first if Codex uses a non-default location:

$env:CODEX_HOME = "C:\Users\you\.codex"
codex-computer-run-mcp-server --install-codex-skill

The explicit installer preserves existing files unless you add --force. Normal MCP startup automatically refreshes the bundled files.

Use the skill in Codex by asking for it explicitly, for example:

Use $codex-computer-run to list visible windows, take a screenshot, and confirm the active desktop state.

Available MCP Tools

screenshot

Captures the current desktop as PNG.

Parameters:

• path (optional) - output PNG path. If omitted, the image is returned in memory and no temporary file is created.
• include_image (default: true) - include PNG image data in the MCP tool result.
• left, top, width, height (optional) - capture only a screen-space region. Provide all four values together; width and height must be greater than zero.
• highlight_cursor (default: true) - draw a red halo at the live cursor position in the captured image on Windows. Set to false for an unmarked capture.

Response: The first content block is JSON metadata with message, path, mimeType, platform, left, top, width, and height. When include_image is true, a PNG image block is also returned.

When a region is supplied, the metadata bounds describe that region instead of the full virtual desktop. Region coordinates use the same virtual-desktop screen space as window bounds returned by list_windows.

When to use: Use before interacting with the desktop, after UI changes, or when the agent needs visual confirmation.

---

move_mouse

Moves the cursor to absolute desktop coordinates.

Parameters:

• x - absolute X coordinate.
• y - absolute Y coordinate.
• duration_ms (default: 350) - move along the path over 0–10000 milliseconds. Use 0 for an instant move.
• delay (optional) - seconds to wait after the action.

When to use: Use before a click or hover-sensitive action.

---

click

Clicks at the current cursor position or at supplied absolute coordinates.

Parameters:

• x (optional) - absolute X coordinate.
• y (optional) - absolute Y coordinate.
• button (default: left) - left, right, or middle; middle is not supported by the built-in macOS adapter.
• clicks (default: 1) - number of clicks.
• interval (default: 0.08) - seconds between repeated clicks.
• delay (optional) - seconds to wait after the action.

When to use: Use for buttons, menus, tabs, context menus, and desktop UI selection.

---

scroll

Scrolls the mouse wheel.

Parameters:

• amount (default: -3) - wheel notches. Positive scrolls up, negative scrolls down.
• x (optional) - absolute X coordinate to move to before scrolling.
• y (optional) - absolute Y coordinate to move to before scrolling.
• delay (optional) - seconds to wait after the action.

When to use: Use for lists, pages, combo boxes, and scrollable application panes.

---

press_key

Presses one keyboard key. On Windows and Linux, named system media and volume keys can control the active media session without focusing its window.

Parameters:

• key - key name or single character, for example enter, tab, escape, f5, a, A, ?, or 1. Media keys: media_play_pause, media_next_track, media_previous_track, and media_stop. Volume keys: volume_mute, volume_down, and volume_up.
• duration (default: 0.03) - seconds to hold the key.
• delay (optional) - seconds to wait after the action.

When to use: Use for navigation keys, function keys, confirm/cancel actions, and single-character shortcuts. For global media and volume controls, omit target_handle; Windows sends the system media key and Linux maps it to the corresponding XF86Audio* key. The built-in macOS adapter reports an explicit unsupported-platform error for these keys.

---

hotkey

Presses a keyboard shortcut.

Parameters:

• keys - shortcut text using +, comma, or space separators, for example ctrl+l, ctrl+shift+escape, or alt+tab.
• delay (optional) - seconds to wait after the action.

When to use: Use for application shortcuts, browser address bar focus, task switching, command palettes, and system shortcuts.

---

type_text

Enters Unicode text into the focused application. On Windows it emits Unicode keyboard events directly and does not modify the clipboard; other platforms use their available native fallback.

Parameters:

• text - text to enter.
• delay (optional) - seconds to wait after the action.

When to use: Use for text fields, editors, terminals, and any non-trivial text entry.

---

cursor_position

Returns the current desktop cursor position as JSON.

When to use: Use before or after mouse actions when the agent needs exact coordinates.

---

list_windows

Lists visible top-level desktop windows as JSON.

Parameters:

• limit (default: 50) - maximum number of windows to return.

When to use: Use to identify visible applications and window titles before interacting with the desktop.

Each window entry also includes isForeground, isMinimized, and bounds when the platform can provide them. bounds contains left, top, width, and height in virtual-desktop screen coordinates. Use these fields to confirm the intended process and target window before relying on coordinates; a title match alone is not sufficient when multiple windows are open.

---

find_windows

Finds visible top-level windows by optional process name, title substring, foreground state, and minimized state. Matching is case-insensitive for process names and title text.

Parameters:

• process_name (optional) - process name such as Notepad or msedge.
• title_contains (optional) - case-insensitive substring of the window title.
• foreground_only (optional) - return only windows reported as foreground.
• include_minimized (optional) - include minimized windows; defaults to true.
• limit (optional) - maximum number of matches; defaults to 50.

When to use: Prefer this when several windows are open and a process/title predicate is more reliable than choosing by screen coordinates. Re-check the returned handle immediately before a data-bearing action because window handles can become stale.

---

screenshot_window

Captures the screen-space bounds of a visible window selected by native handle. It uses the bounds returned by list_windows or find_windows; it does not reveal pixels hidden behind another window.

Parameters:

• handle - native window handle returned by list_windows or find_windows.
• path (optional) - output PNG path.
• include_image (optional) - include PNG bytes in the MCP result; defaults to true.
• highlight_cursor (default: true) - draw the red cursor halo on Windows; set to false to omit it.

When to use: Use after targeting a window when the agent needs a focused visual observation or wants to avoid capturing the entire multi-monitor desktop.

---

verify_window

Checks whether a native window handle still identifies the expected process, title, foreground state, and minimized state. It is observation-only and returns JSON with ok, reason, and current metadata.

Parameters:

• handle - native window handle returned by list_windows or find_windows.
• process_name (optional) - expected process name.
• title_contains (optional) - expected title substring.
• require_foreground (optional) - require current foreground focus.
• allow_minimized (optional) - allow a minimized match; defaults to true.

When to use: Call immediately before an input-changing action when a handle may have become stale, and after a meaningful transition when you need a machine-readable postcondition.

---

wait_for_window

Waits for a visible window matching optional process, title, foreground, and minimized-state filters. It never sends input and is bounded to 30 seconds; a single failed window enumeration is retried because the query is idempotent.

Parameters:

• process_name, title_contains, foreground_only, include_minimized - same targeting filters as find_windows.
• timeout_ms (optional) - maximum wait from 0 to 30000 milliseconds; defaults to 5000.
• poll_ms (optional) - polling interval from 25 to 1000 milliseconds; defaults to 100.

When to use: Use after launching an identified application or waiting for a known window to return after a crash. Do not use a retry loop around clicks, keystrokes, or text entry because repeating those could duplicate a user action.

---

activate_window

Brings a previously enumerated window to the foreground by its native handle.

Parameters:

• handle - native window handle returned by list_windows.
• restore (default: true) - restore the window first when it is minimized.

When to use: Call list_windows first, verify the process and title, then activate the exact handle before sending input. Windows uses the native window handle and waits until the OS reports that handle as foreground; Linux uses wmctrl or xdotool; the current macOS adapter reports a clear unsupported error because its window listing does not expose stable native handles.

---

close_window

Requests a graceful close for one exact top-level window handle. The operation posts the platform's normal close request and then checks whether that handle disappeared. It never terminates the owning process. If the application presents a save dialog or rejects the request, the result contains closed:false and explains that the window is still present.

Parameters:

• handle - native window handle returned by list_windows or find_windows.
• timeout_ms (optional) - bounded wait from 0 to 5000 milliseconds; defaults to 1000.

When to use: Use only after identifying the exact window and confirming that closing it is intended. Prefer this over sending alt+f4, because a stale foreground can route a global shortcut to another application.

---

Targeted desktop input

move_mouse, click, scroll, press_key, hotkey, and type_text accept an optional target_handle. When supplied, the server re-enumerates that exact window immediately before input and sends nothing if it is missing or minimized; clicks, scrolling, and keyboard input additionally require it to be foreground. This turns a focus race into a safe, actionable error. The recommended sequence is find_windows → activate_window → input with target_handle. Global media and volume keys intentionally act on the system's media session, so leave target_handle unset for those.

---

Filesystem operations

The filesystem tools make the server useful for general desktop work such as organizing folders. list_directory is observation-only, uses an entry limit, and does not follow reparse points during recursive scans. read_text_file reads bounded UTF-8 content without changing the file. create_directory, copy_path, move_path, delete_path, and write_text_file default to dry_run:true, returning a normalized plan without changing anything. To apply a mutation, the caller must explicitly pass dry_run:false for the exact path that was inspected.

copy_path and move_path use an exact destination rather than silently treating it as a parent directory. Existing destination directories are never merged, and directories cannot be moved or copied into themselves. delete_path is permanent and requires dry_run:false; non-empty directories also require recursive:true. Dry-run plans do not claim the desktop-control lease, so several safe inspections/plans can run concurrently; the lease is acquired only when a mutation is actually applied. The skill still requires confirmation immediately before destructive deletion when the surrounding user task has not explicitly authorized that exact deletion.

Semantic UI controls

find_ui_elements inspects one exact native window through Windows UI Automation and searches by accessible name, role, or AutomationId. It returns a runtime element id, accessible metadata, bounds, and supported patterns such as invoke, toggle, select, value, and expandCollapse. invoke_ui_element and set_ui_value re-resolve the element inside the same window immediately before acting, so a stale element id fails instead of being redirected to a different control. The adapter currently requires Windows UI Automation; non-Windows builds return an explicit unsupported-platform error.

Browser-targeted controls

When a Chromium browser is started with a local --remote-debugging-port, list_browser_tabs returns exact page target ids, titles, URLs, and debugger endpoints. wait_for_browser_navigation waits for one target or URL/title condition with a bounded timeout. inspect_browser_accessibility uses CDP's accessibility tree and returns ax:<nodeId> ids with roles, names, values, relationships, and DOM mappings. click_browser_element and set_browser_value re-inspect the same target immediately before acting; setting a value dispatches input/change but does not press Enter or submit a form. open_browser_devtools returns the exact inspector URL and only opens it when open:true is supplied. The server accepts only loopback DevTools endpoints and refuses remote WebSocket URLs. Normal browser tabs that were not started with remote debugging remain available to the existing desktop/window tools but are not silently attached through CDP.

Local Git operations

git_status, git_init, git_clone, git_create_branch, and git_commit provide bounded local repository workflows. git_status is observation-only. The other four default to dry_run:true; they return the exact repository, branch, destination, or commit plan and do not contact a remote until a caller explicitly applies the operation. Git arguments are passed directly to the process runner rather than through a shell, so spaces and punctuation in paths or commit messages stay data instead of becoming commands. There is intentionally no automatic push or remote repository deletion in this layer.

Processes and browser entry points

list_processes and wait_for_process provide bounded observation for recovery workflows. launch_application accepts an executable plus an argument list without shell parsing and defaults to dry_run:true. When applied, its returned PID is best-effort: GUI launchers and browsers may reuse an existing process or hand work to another process. Use wait_for_window plus a specific title/process identity to find the window the user actually sees. open_url accepts only absolute http or https URLs and also defaults to dry_run:true; when explicitly applied, the operating system's default browser handles the URL and any returned PID is likewise best-effort. These tools do not terminate processes and do not implement a force-kill fallback.