Codex Computer Run MCP Server

<!-- mcp-name: io.github.chrispulman/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, f