Skip to main content
Glama
Sign In
SSH MCP Server

SSH MCP Server

by YawLabs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ssh_exec

Execute shell commands on remote hosts over SSH, including pipes, redirects, and globs, and return exit status, stderr, and stdout for reliable automation.

Instructions

Execute a command on a remote host via SSH. The command is interpreted by the remote login shell — pipes, redirects, globs, and other shell metacharacters work as expected. Returns up to three content blocks in this order: the status ([exit code: N], plus the signal and any truncation), then [stderr], then [stdout]. Status comes first so a proxy that cuts long results (Yaw MCP keeps about 100 KB) never drops the exit code; for big output, filter or page on the remote (head, tail, grep). Use env to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked against the env-prefixed command).

Input Schema

NameRequiredDescriptionDefault
envNoEnvironment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. VALUES are POSIX-single-quoted, so any byte is safe in a value. KEYS cannot be quoted (a shell assignment prefix requires a bare name), so each key must match /^[A-Za-z_][A-Za-z0-9_]*$/ (the POSIX name grammar) — a key outside that grammar is rejected and the call fails before anything is sent to a host. Command policy is checked against the PREFIXED command, so a `^`-anchored whitelist pattern stops matching once this is set.
hostYesSSH hostname or IP address
portNoSSH port (default: 22)
commandYesShell command to execute on the remote host (interpreted by the remote login shell)
timeoutNoCommand timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately.
passwordNoSSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process.
usernameNoSSH username (default: current user)
privateKeyPathNoPath to SSH private key

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.17.0
    • changedInput schema / properties / env / description
      Previous value: -"Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. Values are POSIX-single-quoted, so any byte is safe."New value: +"Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. VALUES are POSIX-single-quoted, so any byte is safe in a value. KEYS cannot be quoted (a shell assignment prefix requires a bare name), so each key must match /^[A-Za-z_][A-Za-z0-9_]*$/ (the POSIX name grammar) — a key outside that grammar is rejected and the call fails before anything is sent to a host. Command policy is checked against the PREFIXED command, so a `^`-anchored whitelist pattern stops matching once this is set."
    • changedInput schema / properties / timeout / description
      Previous value: -"Command timeout in milliseconds (default: 30000)"New value: +"Command timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately."
  2. Changed1 schema field changedv0.11.0
    • addedInput schema / properties / env
      Added value: +{
+  "additionalProperties": {
+    "type": "string"
+  },
+  "description": "Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. Values are POSIX-single-quoted, so any byte is safe.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}
  3. Changed9 schema fields changedv0.9.1
    • removedInput schema / additionalProperties
      Removed value: -false
    • changedInput schema / properties / command / description
      Previous value: -"Shell command to execute on the remote host"New value: +"Shell command to execute on the remote host (interpreted by the remote login shell)"
    • changedInput schema / properties / password / description
      Previous value: -"SSH password (prefer keys)"New value: +"SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process."
    • addedInput schema / properties / port / maximum
      Added value: +65535
    • addedInput schema / properties / port / minimum
      Added value: +1
    • changedInput schema / properties / port / type
      Previous value: -"number"New value: +"integer"
    • addedInput schema / properties / timeout / exclusiveMinimum
      Added value: +0
    • addedInput schema / properties / timeout / maximum
      Added value: +9007199254740991
    • changedInput schema / properties / timeout / type
      Previous value: -"number"New value: +"integer"
  4. First observedv0.2.0

TDQS

A4/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so well: it discloses the exact three-block return ordering, the rationale for status-first (proxy truncation near 100 KB), and that SSH_MCP_COMMAND_WHITELIST/BLACKLIST may reject the call. These are non-obvious behaviors an agent cannot get from schema or annotations.

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

Conciseness4/5

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

Front-loaded with the core action, then layered with return format, truncation rationale, and policy notes — each sentence adds information. Slightly dense with implementation-specific detail (the ~100 KB Yaw MCP figure) that could be trimmed.

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

Completeness5/5

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

For an 8-parameter, nested-object tool with no output schema and no annotations, the description covers what an agent needs: execution semantics, return block layout, truncation behavior, output-size mitigation, env injection, and policy enforcement. Nothing critical to a correct call is missing.

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 the schema already documents host, port, timeout, password, and the env quoting/grammar rules in detail. The description only adds the note that policy is checked against the env-prefixed command, which is largely duplicative of the env property's own text.

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 ("Execute a command on a remote host via SSH") and clarifies that the remote login shell interprets metacharacters. It never names a sibling, so an agent must infer that ssh_read_file/ssh_write_file/ssh_ls are the narrower alternatives for those operations.

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?

Usage guidance is implied rather than explicit: it recommends remote-side filtering (head, tail, grep) for large output and explains `env` for per-call variables, but never says when to prefer ssh_exec over ssh_multi_exec, ssh_read_file, or ssh_tail. The agent gets operational hints but no routing rules.

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