windows-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
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.
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
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
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.
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.
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:
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).
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.
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.
Architecture
cmd/windows-mcp-server Cobra/Viper CLI (stdio transport)
internal/winmcp server bootstrap: RunStdio composed from mcp-server-core,
plus the Windows probes, credentials, DACL check and
the go-winio harness dial
internal/desktop the Windows engine — one COM STA thread serving UIA
traversal, SendInput, GDI screenshots, overlays,
PowerShell, plus a WMI worker thread
internal/psdata PowerShell data binding for model-supplied values
pkg/windows MCP tool definitions, personas, and the shim over the
shared toolkit
mcp-server-core (imported) the platform-agnostic half, shared with
macos-mcp-server:
inventory domain-agnostic toolset engine (grouping, filtering,
read-only, resources, prompts)
toolkit dependency injection, argument accessors, result
constructors, assertions, evidence sink, Scrape, Plan/Apply
surface the MCP server construction, pinned capabilities,
completion, cache hints, wire capture
runtime guardrail wiring: policy load, egress provisioning,
harness servant, planner, evidence sealing, journeys
conformance the loopback HTTP host and the suite fixtures
journeys / runrecord journey schema, compiler, recorder output; OTLP run records
mcpspec / mcpconf vendored-schema loader; conformance-results reporting
agentweave-harness (imported) the security stack, split by lifecycle layer:
signals signal vocabulary, probes, registry, checks
audit hash chain, destination, VerifyChain
hostmatch egress allowlist matching + forbidden address ranges
policy document schema, signal cache, engine, verdict
egress the egress proxy + Windows firewall enforcement
enforce the MCP middleware
watch heartbeat, rug-pull, in-flight monitor
contain kill switch, containment ladder, actuator, firewall
status status endpoint, GuardrailStatus + Kill tools
policy/examples starting-point policy documents
schema/ vendored MCP protocol schemas, one dir per revision
All Win32/COM work is serialized onto one STA thread; WMI runs on its own thread-affine worker. Tool handlers receive dependencies from the request context via receiving middleware.
Development
go build ./...
go vet ./...
go test ./... -count=1
golangci-lint run --config=./.golangci.yml
The inventory engine, the parameter helpers, the policy engine and the egress
matcher are cross-platform and tested in their own modules (mcp-server-core,
agentweave-harness); the Windows automation packages build and test only on
Windows, though they cross-compile from anywhere with GOOS=windows. See CONTRIBUTING.md and
CLAUDE.md.
Documentation
docs/ — setup and configuration guides, plus the security architecture and conformance report.
Credits
The tool surface began as a Go port of the Python
Windows-MCP project. It is built on
the go-bindings-win32
and go-bindings-wmi SDKs
and the official MCP Go SDK.
