# Codex CUA MCP

[中文版](README_CN.md)

💬 [LINUX DO Discussion](https://linux.do/t/topic/2490658)

Wraps Codex's Computer Use capability as an MCP server, enabling AI agents to control Windows desktop applications.

## Features

- List and control Windows desktop applications
- Capture screenshots and accessibility trees
- Click, type, press keys, scroll, drag, and more
- Launch apps and activate windows
- **Ready to use** - exe bundled, no extra setup needed

## Quick Start

Hand the install doc to your AI agent — send this prompt:

```
Please clone the repository https://github.com/RS-Nocsi/codex-cua-mcp locally, read its INSTALL.md, and install this MCP server into your own MCP configuration by following it.
```

Your agent (Claude Code, Cursor, Windsurf, Cline, OpenCode, Gemini CLI, etc.) will clone the repo, check prerequisites, build the project, and register the server itself. Fully restart the agent afterwards.

Prefer manual setup? Follow [INSTALL.md](INSTALL.md) yourself.

## How It Works

```
AI Agent (Claude Code, Cursor, etc.)
  ↓ MCP protocol (stdio)
MCP Server (codex-cua-mcp)
  ↓ JSON-RPC (stdin/stdout)
codex-computer-use.exe
  ↓ Windows APIs
Desktop Applications
```

The MCP server communicates with `codex-computer-use.exe` via JSON-RPC over stdin/stdout. The exe uses Windows APIs (SendInput, UI Automation, Windows.Graphics.Capture) to interact with desktop applications.


### Dynamic agent name

The desktop overlay shows which agent is controlling the computer (e.g. "Claude Code is using your computer"). Please set the `CUA_AGENT_NAME` environment variable to your own display name in the registration — see [INSTALL.md](INSTALL.md) Step 4. Each agent has its own runtime config under `config-runtime/`; multiple agents can install this MCP simultaneously without conflict.

> 📖 Want to understand the design in depth? Read the [Architecture Deep Dive](docs/ARCHITECTURE.md).

## Available Tools

| Tool | Description |
|------|-------------|
| `list_windows` | List all controllable windows |
| `list_apps` | List installed apps |
| `get_window` | Rehydrate a window object |
| `launch_app` | Launch an application |
| `activate_window` | Bring window to foreground |
| `get_window_state` | Screenshot + accessibility tree |
| `click` | Click |
| `type_text` | Type text |
| `press_key` | Press key |
| `scroll` | Scroll |
| `drag` | Drag |
| `set_value` | Set input field value |
| `perform_secondary_action` | Secondary action (right-click menu, etc.) |

## Disclaimer

The core capability comes from `codex-computer-use.exe`. Actual results depend on the AI agent and model used — no usability guarantee.

## Requirements

- Windows 10/11
- Node.js 18+

## License

MIT