Skip to main content
Glama
Sign In
codex-computer-use-linux

codex-computer-use-linux

by maxionice
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Codex Computer Use for Linux is an open-source Linux computer-use MCP server and Codex skill for controlled desktop GUI automation. It gives Codex a deliberately small tool surface for working with visible native applications while keeping sensitive workflows out of scope.

IMPORTANT

This is an independent community project. It is not made, supported, or endorsed by OpenAI and does not claim feature parity with OpenAI Computer Use.

OpenAI's current Computer Use plugin supports macOS and Windows, while Codex can connect to local STDIO MCP servers. This project fills the Linux integration gap with an MCP action layer and a skill that teaches Codex the safe observe → act → verify loop. See the official Computer Use and MCP documentation for the product boundaries.

Why MCP plus a skill?

Layer

Responsibility

MCP server

Executes typed, bounded Linux desktop actions and reports capability errors.

Codex skill

Chooses safe action sequences, verifies UI state, and stops on sensitive flows.

Plugin

Packages the skill and MCP connection for repeatable installation.

A skill alone cannot reliably provide live screenshots or controlled input. An MCP server alone does not teach the model a safe visual workflow. The hybrid plugin follows OpenAI's documented plugin architecture.

Related MCP server: desk-mcp

What it does

  • Linux-only runtime guard; no silent macOS or Windows fallback.

  • Wayland input through ydotool; X11 input through xdotool with ydotool fallback.

  • Screenshots through grim, gnome-screenshot, scrot, or ImageMagick import.

  • Typed MCP tools for status, screenshot, pointer movement, click, drag, text, keys, and scroll.

  • No arbitrary shell tool, application launcher, clipboard reader, or secret store access.

  • Best-effort blocking of terminals, ChatGPT, and Codex when the active window is discoverable.

  • Structured Doctor output and in-memory MCP contract tests.

  • Installable Codex plugin plus direct MCP-server setup.

Quick start

Requirements

  • Linux with an active graphical session.

  • Python 3.11 or newer.

  • One screenshot backend.

  • One input backend.

Session

Screenshot

Input

Notes

Wayland

grim or gnome-screenshot

ydotool

ydotoold needs access to /dev/uinput.

X11

gnome-screenshot, scrot, or import

xdotool

ydotool is an optional fallback.

Install only the packages relevant to your desktop. Typical package names are:

# Debian / Ubuntu
sudo apt install python3 python3-venv xdotool gnome-screenshot ydotool grim

# Fedora
sudo dnf install python3 xdotool gnome-screenshot ydotool grim

# Arch Linux
sudo pacman -S python xdotool gnome-screenshot ydotool grim

Package availability differs by distribution and desktop environment. On Wayland, configure and start ydotoold according to your distribution. The upstream ydotool documentation explains its /dev/uinput permission model; do not run Codex itself as root.

Install

Install the server CLI with one of these isolated Python tool managers:

uv tool install git+https://github.com/maxionice/codex-computer-use-linux.git

or:

pipx install git+https://github.com/maxionice/codex-computer-use-linux.git

Run the Doctor before connecting Codex:

codex-computer-use-linux --doctor

Option A: install the Codex plugin

codex plugin marketplace add maxionice/codex-computer-use-linux
codex plugin add codex-computer-use-linux@maxionice-linux-tools

Start a new Codex thread after installing so the skill and MCP tools are loaded.

Option B: add only the MCP server

codex mcp add linux-desktop -- codex-computer-use-linux
codex mcp list

For approval on input-producing tools, configure default_tools_approval_mode = "writes" for the server in ~/.codex/config.toml.

Example prompts

Use $use-linux-desktop to open the app's settings and verify that dark mode works.
Inspect the visible calculator app, enter 125 * 8, and report the displayed result.
Reproduce the onboarding bug in the already-open Linux app. Stop before any login prompt.

MCP tools

Tool

Effect

desktop_status

Reports session, available backends, active window, and warnings.

take_screenshot

Returns the current desktop as PNG image content.

move_pointer

Moves the pointer to absolute screenshot coordinates.

click

Moves and clicks left, middle, or right.

drag_pointer

Drags between two absolute coordinates.

type_text

Types bounded plain text into the focused control.

press_key

Presses a named key with optional modifiers.

scroll

Scrolls on X11; Wayland users can use Page Up/Down through press_key.

The server never accepts a command string or invokes a shell. Every native command is constructed from validated typed arguments.

Safety model

Desktop automation can act with your logged-in user's permissions and screenshots may contain sensitive data. Keep the target app visible, close unrelated sensitive apps, and review every approval prompt.

The bundled skill refuses terminal, ChatGPT, Codex, credential, administrator, security, payment, and privacy-setting flows. Active-window blocking is best effort because some Wayland compositors do not expose the focused application. Read the complete safety model before use.

