ssh MCP server
Commit Nov 7, 2026Provides coding agents with secure, high-performance access to SSH hosts for command execution, file transfers, and port forwarding.
Also known as buerka/ssh-mcp
- Stars
- 2
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 7, 2026
- License
- MIT
What is ssh MCP?
ssh provides coding agents with secure, high-performance access to SSH hosts for command execution, file transfers, and port forwarding. It exposes 5 tools, such as ssh_hosts, ssh_exec, ssh_output.
Summary generated from the project's README
About ssh MCP server
Coding agents like Claude Code, Cursor, and ZCode can manage remote servers through this lightweight Go-based MCP server. It provides a secure way for AI models to interact with SSH hosts by reusing your existing ~/.ssh/config and ~/.ssh/known_hosts settings. The server operates via stdio and does not open its own network ports, ensuring that the security boundary remains tied to your specific SSH account permissions.
To keep context windows clean, the server returns plain text responses instead of JSON and caps output at 8 KB. If a command produces large amounts of data, it preserves the head and tail while providing an ssh_output id so the agent can page through the middle only when necessary. It includes specialized tools for executing shell commands with ssh_exec, managing files via ssh_get and ssh_put, listing directories with ssh_ls, and handling local port forwarding through ssh_forward.
Security is prioritized through a redaction filter that scrubs private key material from all tool responses. While it prefers SSH keys and agents, it also supports optional password authentication stored in a protected local file. The server implements a backoff strategy for connection failures to prevent triggering SSH handshake lockouts.
What you can do with it
- 1Execute remote shell commandsAn AI agent can run system commands on a remote host and receive truncated, redacted output.
- 2Manage remote files via SFTPDevelopers can instruct an agent to upload or download specific files from a remote server.
- 3Navigate remote directory structuresAn agent can explore the file system of a remote machine to locate specific configuration files.
- 4Handle large command outputsWhen a command produces too much data, the agent can use a specific ID to fetch missing segments.
- 5Set up local port forwardingAn agent can establish a tunnel to access a remote service locally.
Written from the project's README. Every use case is checked against a quote from it.
ssh MCP tools 5
Detected from the READMEssh_hostsssh_execssh_outputssh_lsssh_forward
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablebuerka/ssh-mcp is public and reachablegithub.com/buerka/ssh-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/buerka/ssh-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubssh-mcp
A lightweight, high-performance MCP (Model Context Protocol) server that gives coding agents — ZCode, Codex, Claude Code, Cursor, … — secure access to your SSH hosts. Written in Go, shipped as a single static binary.
轻量、高性能的 MCP(Model Context Protocol)服务器,让 ZCode、Codex、Claude Code、Cursor 等编码 agent 安全地操作你的 SSH 主机。Go 编写,单个静态二进制。
Design goals 设计目标
- Small context footprint. Every tool response is plain text (never JSON)
and capped at 8 KB by default: head + tail preserved, middle elided with an
ssh_outputid so the model can page through the full output only when it actually needs to. Tool descriptions are one-liners. 省模型上下文。 工具响应一律纯文本(不用 JSON),默认截断到 8 KB:保留 头尾、中间省略并附带ssh_outputid,模型真正需要时才按需分页取回。工具 描述每条只有一句话。 - Loose permissions. No command allowlists, no confirmation prompts. The security boundary is the SSH account itself — the agent runs commands as your configured remote user, exactly like you would. 权限松散。 不做命令白名单、不加确认环节。安全边界就是 SSH 账号本身: agent 以你配置的远程用户身份执行命令,和你本人登录没有区别。
- Zero credential leakage. No new credential store. Connections reuse
~/.ssh/config,~/.ssh/known_hostsand your keys/agent. Host key verification is strict by default (relax with--insecure). Every tool response passes a redaction filter that scrubs private key material, and the server logs nothing by default. 凭据零暴露。 不引入任何新凭据存储。连接复用~/.ssh/config、~/.ssh/known_hosts与你的密钥/agent。主机密钥默认严格校验(可用--insecure放宽)。所有响应经过私钥脱敏过滤器,默认零日志。 - Fast. One persistent connection per host with keepalive, reused across tool calls and shared by exec/SFTP/forwarding; dial timeout 10 s, exec timeout 60 s (both overridable per call). 高性能。 每主机一条持久连接(带 keepalive),跨工具调用复用,exec/SFTP/ 转发共享;连接超时 10 秒、命令超时 60 秒,均可按调用覆盖。
Tools 工具
| Tool 工具 | Purpose 用途 |
|---|---|
ssh_hosts |
list host aliases from ~/.ssh/config(仅列主机别名,不含凭据) |
ssh_exec |
run a shell command; returns exit:N + redacted, truncated output(执行命令,返回退出码 + 脱敏截断输出) |
ssh_output |
page through a previously truncated output by id(按 id 分页取回被截断的输出) |
ssh_ls |
list a remote directory over SFTP(列远程目录) |
ssh_get / ssh_put |
download / upload a file over SFTP(下载 / 上传文件) |
ssh_forward |
start/stop a local port forward through an SSH host(建立/停止本地端口转发) |
Build 构建
go build -o ssh-mcp .
Requires Go 1.25+.(需要 Go 1.25 或更高版本。)
Wire it up 接入
ZCode (.zcode/mcp.json or user config / 用户级或项目级配置):
{
"mcpServers": {
"ssh": {
"command": "/path/to/ssh-mcp"
}
}
}
Codex (~/.codex/config.toml):
[mcp_servers.ssh]
command = "/path/to/ssh-mcp"
Claude Code:
claude mcp add ssh -- /path/to/ssh-mcp
Password auth (optional) 密码登录(可选)
Keys are preferred, but if a host only supports passwords, store one in a
0600 file next to your SSH config. The server adds ssh.Password auth on
top of keys/agent when a password is found — keys are still tried first.
优先用密钥,但若某台主机只支持密码,可把密码存进 SSH 配置旁的 0600 文件。
找到密码时服务器会在密钥/agent 之上追加 ssh.Password 认证——密钥仍然先试。
ssh-mcp password set web1 # hidden prompt; saved to ~/.ssh/ssh-mcp.json (0600) 隐藏输入,存入 0600 文件
ssh-mcp password del web1 # remove 删除
ssh-mcp password list # host names only, never passwords 只列主机名,绝不显示密码
- Passwords never appear in tool output, logs or errors; the file is rejected
as unsafe if its permissions are looser than
0600. 密码绝不出现在工具输出、日志或错误信息里;文件权限一旦宽于0600会拒绝 读取并提示修复。 - Connection order: ssh-agent → identity files → password (when stored). 认证顺序:ssh-agent → 密钥文件 → 密码(已存储时)。
Flags and environment 参数与环境变量
| Flag / env | Meaning 含义 |
|---|---|
--insecure |
skip known_hosts host key verification (dev only)(跳过主机密钥校验,仅限开发) |
--verbose |
log connection diagnostics to stderr: resolved settings and key fingerprints(向 stderr 输出连接诊断:解析结果与密钥指纹) |
SSH_MCP_MAX_OUTPUT |
response cap in bytes, default 8192(单次响应字节数上限,默认 8192) |
Diagnostics and backoff 诊断与退避
Connect failures are self-explaining: the error carries the resolved
user@host:port, every candidate credential with its SHA256 fingerprint (or
why it was skipped), and a password hint. Use --verbose for the same on
stderr per attempt.
连接失败自带诊断:错误信息包含解析出的 user@host:port、每个候选凭据的
SHA256 指纹(或被跳过的原因)以及密码提示;--verbose 还会把每次尝试写到
stderr。
After a failed connect, retries back off 5s → 15s → 45s per host (reset on
success). This protects against sshd PerSourcePenalties, where rapid
retries escalate short auth failures into minutes-long handshake lockouts
that look like "algorithm incompatibility".
连接失败后按主机退避 5s → 15s → 45s(成功即重置),防止 sshd 的
PerSourcePenalties 把短暂的认证失败滚成几分钟的握手封锁——那正是"算法不
兼容"错觉的常见来源。
Example session 使用示例
> ssh_hosts
web1
db1
> ssh_exec {host: web1, command: "uname -a"}
exit:0
Linux web1 6.8.0 ... x86_64 GNU/Linux
> ssh_exec {host: web1, command: "cat huge.log"}
exit:0
<head 5KB>
...[61440 bytes omitted; fetch with ssh_output id=out-3 offset=5461]...
<tail 2.5KB>
Security notes 安全说明
- Credentials never appear in tool output; private key blocks are redacted from every response as a backstop. 凭据绝不出现在工具输出里;每个响应都会经过私钥块脱敏兜底过滤。
- Host key checking uses
~/.ssh/known_hosts; first connections to new hosts must be made once by hand (or accept--insecureknowingly). 主机密钥校验基于~/.ssh/known_hosts;新主机首次需手动连接一次(或明确 接受--insecure)。 - Password auth is optional and off by default; keys and ssh-agent come
first. Stored passwords live in
~/.ssh/ssh-mcp.jsonwith mode0600. 密码登录默认关闭、完全可选,密钥与 ssh-agent 永远优先。已存密码放在~/.ssh/ssh-mcp.json,权限0600。 - The server is stdio-only: it never opens a network port of its own, and
created port forwards bind to
127.0.0.1only. 服务器只走 stdio,自身不监听任何网络端口;端口转发仅绑定127.0.0.1。
License
MIT
ssh MCP questions
What tools does ssh MCP provide?
It exposes 5 tools, including ssh_hosts, ssh_exec, ssh_output, ssh_ls, ssh_forward.
How does the server handle large command outputs?
Outputs are capped at 8 KB by default, preserving the head and tail while eliding the middle with an ID that allows the model to page through the full content if needed.
Does the server store my SSH credentials?
No, it reuses your existing ~/.ssh/config, ~/.ssh/known_hosts, and keys or agent. It does not introduce a new credential store.
Can I use password authentication instead of keys?
Yes, if a host only supports passwords, you can store one in a 0600 permission file next to your SSH config.
Is the server secure against credential leakage?
Yes, it uses a redaction filter to scrub private key material from all tool responses and does not log anything by default.