# win-capture-mcp

An MCP server that runs on Windows and lets any AI agent screenshot open windows or the full desktop — and receive the image directly in its context.

---

## Two modes

### Mode 1: stdio (same machine, auto-managed)

Claude Code spawns the server as a child process. It starts automatically when your session starts and exits when it ends — no manual management needed.

**Best when:** your agent runs on the same Windows machine.

**Setup:**

```bat
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
```

**Claude Code config** (`claude_desktop_config.json` or `claude mcp add`):

```json
{
  "mcpServers": {
    "win-capture": {
      "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\win_capture_mcp.py"]
    }
  }
}
```

Or via CLI:
```bash
claude mcp add win-capture --command "C:\path\to\.venv\Scripts\python.exe" -- "C:\path\to\win_capture_mcp.py"
```

---

### Mode 2: HTTP (cross-machine, manual start)

Runs as a persistent HTTP server. Your agent connects over the network. Required when the agent runs in **WSL2, Linux, or the cloud** — because stdio can't cross that boundary.

**Best when:** agent is in WSL2 / a container / a remote machine.

**Quick start — double-click `run_win_capture.bat`** (creates venv, installs deps, starts server).

Or manually:
```bat
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe win_capture_mcp.py --http
```

Custom host/port:
```bat
.venv\Scripts\python.exe win_capture_mcp.py --http --host 0.0.0.0 --port 8765
```

**Connect from Claude Code:**

```bash
# WSL2 with mirrored networking:
claude mcp add --transport http win-capture http://localhost:8765/mcp

# Remote Windows machine:
claude mcp add --transport http win-capture http://192.168.1.x:8765/mcp
```

Claude Desktop config:
```json
{
  "mcpServers": {
    "win-capture": {
      "url": "http://localhost:8765/mcp"
    }
  }
}
```

> **Firewall note:** if connecting from another machine, allow port 8765 in Windows Firewall.

---

## Tools

| Tool | Description |
|------|-------------|
| `list_windows()` | Returns all capturable windows as `hwnd<TAB>title` lines |
| `capture_window(query)` | Screenshot a single window by title substring or hwnd |
| `capture_screen()` | Screenshot the entire multi-monitor desktop |

### Example agent usage

```
list all open windows
capture the window titled "VS Code"
take a screenshot of my whole desktop
```

---

## Requirements

- Windows 10 / 11
- Python 3.10+ (Windows native, not WSL)
- Dependencies: `pywin32`, `pillow`, `mcp` (installed by the `.bat` or `pip install -r requirements.txt`)

---

## Caveats

- **Browser tabs**: only the *active* tab of a browser window is captured. Background tabs need browser automation (CDP) or the Claude-in-Chrome connector.
- **Hardware-accelerated windows**: some fullscreen games or DRM-protected windows may return a blank capture. Open an issue if you hit one.
- **Minimized windows**: automatically restored before capture.
- **Admin apps**: if a window won't capture and it's running as administrator, the server must also run elevated.

---

## Claude Code Skill (optional)

The included `SKILL.md` teaches Claude how to use this server intelligently — when to call `list_windows` vs. `capture_window`, how to handle ambiguous matches, and caveats to surface to the user.

Place it in your Claude Code skills directory (e.g. `~/.claude/skills/window-capture/SKILL.md`), then use `/window-capture` in Claude Code.

---

## License

MIT