# winapp-mcp [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/floatingbrij/desktop-pilot-mcp  
**GitHub Stars:** 44  
**npm Downloads (last month):** 347  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/winapp-mcp

## Description
MCP server for automating native Windows desktop apps — Playwright for Windows. Gives AI assistants (Copilot, Claude, Cursor) full control over WinUI3, WPF, WinForms, and Win32 apps with 55 UI automation tools. Built entirely with GitHub Copilot.

## Tools
Capabilities this server exposes over MCP:

- **launch_app** — Launch a Windows app by executable path
- **attach_to_app** — Attach to a running process by name
- **attach_to_pid** — Attach to a running process by PID
- **close_app** — Close a tracked application
- **list_apps** — List all currently tracked applications
- **list_windows** — List all windows of a tracked app
- **list_desktop_windows** — List all visible desktop windows
- **get_snapshot** — Get a UI tree snapshot (like browser DOM inspection)
- **get_focused_element** — Get the currently focused element's info
- **find_elements** — Search for elements with filters (type, id, name)
- **find_all_elements** — List all matching elements with indices
- **find_elements_fuzzy** — Fuzzy search — tolerates typos and partial names
- **read_element** — Read detailed properties of a UI element
- **read_element_by_index** — Read properties by index (from `find_all_elements`)
- **get_element_bounds** — Get bounding rectangle (screen coordinates)
- **element_exists** — Fast boolean check — does this element exist?
- **get_all_values** — Read all editable field values at once
- **click_element** — Click a UI element by AutomationId or name
- **double_click_element** — Double-click a UI element
- **right_click_element** — Right-click (open context menu)
- **click_at_coordinates** — Click at absolute screen coordinates
- **invoke_element** — Invoke via UIA InvokePattern/TogglePattern
- **select_option** — Select a ComboBox/dropdown option in one call
- **expand_collapse_element** — Expand, collapse, or toggle tree/menu items
- **drag_element** — Drag from one element to another
- **type_text** — Type text into a text field
- **press_key** — Press a single key (RETURN, TAB, ESCAPE, etc.)
- **press_key_combo** — Press a key combination (Ctrl+S, Alt+F4)
- **fill_form** — Fill multiple form fields in one call
- **wait_for_element** — Wait for an element to appear
- **wait_for_condition** — Wait for a property to reach a value
- **wait_for_input_idle** — Wait for window to be ready for input
- **release_all** — Emergency: release all stuck modifier keys
- **take_screenshot** — Capture app window as PNG
- **take_screenshot_optimized** — Screenshot with auto-resize for LLM token budgets
- **annotate_screenshot** — Draw red bounding boxes around elements
- **screenshot_diff** — Pixel-diff two screenshots, highlight changes
- **get_tree_hash** — Hash the UI tree to detect changes
- **click_element_hwnd** — Click in a specific window by handle
- **set_value_hwnd** — Set text in a specific window by handle
- **get_snapshot_hwnd** — UI snapshot of a specific window by handle
- **get_grid_item** — Access a DataGrid cell by row/column
- **find_item_by_property** — Search in containers (ItemContainerPattern)
- **scroll_into_view** — Scroll an element into the visible area
- **realize_virtualized_item** — Load a virtualized item into the UI tree
- **scroll_element** — Scroll within a scrollable container
- **invalidate_cache** — Force-refresh cached window references
- **start_event_monitor** — Start monitoring UI events (focus/structure/property)
- **stop_event_monitor** — Stop monitoring a session or all sessions
- **get_event_log** — Read captured events from a monitoring session
- **restore_window** — Restore a minimized window and bring it to foreground
- **check_session_status** — Check if desktop is locked, app is minimized, and report available operations

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "winapp-mcp": {
    "command": "npx",
    "args": ["-y","winapp-mcp"]
  }
}
```

## Documentation

## What winapp-mcp does

winapp-mcp exposes native Windows desktop UI automation through the Model Context Protocol. It is intended for AI assistants that need to operate compiled desktop applications rather than web pages or terminal-only workflows. Supported application technologies include WinUI 3, WPF, WinForms, UWP, and Win32.

The server provides 55 UI automation tools covering application launch, UI-tree inspection, element lookup, interaction, screenshots, waits, event monitoring, and session status. It can inspect controls by type, AutomationId, or name, and supports fuzzy matching for partial names and typographical differences. Element existence checks provide a lighter-weight way to test whether a control is present.

Typical uses include AI-assisted end-to-end testing, desktop form entry, post-build UI checks, visual regression checks, and accessibility-oriented inspection of the exposed UI tree.

## How it works

An MCP client communicates with the server over stdio using JSON-RPC. The server uses .NET 10 and FlaUI to access Windows UI Automation, then operates on the target application through native controls and UIA patterns.

Window handles can be used to address a particular top-level window, popup, dialog, or secondary window. This is useful when an application has multiple windows or when a system dialog must be handled separately. The server also supports GridPattern cell access, scrolling off-screen elements into view, realizing virtualized list items, expanding and collapsing items, and searching within large containers.

Repeated UI lookups are reduced through descendant and window caches. Mutating operations such as clicking, typing, and navigation invalidate relevant cached data. Screenshot output can be resized for model context limits, and event sessions retain up to 500 events for focus, structure, and property changes.

## Setup and configuration

winapp-mcp runs on Windows 10 or Windows 11 and uses stdio transport, so it can be configured as a local MCP server in a compatible client. The project is distributed through npm and also provides a VS Code Marketplace listing. Its runtime is based on .NET 10.

The server is designed for MCP clients such as Claude, Cursor, and GitHub Copilot. Configure the client to start the package or installed server using its MCP server settings, then grant the server access to the Windows applications that the agent needs to operate.

## Tools and capabilities

- Inspect the UI as a DOM-like element tree with configurable depth.
- Find controls by type, name, AutomationId, or fuzzy text matching.
- Click, double-click, right-click, invoke, type text, press keys, and send key combinations.
- Fill multiple form fields in one operation and select dropdown values atomically.
- Drag between elements and expand or collapse trees, menus, and accordions.
- Target controls and screenshots by HWND.
- Capture regular, annotated, and pixel-difference screenshots.
- Wait for elements, conditions, or input-idle states with timeout controls.
- Monitor focus, structure, and property changes in a session.
- Check session state and restore minimized windows when needed.

## Limitations and notes

Mouse and keyboard simulation may require a visible or restored desktop, while UIA pattern-based actions can continue in more restricted states. The server attempts UIA patterns first, then can restore a minimized window and use mouse simulation; unsupported operations return an error. Locked-session support depends on operations exposed through patterns such as Invoke, Toggle, SelectionItem, and Value. Screenshots in these conditions use the Windows PrintWindow API.

The server includes an emergency release operation for stuck modifier keys and mouse buttons. It also offers session-status reporting for locked desktops, minimized applications, and available operations. These behaviors make it suitable for longer-running desktop automation, but the target application still needs to expose usable Windows UI Automation elements.

_Full upstream README: https://allmcps.com/mcp/winapp-mcp/readme_