How do I install Windows?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Windows need an API key?

No required environment variable is listed on this record.

What transport does Windows use?

Windows runs locally over stdio.

Windows MCP server

Q: When was Windows last checked?

Last checked 2026-10-27. A MCP 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.

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

	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 Credentials tool 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 carries shell (which can CredRead) or filesystem (which can read a Credential Manager backup) could retrieve them another way. The server now refuses to start when --credentials-file is 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

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 , 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

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 / …_HEADERS hold the value inline.
…_KEY_FILE holds 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.

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.

Windows

Add this server

Host a copy with our keys and logs.

Server facts

About Windows

Tools

Questions

How do I install Windows?

Does Windows need an API key?

What transport does Windows use?

When was Windows last checked?

Documentation

windows-mcp-server

Quick start

Features

Tools

Resources and prompts

Personas

User-journey testing (RPA)

What cannot be automated, by design

Security

Trust model — read this

Threat model

Egress: the domains the device may reach

Flags and environment

Secrets in the environment

Running as SYSTEM

Visual feedback overlays

MCP conformance

Architecture

Development

Documentation

Credits