# Windows Computer Use MCP

A local, dependency-free MCP server that gives a compatible CLI or IDE agent controlled access to the active Windows desktop. It works with **Codex CLI**, **Claude Code CLI**, and **Google Antigravity** because all three support local stdio MCP servers.

The server captures screenshots, lists visible windows, and can launch, focus, click, type, send keys, and request a normal window close. It does not bypass Windows UAC, the lock screen, or secure-desktop prompts.

## Requirements

- Windows with an unlocked, active desktop session
- Node.js 20 or later (`node --version`)
- One of Codex CLI, Claude Code CLI, or Antigravity

No npm packages are required.

## Safety configuration

Before granting control, copy [config.example.json](./config.example.json) to `config.json`, then edit the local copy. Only executable names in `allowedApps` may be launched, focused, clicked, typed into, sent keys, or closed. The initial allowlist is intentionally empty.

```powershell
Copy-Item config.example.json config.json
```

```json
{
  "allowedApps": ["notepad.exe", "msedge.exe", "code.exe"]
}
```

`computer_screenshot` and `computer_list_windows` are read-only. A screenshot can contain any information visible on the desktop and may be sent to the model, so close sensitive material first.

## Tools

| Tool | Purpose |
| --- | --- |
| `computer_screenshot` | Capture the primary display as a PNG. |
| `computer_list_windows` | List visible top-level windows, titles, process names, and handles. |
| `computer_launch_app` | Launch an allowlisted executable. |
| `computer_focus_window` | Focus an allowlisted visible window. |
| `computer_click` | Click an absolute coordinate in an allowlisted foreground app. |
| `computer_type_text` | Type text into the allowlisted foreground app. |
| `computer_press_key` | Send a SendKeys sequence, such as `{ENTER}`, `^s`, or `%{F4}`. |
| `computer_close_window` | Request a normal close for an allowlisted window. |

The model should take one small action, take a new screenshot, and verify the result. Do not allow it to handle passwords, payment flows, healthcare systems, or irreversible actions without direct supervision.

## Configure Codex CLI

This machine is already registered globally. To add it on another machine:

```powershell
codex mcp add windows-computer-use -- node C:\Users\YOUR_USER\windows-computer-use-mcp\windows-computer-use.mjs
```

Verify it:

```powershell
codex mcp get windows-computer-use
```

Start a new Codex CLI session after adding it. Example prompt:

```text
Use computer_launch_app to open notepad.exe, then take a screenshot and stop.
```

## Configure Claude Code CLI

Register it for all your Claude Code projects:

```powershell
claude mcp add --transport stdio --scope user windows-computer-use -- node C:\Users\YOUR_USER\windows-computer-use-mcp\windows-computer-use.mjs
```

Verify the connection with:

```powershell
claude mcp list
```

Then open a new Claude Code session and use `/mcp` to inspect its status. To make the configuration project-specific instead, copy [`examples/claude-code.mcp.json`](./examples/claude-code.mcp.json) to the project root as `.mcp.json`, replace `YOUR_USER`, and approve it in Claude Code.

## Configure Antigravity

In Antigravity IDE, open the agent side panel, select **More actions > MCP Servers > Manage MCP Servers > View raw config**, then add this server to the `mcpServers` object:

```json
{
  "windows-computer-use": {
    "command": "node",
    "args": ["C:\\Users\\YOUR_USER\\windows-computer-use-mcp\\windows-computer-use.mjs"],
    "cwd": "C:\\Users\\YOUR_USER\\windows-computer-use-mcp"
  }
}
```

Replace `YOUR_USER`, save, then reload the server in the MCP Servers panel. The global Antigravity configuration is `~/.gemini/config/mcp_config.json`; for a workspace-only setup use `.agents/mcp_config.json`. A complete copyable example is in [`examples/antigravity-mcp_config.json`](./examples/antigravity-mcp_config.json).

In Antigravity CLI, run `/mcp` to open its MCP manager after saving either config.

## Troubleshooting

- **No windows or blank screenshot:** unlock the target Windows session and keep the desktop visible. Windows desktop automation cannot operate through the lock screen or UAC secure desktop.
- **App is not allowed:** add its executable name, for example `notepad.exe`, to `allowedApps`, then restart the client session.
- **A tool is absent:** restart the CLI/IDE after changing its MCP config and inspect the client MCP status panel or command.
- **Click/type fails:** focus the app first, confirm it appears in `computer_list_windows`, then capture a fresh screenshot before retrying.

## References

- [Claude Code MCP configuration](https://code.claude.com/docs/en/mcp)
- [Antigravity MCP configuration](https://antigravity.google/docs/mcp)