# Mcp Windows

> Let AI agents control Windows applications. Click buttons, type text, toggle settings — all by name, not coordinates. Uses the Windows UI Automation API to find UI elements reliably, regardless of DPI, theme, resolution, or window position.

- **Type:** MCP server
- **Install:** `agentstack add mcp-sbroenne-mcp-windows`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sbroenne](https://agentstack.voostack.com/s/sbroenne)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sbroenne](https://github.com/sbroenne)
- **Source:** https://github.com/sbroenne/mcp-windows
- **Website:** https://windowsmcpserver.dev/

## Install

```sh
agentstack add mcp-sbroenne-mcp-windows
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🪟 Windows MCP Server

[](LICENSE)
[](https://dotnet.microsoft.com/download/dotnet/10.0)
[](#)
[](https://github.com/sbroenne/mcp-windows/actions/workflows/ci.yml)
[](https://github.com/sbroenne/mcp-windows/actions/workflows/llm-tests.yml)

**Windows automation that actually works.** Uses the Windows UI Automation API to find buttons by name, not pixels. Tested with real AI models before every release.

## Why This Exists

Screenshot-based automation doesn't work reliably. Vision models guess wrong, coordinates break when windows move or DPI changes, and you burn through thousands of tokens on retry loops. We tried it (check the commit history) — it failed too often to be useful.

Windows MCP Server asks Windows directly: "What buttons exist in this window?" Windows knows. It's deterministic.

## How It Works

```
# 1. Find the window
window_management(action='find', title='Notepad') → handle='123456'

# 2. Click elements by name
ui_click(windowHandle='123456', nameContains='Save')

# 3. Type into fields
ui_type(windowHandle='123456', controlType='Edit', text='Hello World')

# 4. Fallback for games/canvas — screenshot + mouse
screenshot_control(windowHandle='123456') → element coordinates
mouse_control(action='click', x=450, y=300)
```

Same command works every time. Any machine. Any DPI. Any theme.

Browsers follow the same semantic flow: launch `msedge.exe` or `chrome.exe`, then use `ui_find`, `ui_click`, and `ui_type` on links, buttons, and fields exposed through UIA names and ARIA labels.

## Key Features

- **🧠 Semantic UI** — Find elements by name, not coordinates. Works regardless of DPI, theme, or window position.
- **� Multi-Monitor** — Full support for multiple displays with per-monitor DPI scaling.
- **🧪 LLM-Tested** — 54 tests with real AI models (GPT-4.1, GPT-5.2). 100% pass rate required for release.
- **💻 Broad App Support** — Tested against classic Windows apps, modern Windows 11 apps, and Electron apps (VS Code, Teams, Slack). Chromium browser pages follow the same ARIA-driven pattern, but browser chrome remains best-effort.
- **🔄 Full Fallback** — Screenshot + mouse + keyboard for games and custom controls.
- **🪙 Token Optimized** — Short property names, JPEG screenshots, auto-scaling. ~60% fewer tokens than standard JSON.

## Installation

**VS Code Extension** — [Install from Marketplace](https://marketplace.visualstudio.com/items?itemName=sbroenne.windows-mcp). Works with GitHub Copilot automatically.

**Plugin (GitHub Copilot CLI / Claude Code)** — Install the shared plugin bundle in [`plugin/`](plugin/README.md):

```powershell
copilot plugin install sbroenne/mcp-windows:plugin
```

For local Claude Code development:

```powershell
claude --plugin-dir .\plugin
```

On first use, the plugin downloads the current standalone release into `plugin\bin\`.

**Standalone** — [Download from Releases](https://github.com/sbroenne/mcp-windows/releases). Add to your MCP config:

```json
{ "servers": { "windows": { "command": "path\\to\\Sbroenne.WindowsMcp.exe" } } }
```

## Tools

| Tool | Purpose |
|------|---------|
| `ui_click` | Click buttons, checkboxes, menu items by name |
| `ui_type` | Type into text fields |
| `ui_find` | Discover elements in a window (with timeout/retry) |
| `ui_read` | Read text from elements (with OCR fallback) |
| `file_save` | Save files via Save As dialog |
| `screenshot_control` | Get element metadata (image optional) |
| `window_management` | Find, activate, move, resize windows |
| `mouse_control` | Coordinate-based clicks (fallback for games) |
| `keyboard_control` | Hotkeys and key sequences |
| `app` | Launch applications |

Full reference: [FEATURES.md](FEATURES.md)

## ⚠️ Caution

This MCP server controls your Windows desktop. Use responsibly.

## Known Limitations

**UAC & Elevated Processes** — Windows security prevents any non-elevated process from interacting with UAC prompts or elevated (Administrator) windows. This is a fundamental Windows security boundary, not an MCP limitation.

| Scenario | What Happens | Workaround |
|----------|--------------|------------|
| `winget install` triggers UAC | AI cannot click the UAC prompt | Run terminal as Administrator first |
| App running as Administrator | UI automation tools return `ElevatedWindowActive` error | Run MCP server elevated, or use the app non-elevated |
| UAC prompt appears | AI cannot interact with secure desktop | User must manually approve |

See [FEATURES.md](FEATURES.md#known-limitations) for details.

## Testing

```bash
dotnet test                                      # All tests
dotnet test --filter "FullyQualifiedName~Unit"   # Unit only
```

**Framework coverage**: Tests run against WinForms, WinUI 3, Electron apps, and real Chromium browser app windows by default. The Chromium smoke stack now exercises both Edge and Chrome (when installed) across a deterministic local page and a required public-web slice (`demo.playwright.dev/todomvc`) using the same semantic-first UI Automation model with isolated browser state and browser-window-only cleanup.

```powershell
dotnet test .\tests\Sbroenne.WindowsMcp.Tests\Sbroenne.WindowsMcp.Tests.csproj --filter "FullyQualifiedName~ChromiumBrowser"
```

**LLM tests**: 54 tests with real AI models (GPT-4.1, GPT-5.2). 100% pass rate required for release.

```powershell
cd tests/Sbroenne.WindowsMcp.LLM.Tests
uv run pytest -v
```

Requires Azure OpenAI access. See [LLM Tests README](tests/Sbroenne.WindowsMcp.LLM.Tests/README.md).

## Related Projects

- **[pytest-aitest](https://github.com/sbroenne/pytest-aitest)** — LLM agent testing framework (powers our integration tests)
- **[Excel MCP Server](https://excelmcpserver.dev)** — AI-powered Excel automation
- **[OBS Studio MCP Server](https://github.com/sbroenne/mcp-server-obs)** — AI-powered streaming control

## Documentation

| Document | Description |
|----------|-------------|
| [FEATURES.md](FEATURES.md) | Complete tool reference — all actions, parameters, examples |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Build instructions, coding guidelines, PR process |
| [LLM Tests README](tests/Sbroenne.WindowsMcp.LLM.Tests/README.md) | How to run LLM integration tests |
| [Release Setup](.github/RELEASE_SETUP.md) | Azure OIDC and GitHub Actions configuration |

## License

MIT — see [LICENSE](LICENSE)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sbroenne](https://github.com/sbroenne)
- **Source:** [sbroenne/mcp-windows](https://github.com/sbroenne/mcp-windows)
- **License:** MIT
- **Homepage:** https://windowsmcpserver.dev/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sbroenne-mcp-windows
- Seller: https://agentstack.voostack.com/s/sbroenne
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.