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 Host aliases declared in ~/.ssh/config.
• 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.
• 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 the local loopback address, 127.0.0.1.
• Applies MCP safety annotations to arbitrary commands, file overwrites, and service control.

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_check, ssh_execute
File transfer	ssh_upload, ssh_download
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_stop

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

• Architecture
• Tool reference
• Troubleshooting
• Contributing
• Security policy
• Changelog

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 transfers do not yet support resume or progress events.
• 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.
• Direct server-to-server transfer and batch cluster execution are not implemented.

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.