Skip to main content
Glama
SSH Session MCP

SSH Session MCP

README.md
# SSH Session MCP

[繁體中文](README.zh-TW.md) · [Codex setup](docs/codex.md) · [Protocol](docs/protocol.md) · [Changelog](CHANGELOG.md)

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.

```powershell
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 .
```

```sh
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.

## 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:

```powershell
$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:

```sh
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.

```toml
[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:

```powershell
.\.venv\Scripts\python.exe -m ssh_session_mcp --config C:/private/ssh-session/targets.toml --check-config
```

```sh
.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:

```toml
[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](docs/codex.md).

## 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](docs/protocol.md).

## 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](docs/server-two-factor-authentication.md).

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](https://github.com/ccccchhhheeenng/ssh-session-mcp/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](LICENSE).