Skip to main content
Glama

SSH MCP Server

English | 简体中文

CI Python 3.11+ MCP

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 Host aliases 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_hosts by 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 scp command; 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.1 and 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

  • uv

  • An OpenSSH config file and a verified known_hosts file

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-server

Configure 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 22

192.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-server

Alternatively, 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_list_servers, ssh_search_servers, ssh_check, ssh_execute, ssh_execute_batch

SSH configuration

ssh_config_create, ssh_config_update, ssh_config_delete

File transfer

ssh_upload, ssh_download, ssh_transfer_between_servers

Background jobs

ssh_start_job, ssh_job_status, ssh_job_list, ssh_cancel_job, ssh_job_cleanup

Download monitoring

ssh_file_progress

Host monitoring

ssh_gpu_status, ssh_system_status

systemd and journal

ssh_service_status, ssh_service_control, ssh_read_journal

Tunnels

ssh_tunnel_start, ssh_tunnel_list, ssh_tunnel_status, ssh_tunnel_stop, ssh_tunnel_stop_all, ssh_tunnel_restart

See the tool reference for parameters, safety properties, and usage guidance.

Optional Environment Variables

Variable

Purpose

SSH_MCP_CONFIG

Use a custom OpenSSH config path

SSH_MCP_KNOWN_HOSTS

Use a custom known_hosts path

SSH_MCP_ALLOW_UNKNOWN_HOSTS=1

Temporarily allow unknown hosts; not recommended

SSH_MCP_PASSWORD_<ALIAS>

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 -q

The 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 scp or rsync; 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 tools
ssh_cancel_job停止远程后台任务A
Destructive

终止后台任务;超过等待时间后强制结束。

Inputs: alias (required), job_id (required), force_after_seconds. Returns: object

ssh_check检查 SSH 服务器B
Read-onlyIdempotent

连接服务器并返回用户、主机名和系统内核信息。

Inputs: alias (required). Returns: object

ssh_download下载文件A
Destructive

通过 SFTP 下载文件;本地目标已存在时可能被覆盖。

Inputs: alias (required), local_path (required), remote_path (required), preserve, +1 more. Returns: object

ssh_execute执行 SSH 命令A
Destructive

执行任意远程命令;命令可能改变服务器状态,调用前必须确认意图。

Inputs: alias (required), command (required), timeout_seconds. Returns: object

ssh_file_progress检查远程文件下载速度B
Read-onlyIdempotent

采样远程文件大小;至少调用两次才能计算增长速度。

Inputs: alias (required), remote_path (required), expected_bytes. Returns: object

ssh_gpu_status查询 GPU 状态A
Read-onlyIdempotent

结构化返回 NVIDIA GPU 显存、利用率、温度和功耗。

Inputs: alias (required). Returns: object

ssh_job_cleanup清理远程后台任务A
Destructive

删除已完成任务的脚本、日志和状态文件。

Inputs: alias (required), job_id (required). Returns: object

ssh_job_list列出远程后台任务C
Read-onlyIdempotent

列出远程任务目录中的任务及状态摘要。

Inputs: alias (required), limit. Returns: object

ssh_job_status查询远程后台任务A
Read-onlyIdempotent

查询后台任务状态、进程组、退出码和受限的末尾日志。

Inputs: alias (required), job_id (required), tail_lines, max_log_bytes. Returns: object

ssh_list_servers列出 SSH 服务器A
Read-onlyIdempotent

列出 ~/.ssh/config 中可供 MCP 使用的显式 Host 别名。

Inputs: no named parameters. Returns: object

ssh_read_journal读取 systemd 日志B
Read-onlyIdempotent

读取指定 systemd 服务的 journal 日志。

Inputs: alias (required), service (required), lines, since. Returns: object

ssh_service_control控制 systemd 服务B
Destructive

启动、停止、重启或重载 systemd 服务。

Inputs: alias (required), action (required), service (required). Returns: object

ssh_service_status查询 systemd 服务C
Read-onlyIdempotent

读取 systemd 服务状态。

Inputs: alias (required), service (required). Returns: object

ssh_start_job启动远程后台任务C
Destructive

启动可持续运行的远程任务,适用于模型下载和推理。

Inputs: alias (required), command (required), label. Returns: object

ssh_system_status查询系统状态B
Read-onlyIdempotent

返回服务器负载、内存和磁盘概况。

Inputs: alias (required). Returns: object

ssh_tunnel_list列出 SSH 隧道A
Read-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上传文件B
Destructive

通过 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

    B3.4/5.0

    Scored across 19 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that converts SSH operations on training servers into AI-callable tools for GPU monitoring, job submission, file transfer, and more.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      SSH-based MCP server that enables remote execution of SSH commands, file transfers, and secure server management via the MCP protocol.
      ISC
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables secure remote management of the platform through nine MCP tools over STDIO and HTTP, including terminal execution, service controls, and live status monitoring.
      -