powershell-mcp

Overview Schema Source Related Servers Discussions Admin

run_powershell

Executes PowerShell scripts or commands on a Windows host in a hidden process, returning stdout, stderr, and exit code for any Windows command, file, or system task.

Instructions

Run a PowerShell script/command on this Windows host in a hidden process (no console window appears). Returns stdout, stderr and exit code. Use for any Windows command, file, or system task.

Input Schema

Name	Required	Description
`cwd`	No	Working directory.
`tail`	No	Keep last bytes rather than first; incomplete UTF-8 boundary scalars are omitted.
`engine`	No	Explicit engine; no fallback when specified. Omit to use only configured PWSH_MCP_EXE if set; otherwise try pwsh then powershell.exe on Windows (pwsh only elsewhere).
`script`	Yes	PowerShell script or command to execute.
`logOutput`	No	Opt in to private file-backed raw output logs; may include secrets emitted by command.
`timeoutMs`	No	Hard timeout in ms (default 60000).
`parameters`	No	JSON-safe named script parameters, delivered via stdin; never interpolated into source.
`errorPolicy`	No	Default legacy raw script; strict detects unhandled PowerShell ErrorRecords. Check native exits immediately in the script.
`logQuotaBytes`	No	Combined stdout/stderr quota (default 8 MiB); incomplete beyond quota.
`maxOutputBytes`	No	Raw UTF-8 bytes per stream (default 1 MiB).

Output Schema

Name	Required	Description	Default
`log`	No
`detail`	Yes
`stderr`	Yes
`stdout`	Yes
`target`	Yes
`exitCode`	Yes
`timedOut`	Yes
`transport`	Yes
`durationMs`	Yes
`truncation`	Yes
`executionId`	Yes
`errorRecords`	No
`schemaVersion`	Yes
`terminationStatus`	Yes
`terminationCertainty`	Yes
`errorRecordsTruncated`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.7.0Oct 24, 2026

addedInput schema / properties / engine

Added value: +{
+  "description": "Explicit engine; no fallback when specified. Omit to use only configured PWSH_MCP_EXE if set; otherwise try pwsh then powershell.exe on Windows (pwsh only elsewhere).",
+  "enum": [
+    "pwsh"
+  ],
+  "type": "string"
+}

addedInput schema / properties / errorPolicy

Added value: +{
+  "description": "Default legacy raw script; strict detects unhandled PowerShell ErrorRecords. Check native exits immediately in the script.",
+  "enum": [
+    "legacy",
+    "strict"
+  ],
+  "type": "string"
+}

addedInput schema / properties / logOutput

Added value: +{
+  "description": "Opt in to private file-backed raw output logs; may include secrets emitted by command.",
+  "type": "boolean"
+}

addedInput schema / properties / logQuotaBytes

Added value: +{
+  "description": "Combined stdout/stderr quota (default 8 MiB); incomplete beyond quota.",
+  "exclusiveMinimum": 0,
+  "maximum": 8388608,
+  "type": "integer"
+}

addedInput schema / properties / maxOutputBytes

Added value: +{
+  "description": "Raw UTF-8 bytes per stream (default 1 MiB).",
+  "exclusiveMinimum": 0,
+  "maximum": 8388608,
+  "type": "integer"
+}

addedInput schema / properties / parameters

Added value: +{
+  "additionalProperties": {},
+  "description": "JSON-safe named script parameters, delivered via stdin; never interpolated into source.",
+  "propertyNames": {
+    "pattern": "^[a-zA-Z_][a-zA-Z_0-9]*$",
+    "type": "string"
+  },
+  "type": "object"
+}

addedInput schema / properties / tail

