使用说明

mcp-ssh持久

用于持久SSH连接的MCP服务器，支持Claude Code的流媒体。

特性

持久连接 -连接一次，运行多个命令
双通道支持
- ssh_exec -带有退出代码的无状态命令
- ssh_stream_* -有状态的互动会议
自动读取输出 - ssh_stream_write 立即返回输出
SFTP支持 -直接上传/下载文件
快速检测 -自动检测命令完成

需求

Node.js>=18
克劳德代码CLI或克劳德桌面

安装

选项1:npx（推荐）

无需安装，只需配置和使用即可。

选项2：全局安装

npm install -g mcp-ssh-persistent

配置

Claude 代码命令行界面

添加 ~/.claude/settings.json:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-persistent"]
    }
  }
}

克劳德桌面（macOS）

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-persistent"]
    }
  }
}

克劳德桌面（Windows）

添加 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-persistent"]
    }
  }
}

带Claude扩展名的VS代码

添加到VS代码设置(Ctrl+, → 搜索“克劳德·麦克普”）：

{
  "claude.mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-persistent"]
    }
  }
}

配置后，重新启动Claude Code/Desk以加载MCP服务器。

工具

工具	说明
`ssh_connect`	连接到SSH服务器
`ssh_exec`	执行命令（返回退出代码）
`ssh_stream_start`	启动交互式shell
`ssh_stream_write`	写入+自动读取输出
`ssh_stream_read`	读取流缓冲区
`ssh_stream_stop`	停止流
`ssh_upload`	通过SFTP上传文件
`ssh_download`	通过SFTP下载文件
`ssh_write_remote_file`	写入远程文件
`ssh_read_remote_file`	读取远程文件
`ssh_status`	连接状态
`ssh_disconnect`	断开连接
`ssh_reset_shell`	重置外壳状态

用法

连接

// With private key
ssh_connect({
  host: "192.168.1.100",
  username: "user",
  privateKeyPath: "/path/to/private-key"
})

// With password
ssh_connect({
  host: "192.168.1.100",
  username: "user",
  password: "your-password"
})

快速命令（ssh_exec）

最适合需要退出代码的一次性命令：

ssh_exec({ command: "ls -la" })
// Returns: output + [exit code: 0]

ssh_exec({ command: "npm test" })
// Returns: output + [exit code: 0 or 1]

互动会话（ssh_stream_*）

最适合有状态操作（cd、sudo、环境变量）：

// Start shell
ssh_stream_start({ stream_id: "main", command: "bash" })

// Run commands - output returned immediately!
ssh_stream_write({ data: "cd /var/www\n" })
ssh_stream_write({ data: "ls -la\n" })

// Sudo with password prompt
ssh_stream_write({ data: "sudo apt update\n" })
// Returns: "[sudo] password for user:" with [complete: true]
ssh_stream_write({ data: "your-password\n" })
// Returns: command output

// Cleanup when done
ssh_stream_stop({ stream_id: "main" })

文件操作（SFTP）

// Upload local file to remote
ssh_upload({ local_path: "./app.zip", remote_path: "/home/user/" })

// Download remote file to local
ssh_download({ remote_path: "/var/log/app.log", local_path: "./app.log" })

// Write content directly to remote file
ssh_write_remote_file({ remote_path: "/tmp/config.json", content: '{"key": "value"}' })

// Read remote file content
ssh_read_remote_file({ remote_path: "/etc/nginx/nginx.conf" })

自动读取功能

ssh_stream_write 自动轮询输出（每100ms一次），并在以下情况下返回：

检测到外壳提示($, #, >)
检测到密码提示（例如。， [sudo] password for user:)
已超时（默认5秒）

// Auto-read enabled (default)
ssh_stream_write({ data: "ls -la\n" })
// → Returns output immediately with [complete: true]

// Disable auto-read for long-running commands
ssh_stream_write({ data: "tail -f /var/log/app.log\n", wait_ms: 0 })
// → Returns immediately, use ssh_stream_read to get output later

何时使用Which？

场景	工具
一次性命令	`ssh_exec`
需要退出代码	`ssh_exec`
Sudo命令	`ssh_stream_*`
更改目录	`ssh_stream_*`
设置环境变量	`ssh_stream_*`
长时间运行的命令	`ssh_stream_*`
文件传输	`ssh_upload` / `ssh_download`

许可证

麻省理工学院