# WindowCaptureMCP

## Author and origin

**D. Matthew Pegg — PeggSoft**

Original source:

    https://github.com/LuckyElba/WindowCaptureMCP

WindowCaptureMCP is released under the **PeggSoft Permissive Attribution License**.
It may be used, modified, distributed, and used commercially for any lawful
purpose, provided attribution to D. Matthew Pegg / PeggSoft and a reference to
the original source repository are retained. See `LICENSE` for the full terms.

A small, read-only Windows MCP server that lets an MCP client enumerate desktop
windows and request PNG screenshots of a particular window.

## A useful companion for AI assistants

WindowCaptureMCP is designed to work well alongside ChatGPT and other AI assistants
that can use MCP tools, either directly or through a suitable bridge.

It can be useful with different versions or configurations of ChatGPT, and with
other AI clients, provided there is something available to carry the MCP requests
between the AI and this Windows PC. That connection layer might be:

- Desktop Commander Remote;
- another MCP bridge or relay;
- a secure MCP tunnel;
- or direct local MCP support when the AI client is running on the same machine.

In other words, WindowCaptureMCP handles the Windows screenshot side, while the
bridge or MCP-capable client handles communication with the AI.

This makes it a useful companion tool for AI-assisted debugging, UI review,
software testing, technical support, and other workflows where the AI benefits
from being able to see a specific application window.

### Recommended companion: MCP Activity

[MCP Activity](https://github.com/LuckyElba/MCPActivity) is a companion Windows
tray application for supervising MCP helper processes such as WindowCaptureMCP and
Desktop Commander Remote.

It provides a compact status display, Start/Stop/Restart controls, automatic
startup, restart-on-failure support, logging, and a notification-area status icon.
Using MCP Activity means WindowCaptureMCP and its remote bridge can be kept running
and monitored without leaving command windows open.

For a ChatGPT setup using Desktop Commander Remote, a useful arrangement is:

    ChatGPT
       |
       v
    Desktop Commander Remote  <--- monitored by MCP Activity
       |
       v
    windowcapture.bat
       |
       v
    WindowCaptureMCP          <--- monitored by MCP Activity
       |
       v
    Windows application window

MCP Activity repository:

    https://github.com/LuckyElba/MCPActivity

## Tools

- `list_windows(title_filter="", include_untitled=false)`
- `capture_window(hwnd, client_area_only=false)`
- `capture_window_by_title(title, exact=false, match_index=0, client_area_only=false)`
- `capture_foreground_window(client_area_only=false)`

The capture tools return MCP image content (`image/png`) directly to the client.

## Security design

The server binds to **127.0.0.1 only** by default. It exposes no command execution,
keyboard/mouse control, arbitrary file access, or window-management operations.

Do not change the bind address to `0.0.0.0` unless you also add authentication and
understand the network exposure.

## Install

On Windows:

1. Extract the project.
2. Run `install.bat`.
3. Run `start_server.bat`.

The MCP endpoint is:

    http://127.0.0.1:8765/mcp

## Local smoke test

Leave `start_server.bat` running, then run `test.bat`.

The test enumerates windows, captures one non-minimized window, and writes
`test-capture.png` into the `Screenshots` subdirectory.

The command-line bridge also saves captures into `Screenshots` by default. If no
`-o` path is supplied, it generates a timestamped filename such as
`capture-20261005-073500.png`. A bare filename supplied with `-o` is also
placed in `Screenshots`; an absolute output path is honored exactly.

## MCP Inspector

You can also test it with MCP Inspector using Streamable HTTP and:

    http://127.0.0.1:8765/mcp

## What else is needed to use it?

WindowCaptureMCP is the local screenshot server. It performs window enumeration and
capture, but it does not by itself make your Windows PC reachable from a remote AI
service.

What else you need depends on where the MCP client is running.

### Local MCP client on the same PC

If the MCP client is running on the same Windows PC and supports Streamable HTTP,
no remote bridge is needed. Point it directly at:

    http://127.0.0.1:8765/mcp

For example, MCP Inspector can connect directly to this endpoint for testing.

Any other MCP client that supports Streamable HTTP on localhost can use the same
address. If a particular client supports only stdio MCP servers, an appropriate
stdio-to-HTTP adapter is needed between that client and WindowCaptureMCP.

### ChatGPT using Desktop Commander Remote

A working way to use WindowCaptureMCP from ChatGPT is to use Desktop Commander
Remote as the connection to the Windows PC.

Desktop Commander can be found at:

- Website: https://desktopcommander.app/
- Remote Desktop Commander GitHub:
  https://github.com/desktop-commander/remote-desktop-commander

The local/remote device component can also be launched with:

    npx @wonderwhy-er/desktop-commander@latest remote

In this arrangement:

    ChatGPT
       |
       |  Desktop Commander remote connection
       v
    Desktop Commander Remote on the Windows PC
       |
       |  runs windowcapture.bat
       v
    WindowCaptureMCP
       |
       v
    Windows desktop / target window

Desktop Commander supplies the remote connection to the PC. WindowCaptureMCP
supplies the screenshot-specific functionality.

The command-line bridge supports commands such as:

    windowcapture.bat list
    windowcapture.bat capture-title "MCP Activity"
    windowcapture.bat capture-hwnd 0x00123456

Captures made through the command-line bridge are stored under the `Screenshots`
subdirectory unless an absolute output path is supplied.

For this setup, Desktop Commander Remote must be installed/available, paired with
the ChatGPT account, and running on the Windows PC.

### Other remote MCP bridges or tunnels

Desktop Commander is only one possible remote connection method. Another bridge
can be used if it can securely carry requests between a remote MCP client and the
local Windows machine.

Possible approaches include:

- a private MCP relay service;
- a secure outbound tunnel service;
- a self-hosted HTTPS relay or reverse proxy with authentication;
- an OpenAI-supported MCP tunnel where available for the account/client in use;
- another remote-control/MCP product capable of invoking the local bridge or
  forwarding the MCP endpoint.

A remote solution should provide authentication, encryption, and preferably an
outbound connection initiated by the Windows PC. Some hosted relay or tunnel
services may require a subscription or cloud hosting.

### Do not expose port 8765 directly to the Internet

WindowCaptureMCP deliberately listens on `127.0.0.1` by default. This makes it
available only to programs on the same PC.

Do not simply change the bind address to `0.0.0.0`, forward TCP port 8765 through
a router, or publish the raw MCP endpoint to the Internet. The server currently
assumes that the local loopback boundary is part of its security model.

If remote access is required, put an authenticated and encrypted bridge in front
of it instead.

## Capture behaviour

The implementation first uses Win32 `PrintWindow`, which can capture many windows
even when another window partly covers them. Some GPU-accelerated or protected
windows may refuse or return blank content. In that case the code falls back to
capturing the visible screen rectangle. A minimized window may need to be restored
if it does not support `PrintWindow`.

## Build a standalone EXE

After `install.bat`, run `build_exe.bat`.

It uses PyInstaller and places the result at:

    dist\WindowCaptureMCP.exe

This packaging step should be tested on the same Windows version/architecture where
you intend to run it.