SSH MCP Server

SSH MCP 服务

一个提供 SSH 功能的模型上下文协议（MCP）服务实现。此服务支持通过 MCP 协议安全地远程访问和执行操作。

功能

• 使用 MCP 协议实现 SSH 服务
• 集成 SQLite 数据库以持久化数据
• 使用 TypeScript 实现，确保类型安全并提升开发体验

前提条件

• Node.js 18 或更高版本
• npm 或 yarn 包管理器
• 具备 TypeScript 开发知识

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 SSH 服务：

npx -y @smithery/cli install @KinoThe-Kafkaesque/ssh-mcp-server --client claude

手动安装

1. 克隆仓库：

git clone <repository-url>
cd ssh-server

2. 安装依赖：

npm install

3. 构建项目：

npm run build

使用方法

配置

此服务使用 SQLite 数据库（ssh.db）存储 SSH 凭据。服务启动时会自动创建 数据库文件。

工具

此服务会存储命名凭据，之后每项远程操作都通过 credentialName 指定凭据。privateKeyPath 必须指向现有的私钥 （~/ 会展开为你的主目录）。

系统会验证主机密钥：凭据首次连接时，服务会将主机密钥指纹固定保存到 ~/ssh.db 中。之后的连接如果提供了不同的密钥，系统会拒绝连接并返回 HOST_KEY_MISMATCH。若要预先固定已知密钥，请传入 hostKeyFingerprint（即服务器上运行 ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub 后显示的 SHA256:... 值）。密钥合法更换后，请删除该凭据并重新添加。

• add_credential：保存 { "name", "host", "username", "privateKeyPath", "hostKeyFingerprint"? }。
• list_credentials：列出已存储的凭据记录。
• remove_credential：删除 { "name" }。
• ssh_exec：使用 { "credentialName", "command", "timeout" } 运行 shell 命令。
• ssh_exec_raw：运行 argv 格式的命令数组，例如 { "credentialName": "prod", "command": ["grep", "-E", "foo|bar", "/var/log/app.log"] }。
• scp_copy：使用 { "credentialName", "localPath", "remotePath", "direction" } 通过 SFTP 复制单个文件。
• rsync_copy：使用 rsync 复制目录或较大的目录树，传输参数格式相同。
• ssh_session_start、ssh_session_send、ssh_session_read、ssh_session_end、ssh_session_list：管理交互式 SSH 会话。
• ssh_tunnel_start、ssh_tunnel_list、ssh_tunnel_stop：管理本地或远程端口转发隧道。

示例：

{
  "tool_name": "ssh_exec",
  "arguments": {
    "credentialName": "prod",
    "command": "uptime",
    "timeout": 120000
  }
}

启动服务

npm start

服务将在配置的端口上启动（默认设置可在源代码中修改）。

CLI 用法

CLI 与 MCP 服务共享 ~/ssh.db 凭据存储。进行远程操作时，它会使用 OpenSSH 多路复用连接，因此，对同一主机、用户名和密钥进行的独立 CLI 调用会复用同一个已通过身份验证的传输连接。请先构建，然后通过 npm run cli -- 或在执行 npm link 后通过 sshcli 二进制文件运行：

npm run build && npm run cli -- <command>
# or, after linking:
npx sshcli <command>

命令：

sshcli creds add prod --host 1.2.3.4 --user ubuntu --key ~/.ssh/id_rsa
sshcli creds list
sshcli creds rm prod
sshcli exec prod uptime
sshcli exec prod --timeout 30000 -- df -h /
sshcli exec --raw prod grep -E 'foo|bar' /var/log/app.log
sshcli scp prod ./file.txt /tmp/file.txt toRemote
sshcli rsync prod ./dir/ /tmp/dir/ fromRemote
sshcli session prod   # live interactive shell; Ctrl+D or exit to close
sshcli tunnel prod --type local --local-port 8080 --remote-host localhost --remote-port 80
sshcli cache status prod
sshcli cache close prod

注意：

• 对于 exec，可变参数 <command...> 会贪婪匹配，因此请将 --timeout 和 --raw 等选项放在命令标记之前。
• exec、scp、rsync、session 和 tunnel 都会复用同一个连接。默认情况下，空闲连接会缓存 30 分钟。
• 对于某个端点的首次连接尝试，会在 CLI 进程之间串行执行。尝试失败后会触发 15 秒的指数退避重连，最长可达 5 分钟，以防反复调用持续冲击受速率限制的主机。
• session 和 tunnel 是前台命令，会一直阻塞，直到 shell 关闭或你按下 Ctrl+C；退出这些命令不会关闭共享传输连接。
• CLI 特意省略了 session send/read/end/list 和 tunnel list/stop 命令：这些命令的内存状态不会在一次性 CLI 调用之间持久保留。请改用前台 session 和 tunnel 命令。
• 缓存位于 $XDG_RUNTIME_DIR/sshcli/connections 下（或每位用户专用的临时目录中）。可通过 SSHCLI_CONTROL_PERSIST_SECONDS、SSHCLI_RECONNECT_BACKOFF_MS、SSHCLI_RECONNECT_BACKOFF_MAX_MS 或 SSHCLI_CACHE_DIR 调整。
• 对应的 CLI 命令需要在 PATH 中提供 OpenSSH、scp 和 rsync。

项目结构

• src/ - 源代码目录
• build/ - 编译后的 JavaScript 输出
• node_modules/ - 项目依赖

依赖项

• @modelcontextprotocol/sdk：MCP 协议实现
• sqlite3：SQLite 数据库驱动程序
• typescript：TypeScript 支持的开发依赖项

开发

要修改项目：

1. 在 src/ 目录中进行更改
2. 重新构建项目：

npm run build

3. 启动服务以测试更改：

npm start

许可证

MIT

贡献

1. Fork 仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建新的 Pull Request