Winapp MCP

WinApp MCP

Website · GitHub · npm · VS Code Marketplace

Playwright for Windows Desktop Apps

A Model Context Protocol (MCP) server that gives AI assistants full control over native Windows applications — launch, inspect, click, type, screenshot, and test any WinUI3, WPF, WinForms, UWP, or Win32 app.

Why This Exists

Browser automation has Playwright. Mobile has Appium. But Windows desktop automation for AI agents? The existing options didn't go deep enough.

AI assistants like GitHub Copilot, Claude, and ChatGPT can browse the web, run terminal commands, and edit files. But they cannot interact with native Windows applications. They can't click a button in your WinUI3 app, read a value from a WPF form, or test a WinForms dialog.

WinApp MCP bridges that gap. It exposes 55 UI automation tools through the Model Context Protocol, letting any MCP-compatible AI assistant control Windows desktop apps the same way Playwright controls browsers.

The Problem

The Solution

WinApp MCP gives AI assistants eyes and hands for any Windows desktop application:

┌─────────────────────┐      MCP (stdio)      ┌──────────────────────┐
│   AI Assistant       │◄─────────────────────►│   WinApp MCP Server  │
│   (Copilot, Claude)  │   JSON-RPC over stdio │   (.NET 10 + FlaUI)  │
└─────────────────────┘                        └──────────┬───────────┘
                                                          │ UI Automation
                                                          ▼
                                               ┌──────────────────────┐
                                               │  Windows Application │
                                               │  WinUI3/WPF/WinForms│
                                               └──────────────────────┘

Key Features

🔍 Deep UI Inspection

• DOM-like snapshots of the entire UI element tree with configurable depth
• Filtered search by control type, AutomationId, or name
• Fuzzy matching with Levenshtein distance — tolerates typos and partial names
• Element existence checks — fast boolean queries without full property reads

🖱️ Complete Interaction

• Click, double-click, right-click, invoke (via UIA patterns)
• Type text, press keys, key combos (Ctrl+S, Alt+F4, etc.)
• Fill entire forms in a single call — no sequential typing
• Select dropdown options in one atomic operation
• Drag and drop between elements
• Expand/collapse tree items, menus, and accordions

🪟 Multi-Window HWND Targeting

• Target specific windows by native handle (HWND)
• Click, set values, and take snapshots of popups, dialogs, and secondary windows
• Essential for multi-window applications and system dialogs

⚡ Performance-Optimized

• Descendant cache (2s TTL) — avoids repeated FindAllDescendants calls that take 200-800ms on complex apps
• Window cache (30s TTL) — eliminates expensive window lookups
• Smart cache invalidation — cache is cleared automatically after mutations (click, type, navigate)
• Token-aware screenshots — auto-resize images to fit within LLM context limits

📊 Advanced UIA Patterns

• GridPattern — direct cell access by row/column in DataGrids
• ScrollItemPattern — scroll off-screen elements into view
• VirtualizedItemPattern — realize items in WinUI3 virtualized lists (ListView, GridView)
• ExpandCollapsePattern — programmatic expand/collapse for tree items and menus
• ItemContainerPattern — efficient search in large/virtualized containers

📡 Event Monitoring

• Monitor focus changes, structure changes (elements added/removed), and property changes in real-time
• Session-based with 500-event ring buffer
• Debug async UI updates, animations, and background data loads

📸 Visual Verification

• Screenshot capture with auto-resize for LLM token budgets
• Annotated screenshots — red bounding boxes drawn around specified elements
• Pixel-diff comparison — compare two screenshots and highlight changes
• HWND-targeted screenshots for specific windows

🪟 Minimized & Locked Session Support

• Works when apps are minimized — auto-restores windows before mouse/keyboard operations, uses PrintWindow API for screenshots without needing to restore
• Works when the desktop is locked — clicks via UIA patterns (InvokePattern, TogglePattern, SelectionItemPattern) instead of mouse simulation; reads/writes values via ValuePattern; captures screenshots via PrintWindow
• Smart fallback chain — tries UIA pattern → auto-restore + mouse simulation → informative error
• Session status detection — check_session_status reports whether the session is locked, the app is minimized, and which operations are available
• Manual restore — restore_window brings a minimized app back to foreground on demand

Why it matters: AI agents running long autonomous pipelines shouldn't break because a screensaver kicked in or the user minimized the app. WinApp MCP degrades gracefully — UIA pattern-based operations keep working even when mouse/keyboard simulation can't.

🛡️ Safety

• Emergency release — unstick all modifier keys and mouse buttons with one call
• Wait primitives — wait for elements, conditions, and input idle states
• Timeout controls on all blocking operations

Use Cases

🤖 AI-Powered E2E Testing

Let AI assistants test your Windows app the way a QA engineer would — navigate pages, fill forms, verify data, test status transitions, capture evidence.

"Navigate to Invoices → Create New → Fill all fields → Save → Verify detail page → Test status change to Sent"

🔄 Automated UI Verification

After code generation or refactoring, have the AI launch the app and verify that the UI renders correctly, buttons work, and forms validate properly.

🧪 Visual Regression Testing

Take baseline screenshots, make changes, take new screenshots, and use screenshot_diff to detect unexpected visual changes.

📋 Form Automation & Data Entry

Fill complex multi-field forms in a single fill_form call. Automate repetitive data entry across desktop applications.

🏗️ CI/CD Desktop Testing

Integrate into build pipelines to automatically test desktop applications after each build. The MCP server runs headless-compatible via stdio transport.

🔍 Accessibility Auditing

Inspect the UI Automation tree to verify that all controls have proper AutomationIds, names, and patterns — critical for screen reader compatibility.

Installation

Works with any MCP client — VS Code, Claude Desktop, Cursor, Windsurf, Cline, and more.

Option 1: npm (Works Everywhere) ⭐

The universal way to run WinApp MCP with any MCP client. No .NET SDK required.

npm install -g winapp-mcp

Or run directly without installing:

npx -y winapp-mcp

Then add to your MCP client config (see client-specific configs below).

Option 2: VS Code Extension (VSIX)

The easiest way for VS Code / GitHub Copilot users. Bundles the MCP server and auto-registers on install.

1. Download the latest .vsix file from Releases
2. In VS Code: Ctrl+Shift+P → "Extensions: Install from VSIX..." → select the file
3. Reload VS Code — the MCP server registers automatically