ssh-mcp-server
This server exposes SSH management as MCP tools for secure remote host control.
List and search SSH hosts defined in
~/.ssh/config.Execute single or batch remote commands with timeouts and per-host failure isolation.
Create, update, and delete OpenSSH config blocks safely.
Upload and download files/directories over SFTP with resume and overwrite controls.
Stream files between two remote servers without exposing credentials.
Start background jobs, query status, cancel them, and clean up logs.
Monitor remote file download progress and estimate completion.
Check NVIDIA GPU metrics and system resource usage.
Inspect systemd services, control them, and read journal logs.
Start, list, stop, and restart SSH tunnels bound only to 127.0.0.1.
Provides tools for monitoring NVIDIA GPU metrics and status on remote hosts via SSH.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ssh-mcp-server run nvidia-smi on gpu-01"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SSH MCP Server
English | 简体中文
A structured SSH management service for Codex and other MCP clients. It exposes command execution, file transfer, background jobs, GPU monitoring, systemd operations, and port forwarding as MCP tools with explicit input schemas, structured outputs, and accurate safety annotations.
Features
Connects only to explicit
Hostaliases declared in~/.ssh/config.Searches hosts by keyword, alias, environment, and tags, then runs bounded batch commands with per-host failure isolation.
Strictly verifies
known_hostsby default and rejects unknown or changed host keys.Reuses AsyncSSH connections and rebuilds stale connections automatically.
Transfers files and directories over SFTP without invoking an external
scpcommand; single files support bounded-memory resume, overwrite control, and final progress statistics.Streams files between two SSH servers through bounded local memory without exposing credentials to either remote host.
Safely previews, creates, updates, and deletes single-alias OpenSSH blocks with backups and atomic replacement.
Runs background jobs in isolated process groups with persistent identity, logs, exit status, status discovery, safe cancellation, and cleanup.
Calculates remote file growth rate, progress, and estimated completion time.
Reports NVIDIA GPU metrics, system resources, systemd service state, and journal logs.
Binds SSH tunnels only to
127.0.0.1and exposes status, explicit restart, and per-host stop-all.Applies MCP safety annotations to arbitrary commands, file overwrites, and service control.
Related MCP server: ssh-mcp-server
Quick Start
Requirements
Python 3.11 or later
An OpenSSH
configfile and a verifiedknown_hostsfile
Install and Run
git clone https://github.com/yuyi-clip/ssh-mcp-server.git
Set-Location ssh-mcp-server
uv sync --locked
uv run ssh-mcp-serverConfigure an SSH Host
The server accepts explicit aliases, not arbitrary IP addresses or hostnames:
# description: GPU inference server
# environment: development
# tags: gpu,video
Host gpu-01
HostName 192.0.2.10
User operator
IdentityFile ~/.ssh/id_ed25519
Port 22192.0.2.10 is a documentation-only address. Replace it with your server address, verify the
host fingerprint through a trusted channel, and add it to ~/.ssh/known_hosts before connecting.
Connect from Codex
Register the stdio MCP server with the Codex CLI:
codex mcp add ssh -- uv --directory "D:\path\to\ssh-mcp-server" run ssh-mcp-serverAlternatively, add it to ~/.codex/config.toml manually:
[mcp_servers.ssh]
command = "uv"
args = [
"--directory",
"D:\\path\\to\\ssh-mcp-server",
"run",
"ssh-mcp-server",
]
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "writes"Restart Codex after editing the configuration and use /mcp to verify the server status.
Tool Overview
Category | Tools |
Hosts and commands |
|
SSH configuration |
|
File transfer |
|
Background jobs |
|
Download monitoring |
|
Host monitoring |
|
systemd and journal |
|
Tunnels |
|
See the tool reference for parameters, safety properties, and usage guidance.
Optional Environment Variables
Variable | Purpose |
| Use a custom OpenSSH config path |
| Use a custom |
| Temporarily allow unknown hosts; not recommended |
| Supply a temporary password for one alias |
Non-alphanumeric characters in an alias are converted to underscores and the result is
uppercased. For example, gpu-01 maps to SSH_MCP_PASSWORD_GPU_01. Prefer key authentication
and avoid long-lived password environment variables.
Documentation
The detailed documents are currently maintained in Chinese. English documentation can be added incrementally without changing the tool interfaces described here.
Development and Verification
uv sync --locked
uv run ruff format --check .
uv run ruff check .
uv run pytest -qThe test suite covers configuration parsing, input validation, tool registration, connection behavior, background job lifecycle, and a real MCP stdio initialization handshake. Linux CI also executes the real process-group lifecycle test.
Current Limitations
Remote shell and systemd workflows target Unix-like hosts, with full background-job support requiring Linux.
SFTP tools return final progress statistics but do not emit live MCP progress events.
Server-to-server transfer uses bounded local-memory streaming, not direct remote
scporrsync; throughput therefore depends on the MCP host's network path.Background jobs require Linux
/proc,sh,setsid,nohup,tail, and common Coreutils.Jobs created by older versions can still be inspected, but cannot be safely cancelled because they lack process identity files.
Tunnel state exists only in the current MCP process and is closed when the process exits; failed tunnels require an explicit restart.
OpenSSH configuration backups are intentionally retained beside the config file and must be managed like other sensitive SSH configuration artifacts.
License
This repository does not currently declare an open-source license. Public visibility does not grant permission to copy, modify, or distribute the code; contact the maintainer before reuse.
Available Tools
19 toolsssh_cancel_job停止远程后台任务ADestructive
终止后台任务;超过等待时间后强制结束。
Inputs: alias (required), job_id (required), force_after_seconds. Returns: object
ssh_check检查 SSH 服务器BRead-onlyIdempotent
连接服务器并返回用户、主机名和系统内核信息。
Inputs: alias (required). Returns: object
ssh_download下载文件ADestructive
通过 SFTP 下载文件;本地目标已存在时可能被覆盖。
Inputs: alias (required), local_path (required), remote_path (required), preserve, +1 more. Returns: object
ssh_execute执行 SSH 命令ADestructive
执行任意远程命令;命令可能改变服务器状态,调用前必须确认意图。
Inputs: alias (required), command (required), timeout_seconds. Returns: object
ssh_file_progress检查远程文件下载速度BRead-onlyIdempotent
采样远程文件大小;至少调用两次才能计算增长速度。
Inputs: alias (required), remote_path (required), expected_bytes. Returns: object
ssh_gpu_status查询 GPU 状态ARead-onlyIdempotent
结构化返回 NVIDIA GPU 显存、利用率、温度和功耗。
Inputs: alias (required). Returns: object
ssh_job_cleanup清理远程后台任务ADestructive
删除已完成任务的脚本、日志和状态文件。
Inputs: alias (required), job_id (required). Returns: object
ssh_job_list列出远程后台任务CRead-onlyIdempotent
列出远程任务目录中的任务及状态摘要。
Inputs: alias (required), limit. Returns: object
ssh_job_status查询远程后台任务ARead-onlyIdempotent
查询后台任务状态、进程组、退出码和受限的末尾日志。
Inputs: alias (required), job_id (required), tail_lines, max_log_bytes. Returns: object
ssh_list_servers列出 SSH 服务器ARead-onlyIdempotent
列出 ~/.ssh/config 中可供 MCP 使用的显式 Host 别名。
Inputs: no named parameters. Returns: object
ssh_read_journal读取 systemd 日志BRead-onlyIdempotent
读取指定 systemd 服务的 journal 日志。
Inputs: alias (required), service (required), lines, since. Returns: object
ssh_service_control控制 systemd 服务BDestructive
启动、停止、重启或重载 systemd 服务。
Inputs: alias (required), action (required), service (required). Returns: object
ssh_service_status查询 systemd 服务CRead-onlyIdempotent
读取 systemd 服务状态。
Inputs: alias (required), service (required). Returns: object
ssh_start_job启动远程后台任务CDestructive
启动可持续运行的远程任务,适用于模型下载和推理。
Inputs: alias (required), command (required), label. Returns: object
ssh_system_status查询系统状态BRead-onlyIdempotent
返回服务器负载、内存和磁盘概况。
Inputs: alias (required). Returns: object
ssh_tunnel_list列出 SSH 隧道ARead-onlyIdempotent
列出当前 MCP 进程创建的活动隧道。
Inputs: no named parameters. Returns: object
ssh_tunnel_start启动 SSH 隧道A
创建仅监听 127.0.0.1 的本地端口转发。
Inputs: alias (required), remote_port (required), local_port, remote_host. Returns: object
ssh_tunnel_stop停止 SSH 隧道B
停止当前 MCP 进程中的指定隧道。
Inputs: tunnel_id (required). Returns: object
ssh_upload上传文件BDestructive
通过 SFTP 上传文件;目标已存在时可能被覆盖。
Inputs: alias (required), local_path (required), remote_path (required), preserve, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools have clearly distinct purposes (execute, upload, service control, tunnel management), but ssh_check and ssh_system_status both report host health, and ssh_job_status versus ssh_job_list overlap in querying jobs. Descriptions help disambiguate, but the boundaries aren't perfectly sharp.
All names use snake_case with a consistent ssh_ prefix and mostly a verb-first pattern (list, execute, start, cancel). However, ssh_service_control and ssh_file_progress deviate from the verb-noun structure, creating minor inconsistency.
19 tools is on the higher end but justified by the broad scope covering execution, file transfer, job lifecycle, services, monitoring, and tunnels. The count feels slightly heavy but each tool serves a distinct area without redundancy.
The toolset provides strong lifecycle coverage for jobs, services, files, and tunnels, plus system and GPU monitoring. Minor gaps like remote directory listing or file deletion are absent but workaroundable, so core workflows are well-supported.
Related MCP Connectors
SSH client, server management and one remote MCP URL for your machines, with human approvals.
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server that converts SSH operations on training servers into AI-callable tools for GPU monitoring, job submission, file transfer, and more.1MIT
- AlicenseNot gradedqualityDmaintenanceSSH-based MCP server that enables remote execution of SSH commands, file transfers, and secure server management via the MCP protocol.ISC
- AlicenseAqualityBmaintenanceEnables AI clients to securely execute remote commands and transfer files over SSH through standardized MCP tools, with multi-host management, flexible authentication, and an admin console.524 npm3ISC
- FlicenseNot gradedqualityBmaintenanceEnables secure remote management of the platform through nine MCP tools over STDIO and HTTP, including terminal execution, service controls, and live status monitoring.-