Added value: +{
+  "description": "Keep last bytes rather than first; incomplete UTF-8 boundary scalars are omitted.",
+  "type": "boolean"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "detail": {
+      "additionalProperties": false,
+      "properties": {
+        "bytes": {
+          "type": "number"
+        },
+        "cleanup": {
+          "enum": [
+            "not_needed",
+            "removed",
+            "failed",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "direction": {
+          "enum": [
+            "upload",
+            "download"
+          ],
+          "type": "string"
+        },
+        "error": {
+          "type": "string"
+        },
+        "finalized": {
+          "type": "boolean"
+        },
+        "localExitCode": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "sha256": {
+          "type": "string"
+        },
+        "shell": {
+          "type": "string"
+        },
+        "signal": {
+          "type": "string"
+        },
+        "verification": {
+          "enum": [
+            "not_started",
+            "sha256_matched",
+            "failed"
+          ],
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "durationMs": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "errorRecords": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "type": "string"
+          },
+          "exceptionType": {
+            "type": "string"
+          },
+          "fullyQualifiedErrorId": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "category",
+          "fullyQualifiedErrorId",
+          "exceptionType",
+          "message"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "errorRecordsTruncated": {
+      "type": "boolean"
+    },
+    "executionId": {
+      "type": "string"
+    },
+    "exitCode": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "log": {
+      "additionalProperties": false,
+      "properties": {
+        "complete": {
+          "type": "boolean"
+        },
+        "expiresAt": {
+          "type": "string"
+        },
+        "handle": {
+          "type": "string"
+        },
+        "stderrBytes": {
+          "type": "number"
+        },
+        "stdoutBytes": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "handle",
+        "complete",
+        "stdoutBytes",
+        "stderrBytes",
+        "expiresAt"
+      ],
+      "type": "object"
+    },
+    "schemaVersion": {
+      "const": 1,
+      "type": "number"
+    },
+    "stderr": {
+      "type": "string"
+    },
+    "stdout": {
+      "type": "string"
+    },
+    "target": {
+      "type": "string"
+    },
+    "terminationCertainty": {
+      "enum": [
+        "unknown",
+        "root_exited"
+      ],
+      "type": "string"
+    },
+    "terminationStatus": {
+      "enum": [
+        "completed",
+        "nonzero_exit",
+        "script_error",
+        "remote_error",
+        "timeout",
+        "cancelled",
+        "transport_error",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "timedOut": {
+      "type": "boolean"
+    },
+    "transport": {
+      "enum": [
+        "powershell",
+        "program",
+        "winrm",
+        "ssh",
+        "sftp"
+      ],
+      "type": "string"
+    },
+    "truncation": {
+      "additionalProperties": false,
+      "properties": {
+        "limitBytesPerStream": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "stderr": {
+          "additionalProperties": false,
+          "properties": {
+            "capturedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "observedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "omittedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "truncated": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "observedBytes",
+            "capturedBytes",
+            "omittedBytes",
+            "truncated"
+          ],
+          "type": "object"
+        },
+        "stdout": {
+          "additionalProperties": false,
+          "properties": {
+            "capturedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "observedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "omittedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "truncated": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "observedBytes",
+            "capturedBytes",
+            "omittedBytes",
+            "truncated"
+          ],
+          "type": "object"
+        },
+        "truncated": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "truncated",
+        "limitBytesPerStream"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "executionId",
+    "transport",
+    "target",
+    "stdout",
+    "stderr",
+    "exitCode",
+    "durationMs",
+    "timedOut",
+    "truncation",
+    "terminationStatus",
+    "terminationCertainty",
+    "detail"
+  ],
+  "type": "object"
+}

First observedv0.5.0Aug 6, 2026

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral burden. It usefully discloses that execution happens in a hidden process with no console window and that stdout, stderr, and exit code are returned. It does not mention privilege level, destructive potential, timeout behavior, output truncation, or errorPolicy implications, which are significant for an arbitrary command-execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with no filler. The core action and execution context are front-loaded, followed by return values and the broad intended use.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, the input schema is fully described, and the description covers the essential action, hidden-process behavior, and return streams. For a ten-parameter arbitrary execution tool with no annotations, it could more explicitly address safety, privileges, and sibling alternatives, but an agent has enough to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all ten parameters are already documented in the schema itself. The description adds no parameter-specific meaning beyond what the schema provides, such as timeout defaults or how cwd/engine interact. The baseline of 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: run a PowerShell script/command on this Windows host in a hidden process. It also says what is returned (stdout, stderr, exit code), making the operation recognizable. It does not explicitly distinguish itself from siblings such as run_program, ssh_exec, or winrm_exec, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says to use it for 'any Windows command, file, or system task,' which gives a broad usage context. However, it does not say when not to use it or when to prefer run_program, ssh_exec, or winrm_exec. The guidance is implied rather than explicit routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.