Windows-MCP

Captures the complete hierarchical structure of Windows UI elements using native UI Automation COM APIs, building an accessibility tree that maps all interactive controls, their properties, and spatial relationships without requiring computer vision. The Tree Service maintains a cached, queryable representation of the desktop state that enables LLMs to understand the current UI layout and identify targets for automation actions.

Simulates user input across multiple modalities (mouse clicks, keyboard typing, scrolling, mouse movement, keyboard shortcuts) by translating MCP tool calls into Windows input events through the UI Automation framework. Each action type is optimized for its use case: click operations target specific UI elements by coordinate or element reference, type operations handle text input with clipboard fallback for large payloads, and scroll/move operations support both absolute and relative positioning.

Uses FastMCP's async lifespan context manager to coordinate initialization and cleanup of core services (Desktop Service, Tree Service, WatchDog Service) across the MCP server lifecycle. Services are initialized on server startup and properly cleaned up on shutdown, ensuring resource management and state consistency. The lifespan pattern enables dependency injection and ordered initialization of services.

Supports configuration through environment variables for transport mode (local/remote), server endpoints, logging levels, and feature flags. Configuration is read at startup and applied across all services, enabling deployment flexibility without code changes. The manifest.json file defines server metadata and tool availability, allowing clients to discover capabilities.

Designed with minimal external dependencies, relying primarily on Python standard library and FastMCP framework. Windows UI Automation is accessed through native COM interfaces rather than heavy third-party libraries. This minimizes installation size, reduces dependency conflicts, and improves deployment reliability. The project uses UV (Astral) for dependency management, providing fast, deterministic package resolution.

Published under MIT license with full source code available on GitHub, enabling community contributions, customization, and transparency. The project includes contribution guidelines, development setup documentation, and code quality standards. Open-source licensing allows integration into commercial products and custom deployments without licensing restrictions.

Manages Windows application launching, window control, and process termination through native Windows APIs integrated into the MCP tool layer. Enables starting applications by path or name, bringing windows to focus, minimizing/maximizing/closing windows, and terminating processes. The Desktop Service coordinates these operations with the UI Automation layer to maintain consistent state tracking.

Implements a specialized 'DOM mode' for browser automation that extracts the actual web page content structure while intelligently filtering out browser UI elements (address bar, tabs, toolbars, scrollbars). This is achieved by parsing the browser's accessibility tree and applying heuristics to distinguish page content from browser chrome, returning a clean DOM representation that LLMs can reason about without visual noise.

The WatchDog Service continuously monitors the Windows desktop for state changes (new windows, closed applications, UI element tree modifications) and provides real-time notifications to MCP clients. This enables reactive automation workflows where agents can respond to system events rather than polling. The service maintains a delta between previous and current state, allowing efficient change detection without full tree re-traversal.

Provides control over Windows Virtual Desktop functionality, enabling automation workflows to create, switch between, and manage virtual desktops. This allows organizing application workspaces and isolating automation tasks to specific desktops. The Virtual Desktop Manager integrates with the UI Automation layer to track which applications are on which desktops.

Exposes 17 specialized Windows automation tools through the Model Context Protocol using a schema-based function registry that binds to FastMCP framework. Each tool is defined with precise input/output schemas, parameter validation, and error handling. The MCP server dynamically generates tool definitions that LLM clients can discover and invoke, with automatic marshaling between LLM function calls and Python implementation.

Supports executing multiple automation operations in a single MCP call through multi-operation tools that coordinate state changes across sequential actions. This reduces round-trip latency and improves reliability by grouping related operations (e.g., click, wait for state change, type text) into atomic units. The Desktop Service maintains state consistency across operations, rolling back on failure.

Captures PNG screenshots of the current desktop state, with optional integration into the snapshot tool. The screenshot capability is decoupled from UI element identification, allowing operation in 'vision-free' mode where LLMs can automate Windows without computer vision capabilities. Screenshots are base64-encoded for MCP transmission and can be selectively captured (full desktop, specific window, or region).

Implements the Model Context Protocol (MCP) specification with transport abstraction, supporting both local (stdio) and remote (HTTP/WebSocket) operation modes. The server is compatible with multiple LLM clients including Claude Desktop, Perplexity Desktop, Gemini CLI, and custom MCP clients. Transport configuration is environment-driven, allowing deployment flexibility without code changes.