Skip to main content
Glama
SSH Session MCP

SSH Session MCP

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.toml

Place 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 = true

On 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-config

Register 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 = 360

On 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

  1. Call ssh_targets to review configured target names, then ssh_connect with the selected name.

  2. Poll ssh_status while connecting. Submit only the current server challenge through ssh_authenticate; every challenge round requires its own response.

  3. Once the session is ready, reuse its session_id for ssh_execute, ssh_job_status, ssh_cancel_job, ssh_read_file, and ssh_write_file.

  4. Call ssh_disconnect when 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      1,041
      ISC
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables SSH interactive session management through MCP, supporting commands, menus, and session lifecycle operations.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides MCP clients with a persistent SSH shell on legacy Unix hosts, including session management, SFTP file transfer, and ClearCase workflow helpers.
      19,226 npm
      MIT