# cursortouch/windows-mcp architecture

> Architecture diagram of the GitHub repository cursortouch/windows-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cursortouch/windows-mcp
- Repository: https://github.com/cursortouch/windows-mcp

## Overview

Windows-MCP is an MCP server that exposes Windows automation capabilities to AI agents. The main workflow is an agent request entering the server, reaching its registered tools, and using Windows UI automation to inspect state or perform actions. The repository also provides filesystem, shell, process, registry, notification, and browser-DOM capabilities. Sampled source supports the server-to-tool and UI-tree rendering relationships; exact routing from individual tools to services is not shown, so those links are omitted.

Main entry points: [`src/windows_mcp/desktop/service.py`](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/desktop/service.py) (Desktop service), [`src/windows_mcp/tree/service.py`](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tree/service.py) (UI tree capture), [`src/windows_mcp/uia/controls.py`](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/uia/controls.py) (UIA controls), [`src/windows_mcp/__main__.py`](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/__main__.py) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP server"]
  node_mcp["MCP server<br/>[__main__.py]"]
  node_oauth["OAuth support<br/>[oauth.py]"]
end

subgraph group_tools["Agent tools"]
  node_toolset["Tool registration"]
  node_snapshot["UI snapshot tool<br/>[snapshot.py]"]
  node_input["Input tool<br/>[input.py]"]
  node_app["Application tool<br/>[app.py]"]
  node_toolfs["Filesystem tools<br/>[filesystem.py]"]
  node_misc_tools["System tools"]
end

subgraph group_automation["Desktop automation"]
  node_desktop["Desktop service<br/>[service.py]"]
  node_screenshot["Screenshots<br/>[screenshot.py]"]
  node_overlay["Flash overlay<br/>[flash_overlay.py]"]
  node_tree["UI tree capture<br/>[service.py]"]
  node_treeviews["Tree rendering<br/>[views.py]"]
  node_ia2["IAccessible2 fallback<br/>[ia2.py]"]
  node_watchdog["UI event monitor<br/>[service.py]"]
end

subgraph group_system["Windows services"]
  node_filesystem["Filesystem service<br/>[service.py]"]
  node_powershell["PowerShell executor<br/>[service.py]"]
  node_process["Process service<br/>[service.py]"]
  node_registry["Registry service<br/>[service.py]"]
  node_notifications["Notifications<br/>[service.py]"]
  node_vdm["Virtual desktops<br/>[core.py]"]
end

subgraph group_uia["UIA foundation"]
  node_uia_controls["UIA controls<br/>[controls.py]"]
  node_uia_core["UIA core<br/>[core.py]"]
  node_uia_patterns["UIA patterns<br/>[patterns.py]"]
  node_uia_enums["UIA types<br/>[enums.py]"]
end

node_agent(("AI agent"))

node_agent -->|"requests tools"| node_mcp
node_mcp -->|"registers"| node_toolset
node_mcp -->|"loads"| node_snapshot
node_desktop -->|"uses capture"| node_tree
node_desktop -->|"uses"| node_screenshot
node_desktop -->|"uses"| node_overlay
node_desktop -->|"executes commands"| node_powershell
node_desktop -->|"queries desktops"| node_vdm
node_tree -->|"builds output"| node_treeviews
node_tree -->|"uses fallback"| node_ia2
node_tree -->|"queries controls"| node_uia_controls
node_tree -->|"uses identifiers"| node_uia_enums
node_uia_controls -->|"uses"| node_uia_core
node_uia_controls -->|"uses"| node_uia_patterns
node_uia_controls -->|"uses"| node_uia_enums
node_watchdog -->|"subscribes through"| node_uia_core
node_filesystem --> node_filesystem
node_registry -->|"runs commands"| node_powershell
node_notifications -->|"runs commands"| node_powershell

