Skip to main content
Glama
Sign In
powershell-mcp

powershell-mcp

by IMRRD
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ssh_exec

Run commands on remote Linux or OpenSSH hosts over SSH without ssh.exe or WSL. Authenticate with a key or password and return stdout, stderr, and exit code.

Instructions

Run a command on a remote host over SSH, fully in-process (no ssh.exe, no WSL — works headless). Use for Linux hosts or any OpenSSH target. Auth via privateKeyPath or password. Returns stdout, stderr, exit code.

Input Schema

NameRequiredDescriptionDefault
hostYesRemote host or IP.
portNoSSH port (default 22).
tailNoKeep the LAST maxOutputBytes instead of the first (tail) — useful for long logs.
jumpsNo
commandYesCommand to run on the remote host.
passwordNoPassword auth (used if no key).
usernameYesSSH username.
logOutputNoOpt in to private file-backed raw output logs; may include secrets emitted by command.
timeoutMsNoHard timeout in ms (default 60000). Also bounds the connection handshake.
passphraseNoPassphrase for the private key, if any.
hostKeyPinsNoExplicit SHA256:base64 trusted host key fingerprints; multiple keys permit rotation.
credentialRefNoOperator-provisioned scoped credential reference, exclusive with raw auth.
logQuotaBytesNoCombined stdout/stderr quota (default 8 MiB); incomplete beyond quota.
maxOutputBytesNoCap captured stdout/stderr per stream (bytes, default 1 MiB).
privateKeyPathNoPath to a private key file on this Windows host, e.g. C:\\Users\\isak\\.ssh\\id_ed25519.

Output Schema

NameRequiredDescriptionDefault
logNo
detailYes
stderrYes
stdoutYes
targetYes
exitCodeYes
timedOutYes
transportYes
durationMsYes
truncationYes
executionIdYes
errorRecordsNo
schemaVersionYes
terminationStatusYes
terminationCertaintyYes
errorRecordsTruncatedNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.7.0
    • addedInput schema / properties / credentialRef
      Added value: +{
+  "description": "Operator-provisioned scoped credential reference, exclusive with raw auth.",
+  "type": "string"
+}
    • addedInput schema / properties / hostKeyPins
      Added value: +{
+  "description": "Explicit SHA256:base64 trusted host key fingerprints; multiple keys permit rotation.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / jumps
      Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "credentialRef": {
+        "type": "string"
+      },
+      "host": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "hostKeyPins": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "passphrase": {
+        "type": "string"
+      },
+      "password": {
+        "type": "string"
+      },
+      "port": {
+        "maximum": 65535,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "privateKeyPath": {
+        "type": "string"
+      },
+      "username": {
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "host",
+      "username"
+    ],
+    "type": "object"
+  },
+  "maxItems": 4,
+  "type": "array"
+}
    • 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"
+}
    • 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"
+}
  2. First observedv0.5.0

TDQS

A4/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that execution is fully in-process, works headless, needs key or password auth, and returns stdout/stderr/exit code, but it does not warn that arbitrary remote commands run with the authenticated user's privileges, may have persistent side effects, or discuss host-key verification expectations beyond what the schema already covers.

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 compact sentences, front-loaded with the core action and followed by targeting, auth, and return-value details. Every sentence earns its place.

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?

The tool has an output schema and high parameter description coverage, so the description does not need to explain all fields. It covers the SSH transport, auth methods, and return tuple, but could do more to clarify risk and side effects for arbitrary command execution.

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 93%, so the input schema already documents nearly all parameters thoroughly. The description only highlights the privateKeyPath/password auth choice and adds no meaningful semantics beyond the schema.

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

Purpose5/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 command on a remote host over SSH. It also adds differentiating scope ('Linux hosts or any OpenSSH target'), which helps distinguish it from Windows-oriented siblings such as winrm_exec and run_powershell.

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

Usage Guidelines4/5

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

Gives clear usage context: use it for Linux/OpenSSH targets, with authentication via privateKeyPath or password. It does not explicitly name winrm_exec as the alternative for Windows hosts, but the Linux/OpenSSH framing is strong enough to guide selection.

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

Deploy Server

Other Tools