mcp-ssh-agentic
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-ssh-agentic run 'uptime' on demo@server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-ssh-agentic
An MCP server for agentic SSH/SCP operations with passwordless authentication. It uses the operating system's native ssh and scp binaries, so existing SSH features continue to work seamlessly, including public key authentication, ~/.ssh/config, ssh-agent, ProxyJump, and known_hosts.
Connection Efficiency
On Linux and macOS, each target uses SSH ControlMaster multiplexing:
Socket:
~/.cache/mcp-ssh-agentic/mux/<hash>ControlPersist=600(master connection stays alive for 10 minutes of idle time)Subsequent calls to the same host reuse the existing TCP connection and authentication
Stale sockets are automatically removed and the connection is retried once
ssh_closeexplicitly closes the master connection
Windows (cmd / PowerShell / Git Bash)
Native Win32-OpenSSH does not support ControlMaster (this affects all three common Windows shells — they share the same ssh.exe). Multiplexing is disabled by default on win32; every tool call opens a fresh SSH connection. Behavior is otherwise the same.
Client | Mux default | Notes |
Windows cmd.exe | off | Uses Win32-OpenSSH |
Windows PowerShell / pwsh | off | Same OpenSSH client |
Git Bash | off | Usually the same Win32-OpenSSH on |
WSL (Ubuntu, etc.) | on | Runs as Linux — preferred on Windows for connection reuse |
macOS / Linux | on | Full ControlMaster support |
If a ControlMaster error is still seen (for example after forcing mux on), the server auto-disables multiplexing for the rest of the process and retries without it.
Override with env:
{
"mcpServers": {
"ssh-agentic": {
"command": "npx",
"args": ["-y", "@jahrulnr/mcp-ssh-agentic"],
"env": {
"MCP_SSH_AGENTIC_MUX": "0"
}
}
}
}MCP_SSH_AGENTIC_MUX=0— force off (also:false,no,off)MCP_SSH_AGENTIC_MUX=1— force on (only if yoursshactually supports ControlMaster)
Related MCP server: MCP SSH Tools Server
Running with npx
After a release, the package is on npmjs and GitHub Packages as @jahrulnr/mcp-ssh-agentic.
npmjs (simplest):
{
"mcpServers": {
"ssh-agentic": {
"command": "npx",
"args": ["-y", "@jahrulnr/mcp-ssh-agentic"]
}
}
}GitHub Packages (needs a PAT with read:packages in ~/.npmrc):
@jahrulnr:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT{
"mcpServers": {
"ssh-agentic": {
"command": "npx",
"args": ["-y", "--registry=https://npm.pkg.github.com", "@jahrulnr/mcp-ssh-agentic"]
}
}
}Targets must always be specified as user@host[:port], for example demo@127.0.0.1:22. The port may also be configured through aliases in ~/.ssh/config.
Available Tools
ssh_ping, ssh_read_file, ssh_write_file, ssh_read_image, ssh_list_dir, ssh_mkdir, ssh_grep, ssh_apply_patch, ssh_delete, ssh_exec, ssh_exec_result, ssh_exec_kill, ssh_interactive_exec, ssh_interactive_input, ssh_interactive_close, ssh_interactive_list, ssh_scp_to, ssh_scp_from, ssh_close
Examples:
ssh_read_file("demo@127.0.0.1:22", "/etc/hostname")
ssh_write_file("demo@server", "/srv/app/.env", "PORT=3000\n")
ssh_mkdir("demo@server", "/srv/app/releases/42")
ssh_list_dir("demo@server", "/var/log")
ssh_grep("demo@server", "TODO", "/srv/app", "*.js")
ssh_exec("demo@server", "systemctl --user status my-service")
# Detached / background command:
ssh_exec("demo@server", "./build.sh", background=true)
# -> job_id=abc123
ssh_exec_result(job_id="abc123", wait=true, timeout_ms=60000)
ssh_exec_kill(job_id="abc123", signal="SIGTERM", cleanup=true)
# Commands that may require interactive input (sudo password, y/N prompts, setup wizards):
ssh_interactive_exec("demo@server", "sudo apt-get upgrade")
# -> session_id=abc123, status=running, output contains "[sudo] password for demo:"
ssh_interactive_input(session_id="abc123", input="secret123")
# -> additional output, e.g. "Do you want to continue? [Y/n]"
ssh_interactive_input(session_id="abc123", input="Y")
# -> status=exited (code 0) once the process finishes
ssh_interactive_close("abc123") # close manually if needed
ssh_scp_to("demo@server", "./dist/app.tar.gz", "/apps/app.tar.gz")
ssh_scp_from("demo@server", "/apps/backups/db.sql.gz", "./db.sql.gz")
ssh_close("demo@server")Behavior Notes
ssh_deleteusesrm -ffor files andrm -rfonly whenrecursive=true.ssh_write_filewrites or overwrites a remote file directly from text (without creating a temporary local file). Useappend=trueto append instead of overwrite. Parent directories are created automatically unlesscreate_dirs=false.ssh_mkdiris equivalent tomkdir -pon the remote host, which is especially useful beforessh_scp_to, sincescpdoes not automatically create remote parent directories.ssh_exechas a default timeout of 30 seconds and a maximum output size of 5 MiB.ssh_read_imagesupports files up to 20 MiB.ssh_write_fileaccepts content up to 5 MiB. SCP operations default to a 120-second timeout.ssh_execalso acceptscwd,env,ok_codes, andmax_output_bytes.Set
background=trueonssh_execto run a command detached and get ajob_id. Usessh_exec_resultto poll or wait, andssh_exec_killto stop or clean up the job log directory.All remote commands (not just
ssh_exec) run through a non-login, non-interactive shell (bash --noprofile --norc -c, falling back tosh -c). This avoids failures caused by broken/etc/profile.dscripts on some servers and ensures consistent behavior across all tools.ssh_execalways returnsexit_code=Nalong with stdout. If stderr is present, it is included in a[stderr]section. Non-zero exit codes setisError, but stdout is still returned.Interactive sessions (TTY/PTY):
ssh_interactive_execforces PTY allocation on the remote side (ssh -tt), allowing programs that require a real terminal (sudo,passwd, confirmation prompts, setup wizards, REPLs, etc.) to behave correctly even though the local side uses ordinary pipes. The server waits until output has been quiet forquiet_ms(default: 500 ms) or the process exits, then returns the collected output along with asession_id. Continue the session usingssh_interactive_input(leaveinputempty to simply wait for more output without sending anything). This mechanism is based on output inactivity rather than prompt detection. Commands that continuously produce output (such as long build logs) may cause the tool call to wait longer depending onquiet_msandmaxWaitMs. The server allows up to 8 concurrent interactive sessions, automatically cleans up sessions after 10 minutes of inactivity, and terminates all active sessions when the server exits. Usessh_interactive_listto view active sessions andssh_interactive_closeto close them manually.ssh_greptreats "no matches" as a successful result and still returns partial matches even if some paths cannot be read.ssh_scp_toandssh_scp_fromsupportrecursive=truefor directories. Local parent directories are created automatically when downloading. Remote parent directories must already exist before uploading (usessh_mkdirif needed).The SSH and SCP clients are invoked with
-qto suppress MOTD and other unnecessary output on stderr.
Local Development
npm install
npm run check
npm test
npm startUnit tests use createMockTransport() — the same SSH contract (exec / scp / close / spawnInteractive) executed in a local sandbox, without a real SSH host.
To test the MCP protocol, use MCP Inspector or any MCP client that supports stdio transport.
CI / Release
GitHub Actions (.github/workflows/ci.yml):
Unit test (any branch/PR) — Node 18 / 22 / 24 →
npm run check+npm run test:unitMCP test (after unit) — same Node matrix × (
nodebin |npxfromnpm pack) withMCP_SSH_AGENTIC_MOCK=1Push to
master— after both pass, if tagvX.Y.Zis new: create tag → publish to GitHub Packages + npmjs
Local: npm run test:all
Bump version in package.json before merging to master for a new release. Re-merging the same version skips tag/publish.
Secrets: NPM_TOKEN. GitHub Packages uses GITHUB_TOKEN (packages: write).
Available Tools
19 toolsssh_apply_patchA
Apply a unified diff on the remote host. Tries apply_patch (strip=0 only), then git apply, then patch. Supports dry-run and strip level.
Inputs: patch (required), target (required), strip, dry_run.
ssh_closeA
Close the multiplexed SSH master connection for a target (no-op when multiplexing is disabled, e.g. native Windows OpenSSH).
Inputs: target (required).
ssh_deleteB
Delete a remote file or directory. Directories require recursive=true.
Inputs: path (required), target (required), recursive.
ssh_execA
Execute an intentional shell command on the remote host. Supports stdin, cwd, env, custom output limit, and acceptable exit codes. Set background=true to run a command detached and get a job_id; stdin is not allowed for background jobs. Use ssh_exec_result to poll/wait and ssh_exec_kill to stop or clean up.
Inputs: target (required), command (required), cwd, env, +5 more.
ssh_exec_killA
Send a signal to a background job started with ssh_exec background=true. Optionally remove the job log directory.
Inputs: job_id (required), signal, cleanup.
ssh_exec_resultA
Check the status and output of a background job started with ssh_exec background=true. Optionally wait until it exits.
Inputs: job_id (required), wait, timeout_ms.
ssh_grepB
Search remote text files recursively with ripgrep, falling back to grep. Output format is file:line:match.
Inputs: target (required), pattern (required), glob, path, +5 more.
ssh_interactive_closeA
Kill and remove an interactive SSH session started with ssh_interactive_exec.
Inputs: session_id (required).
ssh_interactive_execA
Start a command on the remote host with a PTY allocated, for programs that prompt for input (sudo asking for a password, y/N confirmations, setup wizards, REPLs). Waits until output goes quiet (likely waiting for input) or the process exits, then returns the output so far plus a session_id. If the command finishes without prompting, the session is closed automatically and there is nothing further to do. Otherwise, use ssh_interactive_input to reply or poll, and ssh_interactive_close when finished. Idle sessions auto-expire after 10 minutes.
Inputs: target (required), command (required), quiet_ms.
ssh_interactive_inputA
Send a line of input to a running ssh_interactive_exec session (e.g. answer a sudo password or y/N prompt), or just poll for more output if input is omitted. Returns newly produced output and status.
Inputs: session_id (required), input, newline, quiet_ms.
ssh_interactive_listB
List currently open interactive SSH sessions.
Inputs: no named parameters.
ssh_list_dirA
List a remote directory with file metadata in ls -lAh style.
Inputs: target (required), path.
ssh_mkdirA
Create a directory (and parents) on the remote host, equivalent to mkdir -p.
Inputs: path (required), target (required).
ssh_pingB
Test passwordless SSH connectivity and return the remote identity.
Inputs: target (required).
ssh_read_fileA
Read a UTF-8 text file from a remote host. offset and limit select a 1-based line range; limit=0 means unlimited. Defaults to first 200 lines.
Inputs: path (required), target (required), limit, offset.
ssh_read_imageC
Read a remote image and return it as an MCP image. Supports common raster formats.
Inputs: path (required), target (required).
ssh_scp_fromB
Download a remote file or directory to the local machine via scp (reuses the multiplexed SSH connection when mux is enabled).
Inputs: target (required), local_path (required), remote_path (required), recursive, +1 more.
ssh_scp_toA
Upload a local file or directory to the remote host via scp (reuses the multiplexed SSH connection when mux is enabled).
Inputs: target (required), local_path (required), remote_path (required), recursive, +1 more.
ssh_write_fileA
Write UTF-8 text content directly to a file on the remote host (creates or overwrites; use append=true to append instead). Avoids the round-trip of writing a local temp file and scp-ing it.
Inputs: path (required), target (required), content (required), append, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
The tools are largely distinct with clear separation between file operations (read/write/delete), directory ops (list/mkdir), execution (exec vs interactive_exec), and transfer (scp_to/scp_from). The only potential overlap is between ssh_ping (connectivity test) and ssh_exec (running commands), but descriptions clarify each purpose. Overall the boundaries are well-drawn.
All tools follow an `ssh_` prefix with clear verb patterns (read_file, write_file, list_dir, mkdir, delete, exec, scp_to, scp_from). The naming is mostly consistent (verb_noun), though a few like exec_result and exec_kill are verb_verb which deviates slightly from the noun pattern.
19 tools is on the higher end but appropriate for a full-featured SSH toolkit covering file operations, execution, interactive sessions, background jobs, and transfer. Each tool serves a distinct purpose; the count is justified by the breadth of the domain, though it's slightly above the comfortable 3-15 sweet spot.
The surface is remarkably complete for SSH operations: file read/write/list/delete/mkdir, grep, patch application, image reading, synchronous and background exec, interactive PTY sessions, scp in both directions, and connection management (ping/close/interactive_list). The lifecycle is well-covered with paired create/close, start/result/kill, and session management operations.
Maintenance
Related MCP Connectors
SSH client, server management and one remote MCP URL for your machines, with human approvals.
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
Related MCP Servers
- FlicenseBqualityDmaintenanceA server that enables remote command execution over SSH through the Model Context Protocol (MCP), supporting both password and private key authentication.12-
- FlicenseAqualityDmaintenanceA server based on the MCP framework that provides remote server management capabilities through SSH, supporting features like connection pooling, file transfers, and remote command execution.7-
- AlicenseAqualityDmaintenanceMCP server for managing remote servers via SSH, enabling command execution, file transfer, rsync, tunnels, health checks, backups, and database operations.171MIT
- AlicenseNot gradedqualityDmaintenanceSSH-based MCP server that enables remote execution of SSH commands, file transfers, and secure server management via the MCP protocol.ISC