SSH MCP Server
English | 简体中文
A structured SSH management service for Codex and other MCP clients. It exposes commandexecution, file transfer, background jobs, GPU monitoring, systemd operations, and portforwarding as MCP tools with explicit input schemas, structured outputs, and accurate safetyannotations.
Features
- Connects only to explicit
Hostaliases declared in~/.ssh/config. - 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. - 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
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-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 thehost 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 isuppercased. For example, gpu-01 maps to SSH_MCP_PASSWORD_GPU_01. Prefer key authenticationand 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 addedincrementally 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, connectionbehavior, background job lifecycle, and a real MCP stdio initialization handshake. Linux CI alsoexecutes the real process-group lifecycle test.
Current Limitations
- Remote shell and systemd workflows target Unix-like hosts, with full background-job supportrequiring 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 becausethey 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 notgrant permission to copy, modify, or distribute the code; contact the maintainer before reuse.
