Powershell MCP

powershell-mcp

A Model Context Protocol server that gives AI agents real, non-intrusive access to Windows PowerShell.

Most tools that let an agent run Windows commands spawn a visible console window for every call — which steals focus and interrupts whatever you're typing. powershell-mcp runs everything in a hidden process (windowsHide: true / no CreateWindow), captures structured output, enforces hard timeouts, and exposes purpose-built tools for service and system management. Built for running unattended next to a human at the keyboard.

Why

• Hidden process configuration. Local child creation uses windowsHide: true; foreground focus preservation needs interactive desktop acceptance and is not established by headless CI.
• Structured + safe. Every call returns { stdout, stderr, exit_code, duration, timed_out }. Hard timeout with tree-kill. Output is capped so a runaway command can't flood the context.
• Real Windows management. First-class tools for services and system info, not just a raw shell — handy for managing Windows servers and backup systems.
• Cross-shell. Prefers pwsh (PowerShell 7+) and falls back to powershell.exe; override with PWSH_MCP_EXE.

Tools

The ten execution tools advertise a versioned MCP outputSchema and return the same structuredContent contract (schemaVersion: 1) alongside their original human-readable text. Fields are executionId (per call), transport, target, stdout, stderr, nullable exitCode, durationMs, timedOut, truncation (truncated, nullable limitBytesPerStream), terminationStatus, and detail. terminationStatus is one of completed, nonzero_exit, remote_error, timeout, script_error, cancelled, transport_error, or unknown. Any status other than completed sets MCP isError; this is execution status, not proof that an application operation succeeded. A null exit code never means success. SSH includes a signal or connection error in detail; an unsolicited signal is unknown, not caller cancellation. SFTP includes direction and verified local file size where available. WinRM validates a locally framed invocation result: successful invocation is completed, remote script errors are remote_error, and connection failures are transport_error. Its *local* PowerShell host exit is in detail.localExitCode; remote native exitCode remains null. Missing or truncated frames fail closed. terminationCertainty is root_exited only for an observed local child exit, otherwise unknown; neither status proves descendants or remote execution stopped after a timeout. These results never include authentication options or credential values.

Optional raw output logs

run_program, run_powershell (legacy or strict), winrm_exec, and ssh_exec accept logOutput: true and optional logQuotaBytes (default/max 8 MiB combined stdout and stderr). Disabled by default: no log directory is created without opting in. Raw child output is written separately per stream, independently of the display byte cap. Strict PowerShell persists validated command payload stdout; WinRM also persists its validated remote console stderr. Framing, credentials, stdin, and wrapper diagnostics are never persisted. A result's log contains an unpredictable process-local handle, complete, byte counts, and expiry timestamp. complete: false means producer truncation, quota loss, or a write failure; never interpret it as the entire output. Read through read_output_log with handle, stream, byte offset and length (maximum 65,536 bytes); data is base64, and nextOffset/totalBytes support pagination. delete_output_log removes a log. Handles are available only in this MCP process, never filesystem paths; only the current OS user and SYSTEM have directory ACL access on Windows (0700/0600 on POSIX). The process reserves at most 64 MiB total, expires completed handles one hour after finish on the next log operation (active handles remain reserved), and removes its own files on normal exit. A hard crash may leave private files requiring operator cleanup under the configured POWERSHELL_MCP_LOG_PARENT or TMPDIR, otherwise the OS temp path. Commands can emit secrets: opt-in logs preserve emitted stdout/stderr verbatim, so do not enable logging for sensitive commands. Passwords, stdin and MCP envelopes are never intentionally logged. Framed payload retention is bounded to the larger of the display cap and log quota per stream before JSON/base64 transport. The log quota remains combined across both streams; complete: false reports any producer truncation or log quota loss. Tail mode can therefore produce an incomplete suffix log.

