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:

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):

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

Or via CLI:

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:

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:

.venv\Scripts\python.exe win_capture_mcp.py --http --host 0.0.0.0 --port 8765

Connect from Claude Code:

# 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:

{
  "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