# Computer Use MCP Server for Claude Code

An MCP (Model Context Protocol) server that gives Claude Code the ability to see and interact with your Linux desktop — take screenshots, click, type, scroll, drag, and more.

Built on top of `xdotool`, `scrot`, and ImageMagick. Designed to run as a stdio MCP server inside Claude Code.

## Features

- **Screenshots** — full desktop capture, automatically scaled to fit API constraints
- **Mouse control** — left/right/middle/double/triple click, drag, move, scroll
- **Keyboard input** — type text, press key combinations, hold keys
- **Screen zoom** — capture a region at full (unscaled) resolution for reading small text
- **Display info** — query resolution, scale factor, and coordinate space

All coordinates use a scaled coordinate space that maps to the actual screen resolution. The server handles the conversion transparently.

## Prerequisites

- Linux with X11 (Wayland is not supported)
- Python >= 3.10
- System packages:

  ```bash
  sudo apt install xdotool scrot imagemagick x11-utils
  ```

  > **Note:** `xdpyinfo` is part of the `x11-utils` package on Debian/Ubuntu — there is no standalone `xdpyinfo` package.

## Installation

```bash
git clone https://github.com/SebastianBaltes/claude_code_computer_use_mcp.git
cd claude_code_computer_use_mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Claude Code Configuration

The easiest way is to use the Claude Code CLI:

```bash
claude mcp add computer-use --scope user -- /path/to/claude_code_computer_use_mcp/.venv/bin/python -m computer_use_mcp.server
```

Replace `/path/to/` with your actual clone path. Then restart Claude Code — the `computer_*` tools will be available automatically.

Alternatively, add the server manually to `~/.claude.json` under `mcpServers`:

```json
{
  "mcpServers": {
    "computer-use": {
      "type": "stdio",
      "command": "/path/to/claude_code_computer_use_mcp/.venv/bin/python",
      "args": ["-m", "computer_use_mcp.server"],
      "env": {}
    }
  }
}
```

> **Note:** The valid `--scope` values are `local`, `user`, `project`, `dynamic`, `enterprise`, `claudeai`, and `managed`. Use `user` for a personal installation available across all projects.

## Available Tools

| Tool | Description |
|---|---|
| `computer_screenshot` | Capture the full desktop |
| `computer_left_click` | Left-click (with optional modifier key) |
| `computer_right_click` | Right-click |
| `computer_double_click` | Double-click |
| `computer_triple_click` | Triple-click (select line) |
| `computer_middle_click` | Middle-click |
| `computer_mouse_move` | Move cursor without clicking |
| `computer_left_click_drag` | Click and drag |
| `computer_type` | Type a text string |
| `computer_key` | Press a key or key combo (e.g. `ctrl+s`) |
| `computer_scroll` | Scroll in any direction |
| `computer_hold_key` | Hold a key for N seconds |
| `computer_wait` | Pause for N seconds |
| `computer_cursor_position` | Get current cursor position |
| `computer_zoom` | Capture a screen region at full resolution |
| `computer_display_info` | Get display resolution and scale info |

## How It Works

The server detects the screen resolution via `xdpyinfo` and calculates a scale factor to keep screenshots within Anthropic's API image constraints (max 1568px long edge, max 1.15M total pixels). All coordinates passed by Claude are in this scaled space and get converted to actual screen coordinates before executing actions.

## License

MIT