SSH Session MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
SSH Session MCP
繁體中文 · Codex setup · Protocol · Changelog
SSH Session MCP is a local, stdio-only Model Context Protocol (MCP) server for an explicitly configured set of SSH targets. It lets an MCP client establish an interactive-authenticated SSH session, run commands as background jobs, inspect or cancel those jobs, and transfer bounded UTF-8 text files over SFTP. It does not open an HTTP listener.
Install
Requirements: Python 3.10 or newer and Git. Clone the public repository, then create a virtual environment and install the package. Use the virtual environment's Python executable directly; activation is not required.
git clone https://github.com/ccccchhhheeenng/ssh-session-mcp.git
cd ssh-session-mcp
py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .git clone https://github.com/ccccchhhheeenng/ssh-session-mcp.git
cd ssh-session-mcp
python3.10 -m venv .venv
.venv/bin/python -m pip install .Keep the repository and virtual environment local to each computer. Do not put credentials or private target configuration in the repository. Create a new private credential directory for these files; do not apply the permission commands below to an existing or shared directory.
Related MCP server: ssh-mcp
Prepare SSH credentials and host verification
Version 0.1 requires a private key readable without a passphrase. Create or provision a dedicated SSH key using your organization's approved process. Copy its public key to the intended account on the SSH server. The private key stays on the client computer. Protect it with Windows file ACLs so only your account and required system principals can read it. On Linux/macOS, set the key file to owner-only access, for example chmod 600 /absolute/path/id_ed25519.
For a new, dedicated Windows directory, create it and restrict inherited access to your current account, SYSTEM, and Administrators. Files created inside inherit these permissions:
$ErrorActionPreference = 'Stop'
if (!(Test-Path C:\private)) { New-Item -ItemType Directory -Path C:\private | Out-Null }
if (Test-Path C:\private\ssh-session) { throw 'Directory already exists; choose a new private directory.' }
New-Item -ItemType Directory -Path C:\private\ssh-session
$keyOwner = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
icacls C:\private\ssh-session /inheritance:r /grant:r "${keyOwner}:(OI)(CI)F" "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-544:(OI)(CI)F"For a new POSIX directory, create it with owner-only access, then restrict each credential/configuration file:
if [ -e /absolute/path/ssh-session ]; then echo 'Directory already exists; choose a new private directory.' >&2; exit 1; fi
mkdir -m 700 -p /absolute/path/ssh-session
chmod 600 /absolute/path/ssh-session/id_ed25519 /absolute/path/ssh-session/known_hosts /absolute/path/ssh-session/targets.tomlPlace the files at the matching paths or adjust the commands before running them. These commands are examples for a newly created, dedicated directory. Do not replace existing credentials or run the ACL/permission changes on an existing or shared directory.
Obtain the server host key fingerprint through a trusted, independent channel and verify it with the server administrator before adding it to known_hosts. Do not trust an unverified ssh-keyscan result. For a nonstandard SSH port, the known-hosts entry uses bracket notation, such as [server.example.invalid]:22222; verify that exact host-and-port identity out of band. Set restrictive permissions on the known-hosts file as well.
Configure targets and policy
Store targets.toml in a private directory outside the cloned repository. Replace the sample username and local paths. The example uses the reserved .invalid domain and cannot identify a real host.
[policy]
idle_timeout_seconds = 900
max_session_seconds = 7200
auth_timeout_seconds = 180
command_timeout_seconds = 300
max_output_bytes = 262144
max_sessions = 4
max_jobs_per_session = 8
max_file_bytes = 1048576
[targets.example]
host = "server.example.invalid"
port = 22222
username = "operator"
private_key = "C:/private/ssh-session/id_ed25519"
known_hosts = "C:/private/ssh-session/known_hosts"
require_interactive_auth = trueOn Linux/macOS, use absolute POSIX paths, for example /absolute/path/id_ed25519 and /absolute/path/known_hosts. Configuration-relative paths resolve from the directory containing targets.toml; absolute paths make this setup easier to review. Protect the TOML file because it identifies the allowed targets and local credential paths. It must not contain passwords, OTP seeds, or OTP codes.
Check syntax and policy locally without opening a network connection. Use the absolute path to the configuration file:
.\.venv\Scripts\python.exe -m ssh_session_mcp --config C:/private/ssh-session/targets.toml --check-config.venv/bin/python -m ssh_session_mcp --config /absolute/path/targets.toml --check-configRegister with Codex
Append this MCP table to the global ~/.codex/config.toml, keeping all existing settings. If the table already exists, edit it instead of adding a duplicate. Replace the paths with absolute paths for this computer:
[mcp_servers.ssh_session]
command = "C:/path/to/ssh-session-mcp/.venv/Scripts/python.exe"
args = ["-m", "ssh_session_mcp", "--config", "C:/private/ssh-session/targets.toml"]
startup_timeout_sec = 20
tool_timeout_sec = 360On Linux/macOS use the venv's /absolute/path/to/ssh-session-mcp/.venv/bin/python. The default policy disconnects after 15 minutes idle or two hours maximum session time. The absolute Python path avoids dependence on shell activation or PATH. Reload the Codex client and confirm ssh_targets lists only the intended targets before connecting. For another stdio MCP client, use its documented server format. See Codex setup details.
Typical session
Call
ssh_targetsto review configured target names, thenssh_connectwith the selected name.Poll
ssh_statuswhile connecting. Submit only the current server challenge throughssh_authenticate; every challenge round requires its own response.Once the session is
ready, reuse itssession_idforssh_execute,ssh_job_status,ssh_cancel_job,ssh_read_file, andssh_write_file.Call
ssh_disconnectwhen finished. A dropped, expired, or restarted session requires a new login.
Each command runs in a separate remote shell, so its working directory and shell variables do not persist. Commands return a job ID; poll the job to collect output. SFTP transfers UTF-8 text only and are bounded by max_file_bytes. File writes are non-atomic and do not overwrite existing files unless overwrite=true is set. Job cancellation or disconnect does not guarantee that a remote process has stopped. The hard session lifetime can close the transport and interrupt running work.
See all tool parameters and protocol behavior.
Authentication limits
require_interactive_auth = true rejects a login if the SSH server presents no interactive authentication challenge. It does not prove that the challenge is a second factor or that the server enforces MFA. A keyboard-interactive prompt alone is not proof of MFA. Configure and verify server-side authentication separately; see server-side OpenSSH and PAM authentication.
Interactive responses pass through MCP tool arguments and may be retained in client conversation history or logs. Never provide TOTP seeds, provisioning QR codes, or recovery codes. This version supports unencrypted private keys only; SSH agent support and encrypted-key unlocking are not implemented. Authenticated commands have the remote account's permissions. Use a dedicated least-privilege account and review commands before execution.
For multiple client computers, either provision a distinct key for each computer and authorize those public keys on the server, or deliberately share the same private key through an approved secure credential-distribution method. Do not copy a private key through chat, source control, or an unprotected shared folder. Server firewall or SSH source-address rules must allow each computer's actual public egress address; those addresses may differ across networks and may change. Coordinate address changes with the server administrator.
Verification status
Verified on 2026-11-05: a real Windows Python 3.10 MCP client connected to Ubuntu 24.04 ARM64 with OpenSSH 9.6 and PAM TOTP for public-key plus keyboard-interactive login. Negative key-only and incorrect-OTP checks, sudo, session reuse, and SFTP were verified. This records one deployment environment. Cross-platform test/build results for Windows, Linux, and macOS are published in GitHub Actions; those temporary-server tests do not validate every production SSH/PAM stack. The official MCP client end-to-end integration was validated; registration and operation inside the Codex product have not been validated.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
SSH client, server management and one remote MCP URL for your machines, with human approvals.
1An authenticated remote MCP server for user-owned devices and one-shot capability invocation.
Termalin's hosted MCP server. Claude, ChatGPT or any MCP client runs commands, moves files over SFTP, queries databases and reads server metrics and monitoring alerts on your servers, keylessly through Termalin Connectors: no SSH key is handed over and no inbound port is opened. Per-host command policy and an audit log. Needs a termal.in Pro or Team account (new accounts start with a 14-day Pro trial).
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables secure remote command execution and bidirectional file transfers on SSH servers through the Model Context Protocol. It features robust security controls including command whitelisting, credential isolation, and support for multiple SSH connection profiles.2,863 npm1,041ISC
- FlicenseNot gradedqualityDmaintenanceEnables SSH interactive session management through MCP, supporting commands, menus, and session lifecycle operations.1-
- AlicenseNot gradedqualityCmaintenanceEnables remote server management via SSH, including executing commands, managing persistent interactive sessions, and transferring files over SFTP.93 npmISC
- AlicenseNot gradedqualityCmaintenanceProvides MCP clients with a persistent SSH shell on legacy Unix hosts, including session management, SFTP file transfer, and ClearCase workflow helpers.19,226 npmMIT