SSH MCP 工具
English Version (README-EN.md)
这是什么
这是一个基于 MCP (Model Context Protocol) 的 SSH 工具，它能让 AI 模型通过标准化接口访问和管理 SSH 连接。
简单来说，它让 AI 助手能够执行各种 SSH 操作，如连接服务器、执行命令、管理文件等，无需用户手动输入复杂的命令或切换到终端。
- 连接管理：创建、获取、列表、更新、删除 SSH 连接
- 命令执行：执行单条命令、复合命令、后台任务
- tmux 会话管理：创建、获取、列表、发送按键、捕获输出
- 文件操作：上传、下载、查看文件内容
- 进程管理：检测阻塞进程、智能等待、超时处理
- 安全控制：密码/密钥认证、超时控制、错误处理
以下是 SSH MCP 工具的一些核心特点：
- 智能命令执行：自动检测并等待阻塞进程，避免会话卡死
- tmux 集成：完整支持 tmux 会话管理，实现持久化终端会话
- 复合命令支持：智能处理包含
&&和;的复合命令 - 实时反馈：命令执行状态实时更新，支持长时间运行的任务
- 错误恢复：自动处理断线重连、超时等异常情况
- 安全可靠：支持多种认证方式，保护敏感信息
通过简单的自然语言指令，AI 可以帮助你完成上述所有操作，无需手动编写复杂的 SSH 命令或在终端中执行操作。
快速上手
0. 环境准备
-
Python 3.11+（必需）
- 访问 Python 官网
- 下载并安装 Python 3.11 或更高版本
- 重要：安装时请勾选"Add Python to PATH"选项
- 安装完成后请重启电脑，确保环境变量生效
-
Node.js 和 npm
- 访问 Node.js 官网
- 下载并安装 LTS（长期支持）版本
- 安装时选择默认选项即可，安装包会同时安装 Node.js 和 npm
-
Git
- 访问 Git 官网
- 下载并安装 Git
- 安装时使用默认选项即可
-
tmux (远程服务器需要)
- 在远程服务器上安装 tmux
- 对于 Ubuntu/Debian:
sudo apt-get install tmux - 对于 CentOS/RHEL:
sudo yum install tmux
1. 克隆并安装
git clone https://github.com/shuakami/mcp-ssh.git
cd mcp-ssh
npm install
npm run build
⚠️ 重要提示：安装后请不要删除克隆或解压的文件，插件需要持续访问这些文件！
2. 构建项目
npm run build
3. 添加到 Cursor MCP 配置
根据你的操作系统，按照以下步骤配置 MCP：
-
在 Cursor 中，打开或创建 MCP 配置文件：
C:\\Users\\你的用户名\\.cursor\\mcp.json- 注意：请将
你的用户名替换为你的 Windows 用户名
- 注意：请将
-
添加或修改配置如下：
{
"mcpServers": {
"ssh-mcp": {
"command": "pythonw",
"args": [
"C:/Users/你的用户名/mcp-ssh/bridging_ssh_mcp.py"
]
}
}
}
⚠️ 请注意:
- 将
你的用户名替换为你的 Windows 用户名- 确保路径正确指向你克隆或解压的项目目录
- 路径应该反映你将项目文件放置的实际位置
- 不要删除克隆或解压的文件夹，这会导致 MCP 无法正常工作
-
在 Cursor 中，打开或创建 MCP 配置文件：
/Users/你的用户名/.cursor/mcp.json- 注意：请将
你的用户名替换为你的 macOS 用户名
- 注意：请将
-
添加或修改配置如下：
{
"mcpServers": {
"ssh-mcp": {
"command": "python3",
"args": [
"/Users/你的用户名/mcp-ssh/bridging_ssh_mcp.py"
]
}
}
}
⚠️ 请注意:
- 将
你的用户名替换为你的 macOS 用户名- 确保路径正确指向你克隆或解压的项目目录
- 路径应该反映你将项目文件放置的实际位置
- 不要删除克隆或解压的文件夹，这会导致 MCP 无法正常工作
-
在 Cursor 中，打开或创建 MCP 配置文件：
/home/你的用户名/.cursor/mcp.json- 注意：请将
你的用户名替换为你的 Linux 用户名
- 注意：请将
-
添加或修改配置如下：
{
"mcpServers": {
"ssh-mcp": {
"command": "python3",
"args": [
"/home/你的用户名/mcp-ssh/bridging_ssh_mcp.py"
]
}
}
}
⚠️ 请注意:
- 将
你的用户名替换为你的 Linux 用户名- 确保路径正确指向你克隆或解压的项目目录
- 路径应该反映你将项目文件放置的实际位置
- 不要删除克隆或解压的文件夹，这会导致 MCP 无法正常工作
4. 启动服务
配置好之后，重启 Cursor 编辑器，它会自动启动 MCP 服务。然后你就可以开始使用了。
5. 配置 SSH 连接
-
在 Cursor 编辑器中，使用 AI 助手创建新的 SSH 连接：
请帮我创建一个新的 SSH 连接，连接到我的服务器 -
AI 助手会引导你提供以下信息：
- 主机地址（IP 或域名）
- 端口号（默认 22）
- 用户名
- 认证方式（密码或密钥）
- 其他可选配置（超时时间、密钥路径等）
-
连接创建后，你可以通过以下命令测试连接：
请帮我测试刚才创建的 SSH 连接
使用示例
请在服务器上执行 ls -la 命令
AI 助手会：
- 检查现有 SSH 连接
- 执行命令并返回结果
- 格式化输出以提高可读性
请创建一个新的 tmux 会话并运行 top 命令
AI 助手会：
- 创建新的 tmux 会话
- 在会话中执行 top 命令
- 返回会话 ID 供后续使用
请帮我查看 /var/log/syslog 文件的最后 100 行
AI 助手会：
- 检查文件权限
- 使用适当的命令读取文件
- 格式化并返回内容
高级功能
阻塞检测
SSH MCP 工具内置了智能的阻塞检测机制：
- 自动检测交互式程序（如 vim、nano）
- 识别后台运行的阻塞进程
- 支持设置等待超时时间（最长10分钟）
- 提供强制执行选项（使用 force 参数）
复合命令处理
支持执行包含 && 和 ; 的复合命令：
- 智能拆分和执行多个命令
- 保持命令执行顺序
- 提供详细的执行状态
- 支持错误处理和回滚
tmux 集成
完整的 tmux 会话管理支持：
- 创建和管理持久化会话
- 支持发送按键序列
- 实时捕获会话输出
- 智能处理会话状态
增强提示设置
为了更好地使用 SSH MCP 工具与远程服务器协作，建议在 Cursor 中添加以下 CursorRules 设置：
在**需要、或可能需要用户协助的**ssh任务时，可创建tmux，一个可共享的终端会话，并直接**告诉用户**可以通过什么命令链接到tmux来和你协作（不要在mcp内告诉用户，你应该输出出来）。然后再开始你的任务。
**你必须在tmux内进行任务。可以使用tmux send-keys相关命令，mcp会自动返回当前运行的命令和上一个运行的命令的结果。**
你应该先查看现有的tmux窗口再做决定。
**注意：在命令运行时必须耐心等待（sleep命令）当前命令，不要/同时/后台/继续执行下一个任务/命令。**
在用户没有明确要求时，你不应该创建帮助文件或者指南/报告文件。尤其是用户在找你帮忙的时候，你应该直接说出来。
添加此设置后，AI 助手将能够更智能地处理 SSH 任务，特别是在需要用户协作的场景中，可以创建共享的 tmux 会话，让远程操作更加高效和透明。
工作原理
本工具基于 MCP (Model Context Protocol) 标准实现，作为 AI 模型与 SSH 服务之间的桥梁。它使用 node-ssh 作为底层 SSH 客户端，并通过 Zod 进行请求验证和类型检查。
主要技术组件包括：
- SSH 客户端：负责建立和维护 SSH 连接，支持密码和密钥认证
- tmux 管理器：处理 tmux 会话的创建、管理和交互
- 命令执行系统：支持单命令、复合命令的执行，并提供阻塞检测
- 进程监控：实时检测进程状态，避免会话卡死
- 文件传输：支持上传和下载功能，处理各种文件类型
每个 SSH 操作都被封装为标准化的 MCP 工具，接收结构化参数并返回格式化结果。所有远程命令都经过处理，以确保以人类可读的格式呈现，使 AI 模型能够轻松理解命令执行结果。
贡献指南
欢迎提交 Issue 和 Pull Request！在提交之前，请：
- 查看现有的 Issue 和 PR
- 遵循项目的代码风格
- 添加适当的测试用例
- 更新相关文档
许可证
本项目采用 ISC 许可证 - 详见 LICENSE 文件
If this project helps you, please give it a Star ⭐️ (｡♥‿♥｡)
使用 Docker 运行 (推荐)
您也可以在 Docker 容器中运行此工具。这是推荐的使用方式，因为它可以避免与您的本地环境产生任何潜在的冲突。
-
构建 Docker 镜像:
docker build -t mcp-ssh . -
运行 Docker 容器 (附带数据持久化):
为了确保您的连接配置和凭证在容器重启后不丢失，我们强烈建议您使用 Docker 数据卷 (Volume)。
# (首次运行前) 创建一个数据卷来存储数据 docker volume create mcp-ssh-data # 运行容器，并将数据卷挂载到容器的 /root/.mcp-ssh 目录 # 同时，我们仍然建议挂载您本地的 .ssh 目录以使用现有密钥 docker run -it -v mcp-ssh-data:/root/.mcp-ssh -v ~/.ssh:/root/.ssh mcp-ssh在 Windows 上，请使用
%USERPROFILE%\.ssh代替~/.ssh:docker run -it -v mcp-ssh-data:/root/.mcp-ssh -v %USERPROFILE%\.ssh:/root/.ssh mcp-ssh
