ssh-usage

name	ssh-usage
description	Usage guide for ssh-mcp MCP server tools. Load when using execute_ssh_command, upload_file, download_file, find, systemd_service, reboot, or ping tools to manage remote Linux hosts over SSH.

ssh-mcp Usage Guide

This guide covers how to effectively use the ssh-mcp MCP server tools to manage remote Linux systems over SSH.

Available Tools

ping — Check connectivity

Test whether a host is reachable before doing anything else. Returns reachable, latency_ms, and uptime.

Always ping a host first if you're unsure it's online.

execute_ssh_command — Run shell commands

Execute a shell command on a remote host. Returns stdout, stderr, exit_code, timed_out, truncated, and duration_seconds.

Key parameters:

• host (required): Hostname or IP address.
• command (required): Shell command to run.
• working_directory: Set the working directory for this command. Does NOT persist between calls — every invocation starts from the user's home directory unless you set this.
• sudo: Run with elevated privileges. Requires NOPASSWD sudo on the remote host.
• port: SSH port, defaults to 22.

find — Search for files and directories

Returns structured JSON results with path, size, mtime, owner, type (f/d/l), and mode for each entry. Supports name (substring filter), file_type (f or d), and max_depth filtering.

Prefer find over execute_ssh_command with ls or shell find — it returns structured data that's easier to work with.

upload_file — Write text files to remote hosts

Upload UTF-8 text content to a remote path via SFTP. Supports sudo for writing to privileged paths (stages to /tmp then sudo mv).

download_file — Read text files from remote hosts

Download a text file's contents via SFTP. Supports sudo for reading privileged files (uses sudo cat). Output may be truncated if the file exceeds the server's max output size (default 1 MiB).

systemd_service — Manage systemd units

Perform actions on systemd services: start, stop, restart, reload, enable, disable, or status. Always returns current unit state after the action. Only these actions are allowed — anything else is rejected.

reboot — Reboot a remote host

Requires confirm: true as a safety flag. Waits up to wait_timeout seconds (default 120) for the host to come back online, polling SSH connectivity. Returns rebooted, came_back, and downtime_seconds.

Critical Behaviors

Commands are stateless

Every execute_ssh_command call starts a fresh shell session. There is no persistent shell — cd /tmp in one call has no effect on the next. Use working_directory to set the cwd per-call.

Wrong:

call 1: execute_ssh_command(host, "cd /var/log")
call 2: execute_ssh_command(host, "cat syslog")  # runs in home dir, not /var/log

Right:

execute_ssh_command(host, "cat syslog", working_directory="/var/log")

Or combine into one command:

execute_ssh_command(host, "cd /var/log && cat syslog")

CIDR allowlist

The server only allows connections to hosts within the configured CIDR ranges. If a host is outside the allowlist, every tool call returns an error. You cannot change this at runtime — it's a server-side security control.

Timeouts

Commands have a server-configured default timeout (typically 30s). When a command times out, the server sends SIGTERM to the remote process, waits briefly, then SIGKILL. The response will have timed_out: true and exit_code: -1, with whatever partial output was captured.

For long-running commands, consider:

• Running them in the background: nohup command > /tmp/output.log 2>&1 &
• Checking output later: execute_ssh_command(host, "cat /tmp/output.log")

Output truncation

Both command output and file downloads are capped at the server's max output size (default 1 MiB). When output is truncated, the response includes truncated: true. For large files, download in chunks or use head/tail to get specific portions.

SSH credentials

Username and SSH key are configured server-side. You do not provide credentials per-call — the server handles authentication automatically.

Best Practices

1. Ping first — Before running commands on a host, use ping to verify connectivity, especially after reboots or when working with hosts you haven't touched recently.

2. Use find for exploration — When you need to locate files, prefer the find tool over execute_ssh_command with shell find/ls. It returns structured JSON you can reason about directly.

3. Use systemd_service for services — Don't manually run systemctl via execute_ssh_command. The systemd_service tool validates actions, sanitizes unit names, and always returns structured state.

4. Combine related commands — Since each call is a separate SSH session, chain related commands with && to avoid multiple round trips:

   execute_ssh_command(host, "apt-get update && apt-get install -y nginx")
   

5. Check exit codes — Always check exit_code in the response. A command can produce stdout but still fail (exit code != 0).

6. Handle sudo correctly — Use the sudo parameter on the tool rather than prefixing commands with sudo yourself. The tool handles the wrapping properly. The remote user must have NOPASSWD sudo configured.

7. Be cautious with reboot — The reboot tool requires explicit confirm: true. After a reboot, use ping to verify the host is back before running further commands.

8. Use upload_file for config changes — When you need to write or replace a configuration file, prefer upload_file over piping content through execute_ssh_command. It's cleaner and handles encoding correctly.