click node_mcp "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/__main__.py"
click node_toolset "https://github.com/cursortouch/windows-mcp/tree/main/src/windows_mcp/tools"
click node_snapshot "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tools/snapshot.py"
click node_input "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tools/input.py"
click node_app "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tools/app.py"
click node_toolfs "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tools/filesystem.py"
click node_misc_tools "https://github.com/cursortouch/windows-mcp/tree/main/src/windows_mcp/tools"
click node_desktop "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/desktop/service.py"
click node_screenshot "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/desktop/screenshot.py"
click node_overlay "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/desktop/flash_overlay.py"
click node_tree "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tree/service.py"
click node_treeviews "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tree/views.py"
click node_ia2 "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tree/ia2.py"
click node_watchdog "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/watchdog/service.py"
click node_uia_controls "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/uia/controls.py"
click node_uia_core "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/uia/core.py"
click node_uia_patterns "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/uia/patterns.py"
click node_uia_enums "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/uia/enums.py"
click node_filesystem "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/filesystem/service.py"
click node_powershell "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/powershell/service.py"
click node_process "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/process/service.py"
click node_registry "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/registry/service.py"
click node_notifications "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/notifications/service.py"
click node_vdm "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/vdm/core.py"
click node_oauth "https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/infrastructure/oauth.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_oauth toneBlue
class node_toolset,node_snapshot,node_input,node_app,node_toolfs,node_misc_tools toneAmber
class node_desktop,node_screenshot,node_overlay,node_tree,node_treeviews,node_ia2,node_watchdog toneMint
class node_filesystem,node_powershell,node_process,node_registry,node_notifications,node_vdm toneRose
class node_uia_controls,node_uia_core,node_uia_patterns,node_uia_enums,node_agent toneIndigo
```

## Components

### MCP server

- [MCP server](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/__main__.py): `src/windows_mcp/__main__.py`
- [OAuth support](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/infrastructure/oauth.py): `src/windows_mcp/infrastructure/oauth.py`

### Agent tools

- [Tool registration](https://github.com/cursortouch/windows-mcp/tree/main/src/windows_mcp/tools): `src/windows_mcp/tools`
- [UI snapshot tool](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tools/snapshot.py): `src/windows_mcp/tools/snapshot.py`
- [Input tool](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tools/input.py): `src/windows_mcp/tools/input.py`
- [Application tool](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tools/app.py): `src/windows_mcp/tools/app.py`
- [Filesystem tools](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tools/filesystem.py): `src/windows_mcp/tools/filesystem.py`
- [System tools](https://github.com/cursortouch/windows-mcp/tree/main/src/windows_mcp/tools): `src/windows_mcp/tools`

### Desktop automation

- [Desktop service](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/desktop/service.py): `src/windows_mcp/desktop/service.py`
- [Screenshots](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/desktop/screenshot.py): `src/windows_mcp/desktop/screenshot.py`
- [Flash overlay](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/desktop/flash_overlay.py): `src/windows_mcp/desktop/flash_overlay.py`
- [UI tree capture](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tree/service.py): `src/windows_mcp/tree/service.py`
- [Tree rendering](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tree/views.py): `src/windows_mcp/tree/views.py`
- [IAccessible2 fallback](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/tree/ia2.py): `src/windows_mcp/tree/ia2.py`
- [UI event monitor](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/watchdog/service.py): `src/windows_mcp/watchdog/service.py`

### Windows services

- [Filesystem service](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/filesystem/service.py): `src/windows_mcp/filesystem/service.py`
- [PowerShell executor](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/powershell/service.py): `src/windows_mcp/powershell/service.py`
- [Process service](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/process/service.py): `src/windows_mcp/process/service.py`
- [Registry service](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/registry/service.py): `src/windows_mcp/registry/service.py`
- [Notifications](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/notifications/service.py): `src/windows_mcp/notifications/service.py`
- [Virtual desktops](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/vdm/core.py): `src/windows_mcp/vdm/core.py`

### UIA foundation

- [UIA controls](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/uia/controls.py): `src/windows_mcp/uia/controls.py`
- [UIA core](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/uia/core.py): `src/windows_mcp/uia/core.py`
- [UIA patterns](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/uia/patterns.py): `src/windows_mcp/uia/patterns.py`
- [UIA types](https://github.com/cursortouch/windows-mcp/blob/main/src/windows_mcp/uia/enums.py): `src/windows_mcp/uia/enums.py`

### Other components

- **AI agent**

## Connections

- AI agent → MCP server: requests tools
- MCP server → Tool registration: registers (evidence: `src/windows_mcp/__main__.py`)
- MCP server → UI snapshot tool: loads (evidence: `src/windows_mcp/__main__.py`)
- Desktop service → UI tree capture: uses capture (evidence: `src/windows_mcp/desktop/service.py`)
- Desktop service → Screenshots: uses (evidence: `src/windows_mcp/desktop/service.py`)
- Desktop service → Flash overlay: uses (evidence: `src/windows_mcp/desktop/service.py`)
- Desktop service → PowerShell executor: executes commands (evidence: `src/windows_mcp/desktop/service.py`)
- Desktop service → Virtual desktops: queries desktops (evidence: `src/windows_mcp/desktop/service.py`)
- UI tree capture → Tree rendering: builds output (evidence: `src/windows_mcp/tree/service.py`)
- UI tree capture → IAccessible2 fallback: uses fallback (evidence: `src/windows_mcp/tree/service.py`)
- UI tree capture → UIA controls: queries controls (evidence: `src/windows_mcp/tree/service.py`)
- UI tree capture → UIA types: uses identifiers (evidence: `src/windows_mcp/tree/service.py`)
- UIA controls → UIA core: uses (evidence: `src/windows_mcp/uia/controls.py`)
- UIA controls → UIA patterns: uses (evidence: `src/windows_mcp/uia/controls.py`)
- UIA controls → UIA types: uses (evidence: `src/windows_mcp/uia/controls.py`)
- UI event monitor → UIA core: subscribes through (evidence: `src/windows_mcp/watchdog/service.py`)
- Filesystem service → Filesystem service (evidence: `src/windows_mcp/filesystem/service.py`)
- Registry service → PowerShell executor: runs commands (evidence: `src/windows_mcp/registry/service.py`)
- Notifications → PowerShell executor: runs commands (evidence: `src/windows_mcp/notifications/service.py`)