Execution tools accept maxOutputBytes (1–8,388,608, default 1 MiB per stream) and tail (default false: retain the head; true: retain the tail). truncation.stdout and .stderr, when the producer observed stream bytes, report observedBytes, capturedBytes, omittedBytes, and truncated on the original UTF-8 input bytes. capturedBytes + omittedBytes = observedBytes; these are not lengths of pretty-printed text. An incomplete UTF-8 scalar at a head/tail cut is omitted and counted as such. Malformed input is displayed with replacement characters; its captured count refers to original bytes, not the encoded replacement characters. Raw structured stdout/stderr preserve newlines; human-readable formatting may trim whitespace. Wrapper-generated diagnostics are not producer bytes and have no invented stream counts. Some failed/early remote calls cannot report producer-side byte counts. No full logs are persisted by default; opt-in runs return a protected output-log handle. Strict PowerShell and WinRM stream formatted pipeline lines into a fixed-capacity UTF-8 writer, counting all bytes after retention fills. WinRM runs this writer inside the remote script block, before remoting serialization. Direct console stdout joins payload stdout without corrupting framing; remote console stderr has a separate bounded writer and counters. Error summaries retain at most eight shortened records as errors arrive. Producer retention is O(cap), with fixed encoding scratch space; terminal JSON/base64 envelopes and local pipe capture also have finite bounds. This does not bound memory allocated by user scripts, individual objects/lines, PowerShell formatting, or remoting internals. The writer requires Add-Type in each execution runspace; constrained endpoints that forbid compilation are unsupported and fail closed. Counts describe rendered UTF-8 pipeline output, with platform newlines from Out-String -Stream, and UTF-8 console text, rather than original native program bytes. Use run_program for native byte provenance.

Strict/WinRM return payload output only after a validated terminal frame. Timeout, cancellation, malformed frames, or direct OS stdout writes that bypass the console writer fail closed without inventing producer counts or returning frame data as command output; unfinished framed logs are discarded. MCP cancellation requests termination of the local PowerShell process tree and releases its log reservation; it does not prove that remote work or descendants stopped.

Opt-in verified staged SFTP

sftp_upload and sftp_download accept staged: true (default false). The default retains the legacy direct fastPut/fastGet behavior; it does not promise destination preservation or content verification. Staged transfers create an exclusive, unpredictable .part file beside the destination, verify SHA-256 against a readback, and finalize without replacing an existing destination. Upload uses the server's hardlink@openssh.com extension for no-clobber finalization; servers without that capability fail closed rather than falling back to an overwriting rename. Download uses a local hard link for no-clobber finalization. The staging and destination paths must support hard links on the same filesystem; filesystem permissions, server extension behavior and concurrent external writers can still cause failure. Only an exclusively created temporary path is eligible for cleanup; an existing destination is not deleted.

Structured detail adds verification (not_started, failed, or sha256_matched), finalized (true/false, or absent when a remote finalization request was sent but its outcome is unknown), cleanup (not_needed, removed, or failed, or unknown when remote staging may remain), sha256 on verified success, and bytes when the staged copy's size was observed. A cleanup failure after successful finalization may report a failed operation with finalized: true; reconcile the destination and orphaned staging file separately. On timeout or connection loss, the reported cleanup is not proof that remote work stopped or no orphan remains. In particular, do not retry an ambiguous finalization as though finalized: false had been proved. SHA-256 readback checks observed bytes, not an immutable source snapshot: source files must be kept stable by the caller; concurrent mutation outside the observed comparison window is not prevented, and there is no source lock.

Only synthetic loopback SFTP fixtures exercise this feature in the repository; live-server extension behavior, filesystem semantics, and permissions remain unverified and require operator validation before deployment.

Native programs: Historical #1 observed missing native stdout from a hidden PowerShell host for particular executables. This is not universal: on a Windows PowerShell 5.1 local probe (October 20, 2026), cmd.exe /d /c echo NATIVE_CMD_24, git.exe --version, and node.exe --version all produced captured stdout. That probe does not reproduce or refute the original gh.exe/where.exe failure on its host. Prefer run_program (direct exec) when you need native arguments, exit status and stdout/stderr independent of PowerShell pipeline behavior; use run_powershell for cmdlets and scripts. Validate the specific executable and host before relying on either path.

Typed inputs: run_powershell accepts engine: "pwsh" | "powershell" (Window