표준화된 프로토콜을 통해 AI 어시스턴트가 원격 SSH 명령 실행, 파일 관리 및 백그라운드 작업을 수행할 수 있도록 지원합니다.
다른 이름 classfang/ssh-mcp-server, @fangjunjie/ssh-mcp-server
- 스타
- 1,046
- Tools
- —
- 다운로드, 30일
- 9,039
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 4일
- 라이선스
- ISC
ssh MCP란?
표준화된 프로토콜을 통해 AI 어시스턴트가 원격 SSH 명령 실행, 파일 관리 및 백그라운드 작업을 수행할 수 있도록 지원합니다.
프로젝트 README에서 생성된 요약
ssh MCP server 정보
AI 어시스턴트를 통해 원격 인프라를 관리해야 하는 개발자는 이 도구를 사용하여 LLM과 원격 서버 사이의 간극을 메울 수 있습니다. Model Context Protocol을 통해 AI 클라이언트가 명령을 실행하고, 파일을 관리하며, 장시간 실행되는 백그라운드 작업을 처리할 수 있도록 합니다. SSH 자격 증명을 로컬에서 관리하므로 민감한 로그인 정보가 AI 모델에 노출되지 않도록 보장합니다.
사용자는 비밀번호 인증, 개인 키 또는 암호(passphrase)를 사용하여 서버에 연결할 수 있습니다. 서버는 exec 및 shell을 포함한 여러 전송 모드를 지원하여 직접 호스트 연결 또는 점프 호스트와 호환됩니다. 또한 업로드, 다운로드, read-file, write-file과 같은 파일 작업을 위한 특화된 도구를 제공합니다. 보안을 위해 관리자는 정규 표현식을 사용하는 화이트리스트 및 블랙리스트 메커니즘을 통해 명령 제어를 구현하고 허용되는 작업 범위를 제한할 수 있습니다.
활용 사례
- 1안전한 명령 실행정규 표현식 패턴을 사용하여 AI가 ls 또는 cat과 같은 특정 안전한 명령만 실행하도록 제한합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
ssh MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 ssh MCP 설치
$ claude mcp add ssh-mcp-server -- npx -y @fangjunjie/ssh-mcp-serverCursor에 ssh MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server"
]
}
}
}VS Code에 ssh MCP 설치
.vscode/mcp.json
{
"servers": {
"ssh-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server"
]
}
}
}VS Code CLI에 ssh MCP 설치
$ code --add-mcp '{"name":"ssh-mcp-server","type":"stdio","command":"npx","args":["-y","@fangjunjie/ssh-mcp-server"]}'Claude Desktop에 ssh MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server"
]
}
}
}Codex에 ssh MCP 설치
$ codex mcp add ssh-mcp-server -- npx -y @fangjunjie/ssh-mcp-serverCodex config.toml에 ssh MCP 설치
~/.codex/config.toml
[mcp_servers.ssh-mcp-server] command = "npx" args = ["-y", "@fangjunjie/ssh-mcp-server"]
Gemini CLI에 ssh MCP 설치
$ gemini mcp add -s user ssh-mcp-server npx -- -y @fangjunjie/ssh-mcp-serverGemini settings.json에 ssh MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server"
]
}
}
}시작하려면 키가 필요
2026년 11월 16일에 키 없이 실행하자 멈추고 키를 요구했습니다. 위 변수를 설정하기 전까지 클라이언트에는 도구가 보이지 않습니다.
구성
SSH_MCP_HTTP_TOKEN
| 이름 | 설명 | 유형 |
|---|---|---|
| SSH_MCP_HTTP_TOKEN | — |
자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
README
GitHub에서 보기ssh-mcp-server
基于 SSH 的 MCP (Model Context Protocol) 服务器,允许通过 MCP 协议远程执行 SSH 命令。
English Document | 中文文档
📝 项目介绍
ssh-mcp-server 是一个桥接工具,可以让 AI 助手等支持 MCP 协议的应用通过标准化接口执行远程 SSH 命令。这使得 AI 助手能够安全地操作远程服务器,执行命令并获取结果,而无需直接暴露 SSH 凭据给 AI 模型。
💬 如有任何问题,欢迎加入微信群交流:
✨ 功能亮点
- 🔒 安全连接:支持多种安全的 SSH 连接方式,包括密码认证和私钥认证(支持带密码的私钥)
- 🛡️ 命令安全控制:通过灵活的黑白名单机制,精确控制允许执行的命令范围,防止危险操作
- 🔄 标准化接口:符合 MCP 协议规范,与支持该协议的 AI 助手无缝集成
- 🚇 双传输模式:同时支持
exec和shell两种 transport,兼容直连主机与堡垒机或跳板机场景 - 🌐 HTTP 接入:默认使用 stdio;加上
--mcp-transport http后通过 Streamable HTTP 提供 MCP 端点 - 📂 文件传输:支持双向文件传输功能,可上传本地文件到服务器或从服务器下载文件
- 🔑 凭据隔离:SSH 凭据完全在本地管理,不会暴露给 AI 模型,增强安全性
- 🚀 即用即走:使用 NPX 可直接运行,无需全局安装,方便快捷
📦 开源仓库
GitHub:https://github.com/classfang/ssh-mcp-server
NPM: https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server
🛠️ 工具列表
| 工具 | 名称 | 描述 |
|---|---|---|
| execute-command | 命令执行工具 | 在远程服务器上执行 SSH 命令并获取执行结果 |
| upload | 文件上传工具 | 将本地文件或整个目录上传到远程服务器指定位置 |
| download | 文件下载工具 | 从远程服务器下载文件或整个目录到本地指定位置 |
| read-file | 读文件工具 | 通过 SFTP 读取远程文本文件,可按字节偏移分页,拒绝二进制文件 |
| write-file | 写文件工具 | 通过 SFTP 直接写入文本内容(覆盖或追加),不经过 shell 引号转义 |
| list-servers | 服务器列表工具 | 列出所有可用SSH服务器配置 |
| job-start / job-status / job-kill / job-list | 后台任务工具 | 启动超过命令超时限制的长任务,轮询输出与退出码,终止任务 |
📚 使用方法
0. 🤖 通过 AI Skill 快速配置(推荐)
如果你使用支持 skill 的 AI 编程助手(如 Claude Code),可以直接使用内置的 ssh-mcp-helper skill 通过交互式问答完成安装和配置,无需手动编辑 JSON 文件。
使用方式:
- 从本仓库
skills/目录安装该 skill - 告诉你的 AI 助手:"帮我配置 ssh-mcp-server" 或 "给 Cursor 加一个 SSH MCP 连接"
- skill 会逐步引导你:检查 Node.js 环境 → 选择 MCP 客户端 → 选择认证方式 → 收集连接参数 → 生成并写入配置
该 skill 支持下文所有场景(账号密码、私钥、SSH config 复用、SOCKS 代理、堡垒机、多连接、2FA、命令限制等),并自动生成格式正确的配置。
下面的章节按从简单到复杂的顺序排列,最简单的入门方式就是用账号密码连接服务器。直接复制对应场景下的 mcp.json 配置到你的 MCP 客户端即可使用。
⚠️ 重要提示:在 MCP 配置文件中,每个命令行参数和其值必须是
args数组中的独立元素。不要用空格将它们连接在一起。例如,使用"--host", "192.168.1.1"而不是"--host 192.168.1.1"。
1. 🔑 账号密码(最简单)
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "192.168.1.1",
"--port", "22",
"--username", "root",
"--password", "pwd123456"
]
}
}
}
2. 🔐 账号 + 私钥
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "192.168.1.1",
"--port", "22",
"--username", "root",
"--privateKey", "~/.ssh/id_rsa"
]
}
}
}
3. 🔏 带密码的私钥
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "192.168.1.1",
"--port", "22",
"--username", "root",
"--privateKey", "~/.ssh/id_rsa",
"--passphrase", "pwd123456"
]
}
}
}
4. 📋 复用 ~/.ssh/config
如果你已经在 ~/.ssh/config 配置了主机别名,服务器会自动从中读取连接参数,mcp.json 里就不用再写一遍。
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "myserver"
]
}
}
}
假设你的 ~/.ssh/config 包含:
Host myserver
HostName 192.168.1.1
Port 22
User root
IdentityFile ~/.ssh/id_rsa
你也可以指定自定义的 SSH 配置文件路径:
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "myserver",
"--ssh-config-file", "/path/to/custom/ssh_config"
]
}
}
}
注意:命令行参数优先级高于 SSH 配置值。例如,如果你指定了 --port 2222,它会覆盖 SSH 配置中的端口。
需要一次连接多台已在 SSH config 中配好的主机时,参见下文「10. 多 SSH 连接配置」的方式四。
5. 🌐 通过代理连接
当目标主机只能通过代理访问时,可使用 --proxy 配置 SOCKS5、HTTP 或 HTTPS 代理。
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "192.168.1.1",
"--port", "22",
"--username", "root",
"--password", "pwd123456",
"--proxy", "http://username:password@proxy-host:proxy-port"
]
}
}
}
支持的 URL 格式:
socks://username:password@proxy-host:1080
socks5://username:password@proxy-host:1080
http://username:password@proxy-host:8080
https://username:password@proxy-host:8443
HTTP 和 HTTPS 代理通过 CONNECT 方法建立到 SSH 服务的隧道,用户名和密码使用 Basic 代理认证。HTTP、HTTPS 未填写端口时分别默认使用 80、443;SOCKS5 必须填写端口。HTTPS 代理证书使用 Node.js 默认信任链进行验证。
原有 socksProxy 配置和 --socksProxy 参数继续兼容,但只接受 socks:// 和 socks5://。不要同时配置 proxy 和 socksProxy。
6. 📝 使用命令白名单 / 黑名单
通过 --whitelist 和 --blacklist 限制服务器允许执行的命令范围。多个模式之间用逗号分隔,每个模式都是一个正则表达式。生产环境强烈建议配置。白名单按完整命令匹配;启用白名单时,包含 ;、&、|、反引号、$()、>、< 或换行符的命令会被直接拒绝,不能使用命令连接、管道、重定向或命令替换绕过校验。
白名单示例(仅允许只读型查看命令):
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "192.168.1.1",
"--port", "22",
"--username", "root",
"--password", "pwd123456",
"--whitelist", "^ls(?: [A-Za-z0-9_./-]+)*$,^cat [A-Za-z0-9_./-]+$,^df(?: -[A-Za-z]+)*(?: [A-Za-z0-9_./-]+)?$"
]
}
}
}
黑名单示例(屏蔽危险命令):
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "192.168.1.1",
"--port", "22",
"--username", "root",
"--password", "pwd123456",
"--blacklist", "^\\s*[rR][mM] .*,^\\s*[sS][hH][uU][tT][dD][oO][wW][nN].*,^\\s*[rR][eE][bB][oO][oO][tT].*"
]
}
}
}
注意:黑名单正则默认区分大小写,
^shutdown.*拦不住Shutdown /a。上面的示例使用[sS]等字符组兼容不同 Node.js 版本,无需作用域内联标志(?i:模式)。旧版 Node.js 可能不支持该内联语法,裸(?i)也不受 JavaScript 正则支持;非法正则会让服务器启动失败。JSON 字符串中的反斜杠需要转义:正则的\s在 JSON 中写作\\s,用于容忍命令前的空白。注意:如果同时指定了白名单和黑名单,系统会先检查命令是否完整匹配白名单,再检查是否命中黑名单,命令必须同时通过两项检查才能被执行。建议在白名单正则中始终显式使用
^和$,便于阅读和审计。需要组合执行多个操作时,请将逻辑放入经过单独审查的脚本,并只允许固定的脚本调用;不要依赖字符串切割来解析 Shell 语法。
7. 🧩 使用命令模板包裹命令
commandTemplate 会把每条执行的命令套进一个模板里,适合切换用户(su)、放进容器、或经过跳板机的场景。当命令会作为 shell 参数传入时使用 <quotedCommand>,需要原样插入时使用 <command>;模板会在目录 cd 拼接之后应用,因此整个 cd ... && <实际命令> 都会被包裹起来。
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "10.0.0.1",
"--port", "22",
"--username", "deploy",
"--password", "xxx",
"--command-template", "su root -c <quotedCommand>"
]
}
}
}
当指定目录为 /data 执行 ls /app 时,实际发送的命令是:
su root -c 'cd -- '\''/data'\'' && ls /app'
其他常见模板:
sudo bash -c <quotedCommand>
docker exec -i mycontainer sh -c <quotedCommand>
ssh jumphost <quotedCommand>
8. 🚇 堡垒机 / 跳板机(transportMode: shell)
transportMode 默认是 exec。出现下面这些情况时,应该切换到 shell:
- SSH 登录成功,但
exec执行命令失败 - 远端必须等登录 banner、profile、环境初始化完成后才能正常执行命令
- 连接目标本质上是堡垒机或只暴露交互式 shell 的设备
两者差异:
exec:支持execute-command、upload、downloadshell:命令通过持久 shell 会话串行执行,内部带命令队列;但不支持upload/download,因为该模式下禁用了 SFTP
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "bastion.example.com",
"--port", "22",
"--username", "ops",
"--password", "pwd123456",
"--transport-mode", "shell",
"--shell-ready-timeout", "15000"
]
}
}
}
JSON 配置文件中还可以通过 shellCommandTimeoutMs 覆盖 shell 模式下单条命令的默认超时。
9. 🔐 多因素认证(2FA / MFA)
当 SSH 服务器要求多因素认证(密码 + 私钥 + 2FA 验证码)时启用 tryKeyboard。密码和私钥会自动提供;对于非密码提示,请在连接前通过服务端环境变量 SSH_MCP_2FA_CODE 提供验证码。
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "example.com",
"--port", "22",
"--username", "user",
"--password", "your_password",
"--privateKey", "/path/to/key",
"--try-keyboard"
]
}
}
}
认证流程:
- 私钥认证(如果提供)
- 密码认证(如果提供)
- 键盘交互式认证通过
SSH_MCP_2FA_CODE提供 2FA 验证码
10. 🧩 多 SSH 连接配置
需要在同一个 MCP server 里同时管理多个 SSH 目标时,给每个连接命名,调用时通过 connectionName 选择。共有四种配置方式:
📄 方式一:使用配置文件(推荐)
创建 JSON 配置文件(例如 ssh-config.json):
数组格式:
[
{
"name": "dev",
"host": "1.2.3.4",
"port": 22,
"username": "alice",
"password": "{abc=P100s0}",
"socksProxy": "socks://127.0.0.1:10808",
"commandTimeoutMs": 120000,
"maxOutputBytes": 10485760
},
{
"name": "bastion",
"host": "9.9.9.9",
"port": 22,
"username": "ops",
"password": "pwd123456",
"transportMode": "shell",
"shellReadyTimeoutMs": 15000,
"shellCommandTimeoutMs": 45000,
"connectionTimeoutMs": 30000,
"keepaliveIntervalMs": 10000,
"keepaliveCountMax": 3
},
{
"name": "prod",
"host": "5.6.7.8",
"port": 22,
"username": "bob",
"password": "yyy",
"socksProxy": "socks://127.0.0.1:10808"
},
{
"name": "secure-server",
"host": "secure.example.com",
"port": 22,
"username": "admin",
"password": "your_password",
"privateKey": "/path/to/private/key",
"tryKeyboard": true
}
]
对象格式:
{
"dev": {
"host": "1.2.3.4",
"port": 22,
"username": "alice",
"password": "{abc=P100s0}",
"socksProxy": "socks://127.0.0.1:10808",
"commandTimeoutMs": 120000,
"maxOutputBytes": 10485760
},
"bastion": {
"host": "9.9.9.9",
"port": 22,
"username": "ops",
"password": "pwd123456",
"transportMode": "shell",
"shellReadyTimeoutMs": 15000,
"shellCommandTimeoutMs": 45000
},
"prod": {
"host": "5.6.7.8",
"port": 22,
"username": "bob",
"password": "yyy",
"socksProxy": "socks://127.0.0.1:10808"
}
}
然后使用 --config-file 参数:
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--config-file", "ssh-config.json"
]
}
}
}
🔧 方式二:使用 JSON 格式的 --ssh 参数
可以直接传递 JSON 格式的配置字符串:
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--ssh", "{\"name\":\"dev\",\"host\":\"1.2.3.4\",\"port\":22,\"username\":\"alice\",\"password\":\"{abc=P100s0}\",\"socksProxy\":\"socks://127.0.0.1:10808\"}",
"--ssh", "{\"name\":\"bastion\",\"host\":\"9.9.9.9\",\"port\":22,\"username\":\"ops\",\"password\":\"pwd123456\",\"transportMode\":\"shell\",\"shellReadyTimeoutMs\":15000}",
"--ssh", "{\"name\":\"prod\",\"host\":\"5.6.7.8\",\"port\":22,\"username\":\"bob\",\"password\":\"yyy\",\"socksProxy\":\"socks://127.0.0.1:10808\"}"
]
}
}
}
📝 方式三:旧格式逗号分隔(向后兼容)
对于密码中不包含特殊字符的简单情况,仍可使用旧格式:
npx @fangjunjie/ssh-mcp-server \
--ssh "name=dev,host=1.2.3.4,port=22,user=alice,password=xxx" \
--ssh "name=prod,host=5.6.7.8,port=22,user=bob,password=yyy"
⚠️ 注意:旧格式在处理包含特殊字符(如
=、,、{、})的密码时可能会有问题。如果密码包含特殊字符,请使用方式一或方式二。
🔑 方式四:--host 逗号分隔多值(复用 ~/.ssh/config)
--host 支持逗号分隔多个主机,进入多连接模式:每个主机作为独立连接,连接名为主机值本身;单值 --host 行为不变(连接名仍为 default)。每个主机独立套用与单主机相同的合并规则——命中 SSH config 别名则展开 HostName/Port/User/IdentityFile,命令行参数逐字段覆盖。适合多台主机都已在 ~/.ssh/config 中配好的场景,无需编写任何 JSON:
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"@fangjunjie/ssh-mcp-server",
"--host", "myserver,anotherserver",
"--pty", "false"
]
}
}
}
认证解析按是否提供 CLI 认证参数(--password/--privateKey/--agent)分两种模式:
- 未提供:每个别名独立从 SSH config 解析认证(该别名的 IdentityFile 优先,其次
~/.ssh默认身份文件回退,最后 SSH agent) - 提供:全部主机共享该 CLI 认证,SSH config 的 IdentityFile 不参与(别名与裸 IP 行为一致,仅地址展开不同);
--passphrase作为密钥解密口令可共享
其余 CLI 策略参数(--pty、--whitelist、超时等)作为进程级默认值共享给全部主机,无需逐服务器重复。任一主机缺用户名或认证来源时,启动即报错并列出该主机。需要为不同主机配置不同的策略(端口、白名单、超时等)时,请使用方式一。
在MCP工具调用时,通过 connectionName 参数指定目标连接名称,未指定时使用默认连接。
示例(在prod连接上执行命令):
{
"tool": "execute-command",
"params": {
"cmdString": "ls -al",
"connectionName": "prod"
}
}
示例(带超时选项的命令执行):
{
"tool": "execute-command",
"params": {
"cmdString": "ping -c 10 127.0.0.1",
"connectionName": "prod",
"timeout": 5000
}
}
⏱️ 命令执行超时
execute-command 工具支持超时选项,防止命令无限期挂起:
- timeout: 单次调用的命令执行超时时间(毫秒,可选);传入时会覆盖连接配置,未传入时使用对应连接配置或其 30000ms 默认值
- 在 JSON 配置文件里为单个连接设置
commandTimeoutMs,可以改掉这个默认值,避免每次调用都手动传timeout(exec模式) shell模式对应的配置项是shellCommandTimeoutMs- 调用参数里的
timeout始终优先于上面两个配置项 - 连接默认启用 SSH keepalive(
keepaliveIntervalMs: 10000,keepaliveCountMax: 3),并使用connectionTimeoutMs限制连接建立时间 - SFTP 打开和传输操作使用
sftpTimeoutMs控制超时(默认 300000ms) - 错误响应现在包含稳定的
code、message、retriable字段,便于上层 Agent 处理 - 命令正常执行但以非零退出码结束(如
grep无匹配、diff有差异)时,execute-command直接返回命令输出并在末尾附上[exit code] N,不再作为工具错误、也不再包成 JSON;超时、连接失败、校验失败等真正的错误仍按上一条返回code/message/retriable
这对于像 ping、tail -f 或其他可能阻塞执行的长时间运行进程特别有用。
📄 文件读写与目录传输
read-file:读取远程文本文件的一个字节范围(offset/length,默认最多 65536 字节)。返回内容前有[bytes] 起-止 of 总大小头部,未读完时给出next offset,便于分页。检测到二进制内容(NUL 字节或大量无效 UTF-8)时拒绝并提示改用downloadwrite-file:直接把文本内容写入远程文件(append: true追加,mode指定新建文件权限)。内容不经过 shell,因此引号、$、反引号、多行内容都不需要转义upload/download的路径是目录时会递归传输:远端目录不存在则创建,符号链接等非普通文件会跳过,单次最多 2000 个文件(更大的目录请先打包)。文件逐个传输,路径校验与单文件相同- 以上均使用 SFTP,受
allowedLocalPaths/allowedRemotePaths限制,shell模式下不可用
📦 命令输出限制
会限制单条命令捕获的 stdout 和 stderr 总量,避免大文件或无限输出耗尽 MCP server 内存:
- 在 JSON 连接配置中使用
maxOutputBytes设置上限,默认值为10485760(10 MiB) maxOutputBytes必须是非负整数;设置为0可禁用限制,但不建议对不受信任的命令禁用- 输出超过限制时,远端命令会被中止,工具返回
OUTPUT_LIMIT_EXCEEDED错误和已经捕获的截断输出,不会把中止的命令误报为成功 - 当
pty为false时,成功命令写入stderr的警告或进度信息会保留在[stderr]区段中 exec与shell两种模式都会应用该限制。区别在于exec模式只关闭该命令的通道,而shell模式的通道由该连接上的所有命令共用、远端在中止后仍会继续写入,因此会断开连接(与 shell 模式命令超时的处理一致)
🧵 后台任务
execute-command 会在超时后放弃命令,构建、部署这类长任务应改用后台任务:
job-start:在远端后台启动命令并立即返回job_id。命令与execute-command一样经过commandWhitelist/commandBlacklist校验job-status:返回状态(running/exited/killed/lost)、退出码、已运行时间和输出。不带offset时返回输出末尾(tailBytes,默认 8192);带offset时从该字节继续读,返回里给出next offset,重复轮询只会读到新增内容job-kill:先SIGTERM,5 秒后仍未退出则SIGKILL,并递归终止子进程job-list:列出最近的任务及状态- 任务的状态(命令、输出、pid、退出码)保存在远端
~/.ssh-mcp-jobs/<id>/,因此 MCP 重启或 SSH 连接断开都不会丢失;已结束超过 7 天的任务目录会在下次job-start时清理 job-kill只会向命令行中带有该任务 id 的进程发信号,避免 pid 被复用后误杀无关进程;此时任务显示为lost- 远端需要 POSIX
sh,有setsid时任务独立成进程组;shell(堡垒机)模式同样可用
🗂️ 列出所有SSH服务器
可以通过MCP工具 list-servers 获取所有可用的SSH服务器配置:
调用示例:
{
"tool": "list-servers",
"params": {}
}
返回示例:
[
{ "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" },
{ "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" }
]
🌐 HTTP 传输(Streamable HTTP)
进程默认使用 stdio,现有 command / args 配置保持可用。需要客户端通过 URL 连接时,用 --mcp-transport http 把同一进程跑成 MCP Streamable HTTP 服务,端点默认是 http://127.0.0.1:3000/mcp。
先在本机启动服务。令牌放在环境变量里,避免出现在进程参数中:
export SSH_MCP_HTTP_TOKEN='replace-with-a-long-random-token'
npx -y @fangjunjie/ssh-mcp-server \
--mcp-transport http \
--http-host 127.0.0.1 \
--http-port 3000 \
--host 192.168.1.1 \
--port 22 \
--username root \
--privateKey ~/.ssh/id_rsa
MCP 客户端配置 URL:
{
"mcpServers": {
"ssh-mcp-server": {
"url": "http://127.0.0.1:3000/mcp",
"headers": {
"Authorization": "Bearer replace-with-a-long-random-token"
}
}
}
}
--http-token 与 SSH_MCP_HTTP_TOKEN 同时设置时,以命令行参数为准。未设置令牌时只建议绑定 127.0.0.1。监听 0.0.0.0 或其他非本机地址时,任何能访问该端口的客户端都可以执行远程命令,启动日志会给出警告。
⚙️ 命令行选项参考
选项:
--config-file JSON 配置文件路径(推荐用于多服务器配置)
--ssh-config-file SSH 配置文件路径(默认: ~/.ssh/config)
--ssh SSH 连接配置(可以是 JSON 字符串或旧格式)
-h, --host SSH 服务器主机地址或 SSH 配置中的别名(逗号分隔多值进入多连接模式)
-p, --port SSH 服务器端口
-u, --username SSH 用户名
-w, --password SSH 密码
-k, --privateKey SSH 私钥文件路径
-P, --passphrase 私钥密码(如果有的话)
-a, --agent SSH agent socket 路径
--try-keyboard 启用键盘交互式认证以支持 2FA/MFA(默认: false)
-W, --whitelist 命令白名单,以逗号分隔的正则表达式
-B, --blacklist 命令黑名单,以逗号分隔的正则表达式
--proxy 代理地址,支持 SOCKS5、HTTP 和 HTTPS
-s, --socksProxy 旧版 SOCKS5 代理地址(兼容参数)
--allowed-local-paths upload/download 允许访问的额外本地路径,逗号分隔
--allowed-remote-paths SFTP upload/download 允许访问的远端路径(POSIX 绝对路径或 Windows 盘符绝对路径,如 /var/log 或 C:/Users),逗号分隔
--transport-mode SSH transport 模式: exec 或 shell(默认: exec)
--shell-ready-timeout shell 就绪探测超时,单位毫秒(默认: 10000)
--command-template 命令模板;shell 参数用 <quotedCommand>,原样插入用 <command>
--pty <true|false> 为命令执行分配伪终端(默认: true)
--pre-connect 启动时预连接所有配置的 SSH 服务器
--mcp-transport MCP 客户端传输:stdio 或 http(默认: stdio)
--http-host HTTP 监听地址(默认: 127.0.0.1)
--http-port HTTP 监听端口(默认: 3000,0 表示由系统分配)
--http-path HTTP 端点路径(默认: /mcp)
--http-token HTTP Bearer 令牌;未传时读取环境变量 SSH_MCP_HTTP_TOKEN
--version, -v 打印包版本
--help 打印帮助信息
🛡️ 安全注意事项
该服务器提供了在远程服务器上执行命令和传输文件的强大功能。为确保安全使用,请注意以下几点:
- 命令白名单:强烈建议 使用
--whitelist选项来限制可执行的命令集合。如果没有白名单,任何命令都可以在远程服务器上执行,这可能带来重大的安全风险。 - 私钥安全:服务器会将 SSH 私钥读入内存。请确保运行
ssh-mcp-server的机器是安全的。不要将服务器暴露给不受信任的网络。 - HTTP 端点:HTTP 模式默认只监听
127.0.0.1。对外网卡监听时请配置--http-token或SSH_MCP_HTTP_TOKEN。令牌相当于远程命令执行的钥匙,使用长随机字符串,并优先放在环境变量中。 - 拒绝服务攻击 (DoS):服务器没有内置的速率限制。攻击者可能通过向服务器发送大量连接请求或大文件传输来发起 DoS 攻击。建议在具有速率限制功能的防火墙或反向代理后面运行服务器。
- 路径遍历:服务器内置了对本地文件系统路径遍历攻击的保护。但是,仍然需要注意在
upload和download命令中使用的路径。 - 本地传输范围:默认仅允许访问当前工作目录。只有在明确可信时,才建议通过
--allowed-local-paths或配置文件中的allowedLocalPaths放宽范围。 - 远端传输范围:SFTP upload/download 接受 POSIX 绝对路径(如
/var/log/app.log)和 Windows 盘符绝对路径(如C:/Users/foo/bar.txt,自动归一化为正斜杠)。未配置allowedRemotePaths(或--allowed-remote-paths)时,任意远端路径都允许,但启动时会打印警告。强烈建议显式配置allowedRemotePaths白名单,避免模型被 prompt 注入后读写~/.ssh/authorized_keys、/etc/sshd_config之类敏感文件。
🌟 Star 历史
Star History
ssh MCP 질문
ssh MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add ssh-mcp-server -- npx -y @fangjunjie/ssh-mcp-server를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
ssh MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
AI가 실행할 수 있는 명령을 어떻게 안전하게 제어할 수 있나요?
--whitelist 및 --blacklist 플래그를 사용하여 정규 표현식으로 허용 또는 금지할 명령 범위를 정의할 수 있습니다.
서버에서 다요소 인증(2FA)을 어떻게 처리하나요?
--try-keyboard 플래그를 활성화하면 SSH_MCP_2FA_CODE 환경 변수를 사용하여 2FA 프롬프트를 처리할 수 있습니다.