windows MCP server
Commit Nov 13, 2026Bridges AI agents to the Windows desktop for UI automation, system control, and secure task execution via the accessibility tree.
Also known as deploymenttheory/windows-mcp-server
- Stars
- 17
- Tools
- 16
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is windows MCP?
windows bridges AI agents to the Windows desktop for UI automation, system control, and secure task execution via the accessibility tree. It exposes 16 tools, such as screen, interaction, apps.
Summary generated from the project's README
About windows MCP server
Connecting AI agents to a Windows desktop for UI automation and system management is what this server enables. It allows agents to perceive the interface through the Windows accessibility tree rather than relying on computer vision, using tools like Snapshot, Invoke, and Click to interact with applications. Developers can use it to control processes, manage the registry, execute PowerShell commands, and perform web scraping directly from an MCP client like Claude Desktop or Cursor.
Security is a central focus, as the server includes a device policy engine that evaluates every action against live signals such as BitLocker, TPM attestation, and Secure Boot. It also features an egress allowlist via a loopback proxy to restrict network access to specific domains. To ensure accountability, the server maintains a tamper-evident, hash-chained audit log and provides session recording capabilities. Users can deploy it on Windows 10 or 11 using the stdio subcommand, and it supports specific personas like qa-test-engineer or first-line-support to guide agent behavior.
What you can do with it
- 1Automated UI regression testingA developer can instruct an agent to run a sequence of UI interactions and verify that specific elements appear correctly.
- 2Secure system administrationAdministrators can grant an agent limited access to manage scheduled tasks or registry settings within a controlled policy framework.
- 3Web data extractionAn agent can navigate to specific websites and scrape content using the integrated web toolset.
Written from the project's README. Every use case is checked against a quote from it.
windows MCP tools 16
Detected from the READMEscreeninteractionappssystemsystem-adminshellfilesystemwebdiagnosticstestingplanningpackages
Show all 16 toolsShow fewer tools
credentialsrpa-journeytriage-support-issuecapture-evidence
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledeploymenttheory/windows-mcp-server is public and reachablegithub.com/deploymenttheory/windows-mcp-server ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-06github.com/deploymenttheory/windows-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model16 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubwindows-mcp-server
A Model Context Protocol server that bridges AI agents to the Windows desktop — UI Automation, synthetic mouse/keyboard input, screenshots, window and application control, PowerShell, the registry, processes, the filesystem, and web scraping. No computer-vision model is required: the agent perceives the UI through the Windows accessibility tree.
What separates it from a plain automation bridge is that it is the only Windows MCP server that gates every agent action on live device posture and constrains the agent's network egress, and records both in a tamper-evident audit chain the agent cannot switch off. It turns an agent with system access into an agent whose actions are conditional, bounded, and reviewable.
- Device policy engine — every tool call, resource read and prompt fetch is evaluated against live device signals (MDM enrolment, Entra join, Secure Boot, BitLocker, VBS/HVCI, TPM attestation) before it runs, and refused, warned or contained by policy configuration. Rules match by tool, toolset or annotation, so a screenshot is not gated like a shell command. → Policy configuration
- Egress allowlist — a loopback proxy admits only the domains you declare, checking the allowlist before it resolves a name, optionally backed by firewall rules so named applications — or the whole machine — cannot go around it. → Egress setup
- Tamper-evident transparency — a hash-chained audit log (optionally keyed and anchored off-box), heartbeat, rug-pull detection, whole-session recording, and an out-of-band tiered kill switch. None of it is agent-disableable. → Monitoring · Security architecture
Several tools (PowerShell, Registry, FileSystem, Process, App) have full system access with no sandboxing. That is the design, not an oversight. Run untrusted workloads in a VM or Windows Sandbox — see VM isolation — and see SECURITY.md for what is and is not in scope as a vulnerability.
Quick start
Windows 10 or 11 (amd64 or arm64). Download the archive for your architecture
from GitHub Releases,
then extract it to a stable directory. Starting with releases built by the new
distribution workflow, Claude Desktop on amd64 can install the release .mcpb
directly. Go 1.25+ is needed only to build from source.
.\windows-mcp-server.exe --version
Point any MCP client at the binary with the stdio subcommand:
{
"mcpServers": {
"windows": {
"command": "C:\\path\\to\\windows-mcp-server.exe",
"args": ["stdio", "--persona", "first-line-support"]
}
}
}
→ Getting started covers Claude Code, Cursor, Codex CLI and Claude Desktop specifically, and what to do before pointing this at a machine you care about. Releasing covers signing, distribution and the preview lifecycle.
Not sure this is for you? If you have to approve it on a fleet, read Deciding to deploy this. If you have a job to do, see the walk-throughs for a UI regression suite or a first-line support queue.
Features
| What it does | Guide | |
|---|---|---|
| Desktop automation | 35 tools across 13 toolsets: accessibility-tree perception, UI Automation pattern invocation, synthetic input, screenshots, apps, windows, PowerShell, registry, filesystem, processes, services, event logs, network, scheduled tasks, packages, scraping, plan-and-apply | Toolsets and personas |
| Personas | Presets that select toolsets and inject workflow guidance, so the agent adopts a role rather than just getting a tool list | Toolsets and personas |
| Credentials | The agent signs in to apps and sites without ever being told the secret. The Credentials tool has no read mode and no engine method returns plaintext — but see the note below on toolset exposure |
Credentials |
| Session recording | Once transparency.recording_dir is set, the whole session goes to one video file — automatically, under every persona — with timeline markers |
Session recording |
| Kill switch | Out-of-band, tiered containment. A trip always audits, raises the banner and seals the log; the optional rungs — isolate, kill processes, lock, shut down — run in a fixed order, with the recording finalized before shutdown and the session aborted last | Security architecture |
| MCP conformance | Implemented protocol behavior checked against the latest published spec on every PR | MCP compliance |
On the credentials claim: the guarantee holds at the tool boundary — the
Credentialstool cannot read a secret back and no engine method returns one. Another toolset could once route around it: installed generic credentials live in the calling user's Credential Manager, so a persona that also carriesshell(which canCredRead) orfilesystem(which can read a Credential Manager backup) could retrieve them another way. The server now refuses to start when--credentials-fileis combined with either toolset, unless the policy document acknowledges the exposure (credentials.acknowledge_toolset_exposure), and audits the decision — so the exposure is a deliberate, recorded choice rather than a silent hole. See the trust model.
Tools
Tools are grouped into toolsets. screen, interaction, apps and system
are on by default; the rest are opt-in.
| Toolset | Default | Tools |
|---|---|---|
screen |
✓ | Snapshot, Screenshot, DisplayInventory, Recording |
interaction |
✓ | Click, Type, Invoke, GetText, Scroll, Move, Shortcut, Wait, WaitFor, MultiSelect, MultiEdit |
apps |
✓ | App (launch / switch / resize) |
system |
✓ | Clipboard, Process, Notification |
system-admin |
Registry, ScheduledTask (list / get / run / enable / disable / delete / create) |
|
shell |
PowerShell, LaunchExecutable |
|
filesystem |
FileSystem (read / write / copy / move / delete / list / search / info) |
|
web |
Scrape |
|
diagnostics |
SystemInfo (OS/hardware/disk via WMI), Service (list / start / stop / restart), EventLog (Get-WinEvent queries), Network (adapters / dns / config / test) |
|
testing |
Assert (PASS/FAIL UI condition), CaptureEvidence (screenshot + tree) |
|
planning |
Plan, Apply — propose a whole sequence, adjudicate it up front, then run it verbatim — see Plan and apply |
|
packages |
Package (list / search / install / uninstall via winget and MSI) — downloads run outside the egress proxy; in no persona |
|
credentials |
Credentials (list / verify / inject) — enabled automatically by --credentials-file |
Two more are served under every persona and belong to no toolset:
GuardrailStatus (read-only posture) and Kill (stop the session).
The typical loop: call Snapshot for the foreground window and a labeled
tree of interactive elements, then act on a label with Invoke, Click
or Type. Take a fresh Snapshot after the UI changes.
Resources and prompts
| Resource URI | Contents | Toolset |
|---|---|---|
windows://desktop/snapshot |
The most recent Snapshot — reading it does not capture a new one |
screen |
windows://desktop/displays |
Connected displays: bounds, work area, DPI, scale | screen |
windows://session/recording |
Session-recording status, paths, frame count | screen |
windows://system/info |
OS, hardware, memory and disk inventory | diagnostics |
| Prompt | Purpose | Toolset |
|---|---|---|
rpa-journey |
Drive a scripted end-user journey, verifying each step | interaction |
triage-support-issue |
Diagnose a reported problem, gathering state before acting | diagnostics |
capture-evidence |
Record reproducible evidence for a test or support case | testing |
Resources and prompts are filtered by toolset like tools are, so a prompt
whose toolset is disabled is not served. Prompts build their text from the
matching persona's instructions rather than restating it, so --persona and the
prompts cannot drift apart.
Both are decided by the policy engine: resources/read and prompts/get are
written to the audit log, covered by any rule matching toolset: "*" or
annotation: read-only, and fingerprinted for rug-pull detection.
Personas
.\windows-mcp-server.exe personas # list them
.\windows-mcp-server.exe stdio --persona qa-test-engineer
| Persona | Toolsets | Focus |
|---|---|---|
first-line-support |
screen, interaction, apps, system, shell, diagnostics | Diagnose before acting; SystemInfo/Process/Service + PowerShell |
qa-test-engineer |
screen, interaction, apps, system, filesystem, web, testing | Deterministic UI tests; label targeting, Assert, CaptureEvidence |
business-user |
screen, interaction, apps, web, testing | End-user tasks and journey testing through the real UI; no shell, registry or filesystem |
User-journey testing (RPA)
business-user and qa-test-engineer are built for driving scripted journeys —
open apps, sign into sites, click through flows, check and change settings via
the UI — and verifying each step:
perceive → target → act → synchronize → verify
Snapshot # the foreground window + labeled elements
Invoke {name:"Sign in"} # act via the accessibility pattern (reliable)
WaitFor {condition:active_window, window_name:"Inbox"}
Assert {condition:text_present, text:"Welcome"}
CaptureEvidence {label:"logged in"}
Prefer Invoke over Click/Type. Invoke (and set_value, toggle,
select, expand/collapse) acts through a UI Automation control pattern
rather than synthesizing input, so it does not depend on the window being
focused, unoccluded or at a particular DPI. Journeys are far less flaky.
Click/Type remain the fallback for controls exposing no pattern.
Target by name or label. The targeting tools accept a label from the latest
Snapshot, or a name with optional control_type and nth — so a step reads as
Invoke {name:"Submit", control_type:"Button"}. Click, Type and Move also
accept an explicit loc [x,y]; Invoke and GetText resolve through the
accessibility tree and need a label or a name.
What cannot be automated, by design
These sit on the Windows secure desktop, which no user-session process can see or drive — a platform boundary, not a limitation of this server:
- The sign-in / lock screen and UAC elevation prompts
- Driving elevated apps from a non-elevated process (UIPI)
Design around it: have the harness deliver an already-signed-in, unlocked session, and auto-start the server at logon. "Login" inside a journey then means application and website sign-in, which is fully supported. See Deployment.
Security
📐 Architecture with diagrams: docs/security-architecture.md 📄 Schema reference: docs/policy-config.md
A policy engine sits between the MCP caller and the tools. Before a tool runs, a resource is read or a prompt is fetched, it evaluates device signals against rules in a policy document and decides what happens.
MCP client ──▶ audit ──▶ rug-pull ──▶ policy engine ──▶ tool handler
│
device signals
.\windows-mcp-server.exe stdio --policy-config C:\ProgramData\windows-mcp\policy.json
With no --policy-config the built-in default applies: the engine is
present, every declared signal is evaluated and every verdict recorded, and
nothing is refused. Adopting the engine cannot break a working deployment before
its policy is written.
on_fail |
Effect |
|---|---|
allow |
Proceeds; the failure is still recorded |
warn |
Proceeds, and the warning rides back with the result so the model sees it |
hold |
The call is suspended on an out-of-band human authoriser and fails closed — a timeout, an unreachable webhook or an unintelligible reply all deny |
deny |
This call is refused, and re-evaluated next time — a signal that recovers restores service with no restart |
kill |
The kill switch trips and the containment ladder runs |
Rules match on tool, toolset or MCP annotation, so a screenshot is not gated on the posture a shell command is gated on:
{
"rules": [
{ "name": "baseline", "match": { "toolset": "*" }, "require": ["run-context"], "on_fail": "deny" },
{ "name": "destructive", "match": { "annotation": "destructive" }, "require": ["bitlocker"], "on_fail": "deny" },
{ "name": "shell", "match": { "tool": "PowerShell" }, "require": ["mdm-enrolled"], "on_fail": "kill" }
]
}
Requirements are the union across matching rules, so adding a rule never drops
one. Severity is attributed per signal to the most specific rule requiring it:
tool > annotation > named toolset > "*".
.\windows-mcp-server.exe policy validate --policy-config policy.json # document + signal ids; exits 1
.\windows-mcp-server.exe policy check --policy-config policy.json # this device now; exits 2 if not admitted
.\windows-mcp-server.exe policy explain --policy-config policy.json --tool PowerShell
Six starting points ship in policy/examples/: audit.json (adopt first —
refuses nothing), secure.json, enterprise.json, locked-down.json,
egress.json and dual-control.json.
Trust model — read this
The local device signals (dsregcmd, registry, WMI) are auditable
defense-in-depth, not a hard boundary — a local admin can spoof them. The
containment layers raise the cost of, and record, in-session compromise but do
not replace the OS controls you already own: pair them with WDAC/AppLocker,
Conditional Access and code signing. The authoritative remote signals
(Microsoft Graph, an external may-run endpoint) register only when their
credentials are present — see Remote signals.
Threat model
What each actor can do, what constrains them, and what is left over. The honest column is the last one: several controls raise cost and produce evidence rather than prevent, and this is the register a risk function should read it in. The security architecture maps these to mechanisms.
| Actor | Capability | Control | Residual risk |
|---|---|---|---|
| Prompt-injected agent — the model, driven by hostile content | Issue any tool call the served surface allows | Policy engine gates every call on device posture; rate limits break exfil loops; the egress allowlist bounds network reach; the audit chain records every call with argument digests. Plan-and-apply adjudicates a whole proposed sequence up front, and require_plan can force named or destructive tools through that review |
Benign-annotated calls can still compose into a harmful outcome when they run one at a time outside a plan; scope the surface with personas, gate destructive annotations, and use require_plan where the composition risk is real |
| Malicious MCP client — the host process on the other end of stdio | Swap the tool manifest after approval; probe methods | Manifest fingerprinted at startup; tools/list and discover intercepted; rug-pull monitor trips the kill switch on drift; list_changed suppressed |
The stdio transport assumes a trusted host: a client that never drifts is trusted by construction. There is no network listener to attack |
| Local user — non-admin, same session | Read what the agent reads; use the running server | Credentials never returned to the model; the FileSystem tool refuses the credentials file, the audit key, the audit log, the policy document and the kill-switch control directory; GuardrailStatus/Kill cannot be removed |
A user already holds their own privileges; the server does not raise them. The protected-path check binds the FileSystem tool only — PowerShell reaches the same files unchecked, which is why the shell toolset requires an explicit acknowledgement to be served alongside credentials. Registry and ScheduledTask now live in the non-default system-admin toolset |
| Local administrator | Spoof device signals; edit the audit log; disable transparency | Local signals are defense-in-depth, not a boundary; the audit chain is tamper-evident, and keying + off-box anchoring raise the bar; pair with WDAC/AppLocker and Conditional Access | An admin can defeat any on-box control — the value is evidence that survives, not prevention. The audit HMAC key sits on the box unless anchored off it; path protection matches by cleaned path, not 8.3 names or hard links |
| Network attacker | Reach the server; intercept egress | No inbound listener — the transport is stdio only; the egress proxy checks the allowlist before any DNS query and re-checks resolved addresses against loopback/RFC1918/link-local before dialling | Enforce HTTPS and the egress proxy do not intercept navigation inside an already-open browser; the proxy-only enforcement tier is advisory until backed by firewall rules |
Egress: the domains the device may reach
Declare an allowlist and everything else is dropped:
"egress": {
"enabled": true,
"allow": ["*.contoso.com", "login.microsoftonline.com"],
"allow_ports": [443]
}
A loopback CONNECT/HTTP proxy enforces it. *.contoso.com covers the apex and
every depth below it, anchored at a label boundary so fakecontoso.com never
matches. The allowlist is checked before the name is resolved — a refused
host emits no DNS query — and resolved addresses are re-checked against
loopback, RFC1918 and link-local ranges before anything is dialled, so an
allowed name cannot be pointed at something internal. TLS is never intercepted;
there is no CA and nothing is decrypted.
Three enforcement tiers:
| Tier | What forces traffic through the proxy |
|---|---|
proxy-only |
Nothing — it constrains whatever is configured to use it. No elevation |
scoped |
Outbound-block firewall rules on named applications. Loopback stays reachable, so the proxy is their only route out |
global |
The machine's default outbound action becomes block, with a service-scoped exception set for DNS, DHCP, NCSI, time, update and revocation |
Both firewall tiers need elevation and refuse to start without it rather than serving a weaker posture than the document describes.
→ Egress setup — per-tier procedure, browser configuration, verification and recovery.
Flags and environment
Every flag has a WINDOWS_MCP_-prefixed environment variable (--read-only ↔
WINDOWS_MCP_READ_ONLY).
| Flag | Description |
|---|---|
--policy-config |
Path to the device-policy JSON document. Omit for the built-in default |
--toolsets |
Comma-separated toolsets to enable (all, default, or specific ids) |
--tools |
Additionally enable individual tools (bypasses toolset filtering) |
--exclude-tools |
Disable specific tools; applied last |
--read-only |
Expose only read-only tools |
--persona |
Select a persona preset |
--overlay |
Visual feedback overlays (see below) |
--record-fps |
Recording frame rate (default 4) |
--record-codec |
h264/h265 (via ffmpeg; small files) or mjpeg (pure-Go, no dependency) |
--credentials-file |
JSON file of credentials to install at init |
--log-file |
Write debug logs to a file (stdout is reserved for the transport) |
Secrets in the environment
Key material and credentials are environment-only, never flags or the policy
document — argv is world-readable and the policy is meant to be reviewed and
checked in. The suffix says how the value is delivered:
…_KEY/…_TOKEN/…_SECRET/…_HEADERShold the value inline.…_KEY_FILEholds a path to a file whose contents are the material — used where the material is a key file with its own ACLs (the ed25519 evidence signing seed), so it never sits in the process environment.
| Variable | Delivery | Purpose |
|---|---|---|
WINDOWS_MCP_AUDIT_KEY |
value | HMAC key that seals the audit chain (absent → unkeyed) |
WINDOWS_MCP_APPROVAL_KEY |
value | HMAC key signing dual-control webhook requests |
WINDOWS_MCP_EVIDENCE_KEY_FILE |
path | ed25519 seed that signs evidence bundles |
WINDOWS_MCP_OTLP_HEADERS |
value | k=v,k=v auth headers for the OTLP collector |
WINDOWS_MCP_GRAPH_TENANT / _CLIENT_ID / _CLIENT_SECRET |
value | Graph/Intune tier-2 signal credentials |
WINDOWS_MCP_REMOTE_POLICY_TOKEN |
value | bearer token for the remote may-run endpoint |
WINDOWS_MCP_EXPORT_SIGNED_URL (…_MANIFEST, …_SIGNATURE) |
value | pre-signed PUT / SAS / signed URL the sealed evidence bundle is shipped to. A documented exception to the suffix rule: it is a write credential whose only sensible shape is a URL |
whatever egress.auth_token_env names |
value | Proxy-Authorization secret the egress proxy requires |
Everything the security subsystem does — which signals are read and how often, which rules cover which tools, what a failure does, what trips the kill switch and what it actuates, where the audit chain goes, whether the session is recorded, which domains are reachable — is configured in the policy document rather than by flags. The questions are relational, and a flag cannot express a relation: "PowerShell requires MDM enrolment but taking a screenshot does not" has no spelling as a set of booleans. docs/policy-config.md carries a table mapping each removed flag to its field.
Running as SYSTEM
Session 0 has no desktop to drive, so if the server detects it is running as
SYSTEM the desktop-automation toolsets are dropped and the selection is replaced
with system, shell, filesystem, diagnostics, web. This is detected, not
declared. A persona explicitly requested under SYSTEM is refused — the server
exits rather than serving a reshaped version of it.
Visual feedback overlays
--overlay draws click-through, top-most overlays so a viewer can see what the
automation is doing — a green hue around the focused window on each
Snapshot, and an orange flash at each click point. They never intercept
input or take focus.
MCP conformance
Every PR runs the required MCP spec gate against the latest published MCP revision. It captures the product's actual advertised surface and raw wire responses, checks the definitions and safe method calls against the published schema, and fails if a newer revision needs assessment. The check covers the features this server implements, without assigning a percentage for optional features it does not implement. See MCP spec gate.
windows MCP questions
What tools does windows MCP provide?
It exposes 16 tools, including screen, interaction, apps, system, system-admin.
Does this server require a computer-vision model?
No, the agent perceives the UI through the Windows accessibility tree.
How does the server handle security and agent actions?
It uses a device policy engine to evaluate every tool call against live device signals and constrains network egress via a loopback proxy.
Is the agent's activity recorded?
Yes, it features a tamper-evident audit log and optional whole-session video recording.