SSH 远程 MCP 服务器

通过模型上下文协议 (MCP) 为兼容 MCP 的客户端提供 SSH 远程访问。

快速入门

请使用将运行 MCP 服务器的同一操作系统创建的虚拟环境。不要在 Windows 和 WSL/Linux 之间共享同一个 venv。

Windows

1. 安装：

   .\install.ps1

2. 在 Claude Desktop、Claude Code 或 Codex 中添加 MCP：

   {
     "mcpServers": {
       "ssh-remote": {
         "command": "C:\\Users\\Intel\\Desktop\\adremote-mcp\\.venv-win\\Scripts\\python.exe",
         "args": [
           "C:\\Users\\Intel\\Desktop\\adremote-mcp\\ssh_mcp_server.py"
         ]
       }
     }
   }

   如果您已经安装了带有 paramiko 和 mcp 的 Windows Python，则可以直接使用该解释器，而无需使用 .venv-win。

WSL/Linux

1. 安装：

   ./install.sh

2. 在 Claude Desktop、Claude Code 或 Codex 中添加 MCP：

   {
     "mcpServers": {
       "ssh-remote": {
         "command": "/home/user/adremote-mcp/.venv-linux/bin/python",
         "args": [
           "/home/user/adremote-mcp/ssh_mcp_server.py"
         ]
       }
     }
   }

   如果通过 Windows 驱动器访问 WSL 中的存储库，请使用 WSL 路径：

   {
     "mcpServers": {
       "ssh-remote": {
         "command": "/mnt/c/Users/Intel/Desktop/adremote-mcp/.venv-linux/bin/python",
         "args": [
           "/mnt/c/Users/Intel/Desktop/adremote-mcp/ssh_mcp_server.py"
         ]
       }
     }
   }

便携式启动器

您也可以将 MCP 客户端指向对应操作系统的内置启动器：

• Windows: C:\Users\Intel\Desktop\adremote-mcp\run-ssh-mcp.cmd

• WSL/Linux: /path/to/adremote-mcp/run-ssh-mcp.sh

启动器会优先使用操作系统特定的 venv，然后回退到 python3 或 python。在 Windows 上，可以设置 SSH_MCP_PYTHON 来强制使用特定的 Python 解释器。

对于 WSL/Linux 客户端，如果脚本未标记为可执行，请使用 command: "/bin/sh" 和 args: ["/path/to/adremote-mcp/run-ssh-mcp.sh"]。

直接运行

安装依赖项后，您可以直接运行服务器：

Windows:

.\.venv-win\Scripts\python.exe .\ssh_mcp_server.py

WSL/Linux:

./.venv-linux/bin/python ssh_mcp_server.py

自动设置

下载此存储库，运行 Claude 或 Codex，并要求它将此文件夹添加为当前操作系统的全局 MCP 服务器。之后，您就可以直接在聊天中使用它了。

故障排除

如果 Windows 报告：

No Python at '"/usr/bin\python.exe'

说明 MCP 指向的是由 WSL/Linux 创建的 venv。请使用 .\install.ps1 创建一个 Windows venv，并将 MCP 命令更新为 .venv-win\Scripts\python.exe。

Related MCP server: MCP SSH Server

功能

• 适用于 Windows 和 Linux 上兼容 MCP 的客户端

• 通过 SSH 连接到远程服务器

• 原生 SSH 跳板机 (jump-host) / 堡垒机支持

• 远程执行命令

• 通过 SFTP 上传/下载文件

• 管理多个连接

• 健康状况监控

使用示例

使用密码连接：

Connect to 192.168.1.100 with username ubuntu and password mypass

或使用简写形式：

ssh 192.168.1.100:22 ubuntu mypass

MCP 首先会使用您的用户名和密码测试 SSH 连接。如果登录成功，它会生成或安装 SSH 密钥，在本地保存基于密钥的凭据，并且不会保存密码。密码仅在第一次使用。

为一次性会话使用密码连接：

ssh 192.168.1.100:22 ubuntu mypass, save_credentials false

这仅保持实时连接。不会保存可重用的凭据，也不会尝试自动引导密钥。

稍后使用保存的名称连接：

ssh saved-name

首次设置成功后，只需使用保存的凭据名称即可再次连接。

使用加密（受密码保护）的私钥连接：

Connect to 10.0.2.15 as ubuntu using private key ~/.ssh/id_ed25519 with passphrase mysecret

或通过工具参数：

{
  "hostname": "10.0.2.15",
  "username": "ubuntu",
  "private_key_path": "~/.ssh/id_ed25519",
  "private_key_passphrase": "mysecret"
}

密码短语会与保存的凭据一起存储，因此后续调用 ssh_connect_saved 时无需再次输入。您仍然可以在 ssh_connect_saved 上提供 private_key_passphrase 来覆盖存储的值，仅限单次会话。

通过跳板机连接：

在 ssh_connect 或 ssh_save_credentials 上使用 jump_host 对象：

{
  "hostname": "10.0.2.15",
  "username": "ubuntu",
  "private_key_path": "~/.ssh/id_ed25519",
  "jump_host": {
    "hostname": "203.0.113.10",
    "username": "bastion",
    "private_key_path": "~/.ssh/id_ed25519",
    "port": 22
  }
}

跳板机密钥也可以受密码保护 — 在 jump_host 对象中添加 private_key_passphrase。

这会使用原生 SSH 隧道连接到目标主机，保存的凭据会保留相同的跳板机配置。对于可重用的保存凭据，跳板机必须使用 private_key_path 而不是密码。

执行命令：

List files in /home directory on my server
Run 'top' command on the remote server
Execute script.py and monitor its log

文件传输：

Upload local file.txt to /home/user/ on the server
Download /var/log/app.log from the server

连接健康状况和清单：

Check health of all SSH connections
Show me all active SSH connections

要求

• Python 3.10+

• paramiko

• mcp

最新更新

版本 1.0.3 在保存的凭据中持久化私钥密码短语：

• 通过 ssh_connect 或 ssh_save_credentials 保存时，private_key_passphrase 现在会存储在凭据文件中

• ssh_connect_saved 会自动使用存储的密码短语 — 无需在每次调用时提供

• 在 ssh_connect_saved 上提供 private_key_passphrase 仅会覆盖该会话的存储值

• ssh_list_saved_credentials 在存储了密码短语时会显示 private key (passphrase saved)

版本 1.0.2 增加了对受密码保护（加密）私钥的支持：

• ssh_connect、ssh_connect_saved 和 ssh_save_credentials 接受 private_key_passphrase

• 适用于目标主机密钥和跳板机密钥

• 当密钥已加密但未提供密码短语，或密码短语错误时，会显示清晰的错误消息

版本 1.0.1 增加了更安全、更实用的日常 SSH 工作流：

• 直接登录默认仍会保存可重用凭据，但 save_credentials=false 现在也可以明确选择不保存密码会话

• 保存的凭据流程现在包括连接、保存、列出、删除和手动密钥设置助手

• 主机信任和文件传输规则更严格，具有本地根目录限制和首次使用信任的主机固定功能

• 实时会话和保存的凭据均支持原生跳板机连接

• 保存的凭据基于密钥，因此正常使用无需主密码

• 手动保存的私钥路径在保存时即会验证，而不是在首次连接时才验证

支持

联系我进行协作。