Development

git clone https://github.com/maxionice/codex-computer-use-linux.git
cd codex-computer-use-linux
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m ruff format --check .
python -m ruff check .
python -m mypy src
python -m pytest

The project uses the stable MCP Python SDK 2.x, which supports the 2026-07-28 MCP specification. See the official MCP Python SDK.

Uninstall and rollback

codex plugin remove codex-computer-use-linux
codex plugin marketplace remove maxionice-linux-tools
codex mcp remove linux-desktop
uv tool uninstall codex-computer-use-linux

If you installed with pipx, replace the final command with pipx uninstall codex-computer-use-linux. Removing the plugin or MCP entry stops Codex from launching the server; removing the tool installation deletes the local executable. System packages such as ydotool are not removed automatically.

Trademark and affiliation

This is an independent open-source project and is not affiliated with or endorsed by OpenAI. OpenAI, Codex, ChatGPT, and related marks belong to their respective owners.

License

Apache-2.0. See LICENSE.

Available Tools

8 tools
clickClick the Linux desktopA

Move to absolute screenshot coordinates and click a mouse button. Use one click unless the visible control clearly requires a double-click.

Inputs: x (required), y (required), count, button, +1 more. Returns: Result of one bounded input action.

desktop_statusInspect Linux desktop capabilitiesA
Read-onlyIdempotent

Call first to detect Wayland or X11, screenshot and input backends, the active window, and safety warnings. This does not capture the screen or send input.

Inputs: no named parameters. Returns: Detected Linux desktop capabilities.

drag_pointerDrag on the Linux desktopA

Drag a mouse button between two absolute coordinates from the latest screenshot.

Inputs: end_x (required), end_y (required), start_x (required), start_y (required), +1 more. Returns: Result of one bounded input action.

move_pointerMove the desktop pointerA
Idempotent

Move the pointer to absolute coordinates from the latest screenshot.

Inputs: x (required), y (required). Returns: Result of one bounded input action.

press_keyPress a keyboard keyA

Press one allow-listed key with optional ctrl, alt, shift, or super modifiers in the focused Linux app.

Inputs: key (required), modifiers, interval_ms. Returns: Result of one bounded input action.

scrollScroll the X11 desktopA

Scroll vertically by a small number of steps. Positive scrolls up and negative scrolls down. On Wayland use press_key with PAGEUP or PAGEDOWN instead.

Inputs: steps (required). Returns: Result of one bounded input action.

take_screenshotTake a desktop screenshotA
Read-onlyIdempotent

Capture the current Linux desktop as PNG image content. Use before choosing coordinates and again after every action that changes visible state.

Inputs: no named parameters.

type_textType text into the focused controlA

Type bounded plain text into the currently focused control. Never pass passwords, tokens, recovery codes, payment data, or terminal commands.

Inputs: text (required), interval_ms. Returns: Result of one bounded input action.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.1/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct action: status inspection, screenshot capture, pointer movement, clicking, dragging, typing, key pressing, and scrolling. No two tools have overlapping purposes; even move_pointer and click are clearly differentiated by the act of clicking.

    Naming Consistency3/5

    Most tools follow a verb_noun pattern (take_screenshot, move_pointer, drag_pointer, type_text, press_key), but 'click' is a bare verb and 'desktop_status' is a noun phrase. This inconsistency in naming style is noticeable but still readable.

    Tool Count5/5

    Eight tools cover the essential actions for computer use on Linux without being excessive. Each tool serves a distinct purpose, and the count is well within the ideal 3-15 range.

    Completeness4/5

    The surface covers the core actions: observing the screen, moving the pointer, clicking, dragging, typing, pressing keys, and scrolling. Minor gaps exist, such as no explicit method to retrieve the current cursor position or handle clipboard, but these are not critical for the primary purpose.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • desk-mcp

      KpihX
      A
      license
      Not graded
      quality
      D
      maintenance
      A desktop automation MCP server that enables AI agents to interact with Linux environments through screenshots, window inspection, and input simulation. It provides tools for mouse control, keyboard input, and screen capture using xdotool and XDG Desktop Portals.
      MIT

    • gnome-ui-mcp

      asattelmaier
      A
      license
      Not graded
      quality
      C
      maintenance
      Small MCP server for GNOME Wayland desktop automation, enabling element lookup, activation, typing, screenshots, and wait helpers through AT-SPI and Mutter RemoteDesktop.
      1
      MIT

    • computer-use-linux

      agent-sh
      A
      license
      Not graded
      quality
      A
      maintenance
      Controls a real Linux desktop from any MCP host. Reads accessibility trees, takes screenshots, and drives clicks, scrolls, and keystrokes across GNOME, KDE/KWin, Hyprland, i3, and COSMIC.
      3,672 npm
      852
      MIT