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. 环境准备

环境要求 (点击展开)

1. Python 3.11+（必需）

   • 访问 Python 官网
   • 下载并安装 Python 3.11 或更高版本
   • 重要：安装时请勾选"Add Python to PATH"选项
   • 安装完成后请重启电脑，确保环境变量生效

2. Node.js 和 npm

   • 访问 Node.js 官网
   • 下载并安装 LTS（长期支持）版本
   • 安装时选择默认选项即可，安装包会同时安装 Node.js 和 npm

3. Git

   • 访问 Git 官网
   • 下载并安装 Git
   • 安装时使用默认选项即可

4. 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：

Windows 配置 (点击展开)

1. 在 Cursor 中，打开或创建 MCP 配置文件：C:\\Users\\你的用户名\\.cursor\\mcp.json

   • 注意：请将 你的用户名 替换为你的 Windows 用户名

2. 添加或修改配置如下：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "pythonw",
      "args": [
        "C:/Users/你的用户名/mcp-ssh/bridging_ssh_mcp.py"
      ]
    }
  }
}

⚠️ 请注意:

• 将 你的用户名 替换为你的 Windows 用户名
• 确保路径正确指向你克隆或解压的项目目录
• 路径应该反映你将项目文件放置的实际位置
• 不要删除克隆或解压的文件夹，这会导致 MCP 无法正常工作

macOS 配置 (点击展开)

1. 在 Cursor 中，打开或创建 MCP 配置文件：/Users/你的用户名/.cursor/mcp.json

   • 注意：请将 你的用户名 替换为你的 macOS 用户名

2. 添加或修改配置如下：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "python3",
      "args": [
        "/Users/你的用户名/mcp-ssh/bridging_ssh_mcp.py"
      ]
    }
  }
}

⚠️ 请注意:

• 将 你的用户名 替换为你的 macOS 用户名
• 确保路径正确指向你克隆或解压的项目目录
• 路径应该反映你将项目文件放置的实际位置
• 不要删除克隆或解压的文件夹，这会导致 MCP 无法正常工作

Linux 配置 (点击展开)

1. 在 Cursor 中，打开或创建 MCP 配置文件：/home/你的用户名/.cursor/mcp.json

   • 注意：请将 你的用户名 替换为你的 Linux 用户名

2. 添加或修改配置如下：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "python3",
      "args": [
        "/home/你的用户名/mcp-ssh/bridging_ssh_mcp.py"
      ]
    }
  }
}

⚠️ 请注意:

• 将 你的用户名 替换为你的 Linux 用户名
• 确保路径正确指向你克隆或解压的项目目录
• 路径应该反映你将项目文件放置的实际位置
• 不要删除克隆或解压的文件夹，这会导致 MCP 无法正常工作

4. 启动服务

配置好之后，重启 Cursor 编辑器，它会自动启动 MCP 服务。然后你就可以开始使用了。

5. 配置 SSH 连接

如何配置 SSH 连接 (点击展开)

1. 在 Cursor 编辑器中，使用 AI 助手创建新的 SSH 连接：

   请帮我创建一个新的 SSH 连接，连接到我的服务器
   

2. AI 助手会引导你提供以下信息：

   • 主机地址（IP 或域名）
   • 端口号（默认 22）
   • 用户名
   • 认证方式（密码或密钥）
   • 其他可选配置（超时时间、密钥路径等）

3. 连接创建后，你可以通过以下命令测试连接：

   请帮我测试刚才创建的 SSH 连接
   

使用示例

基本命令执行 (点击展开)

请在服务器上执行 ls -la 命令

AI 助手会：

1. 检查现有 SSH 连接
2. 执行命令并返回结果
3. 格式化输出以提高可读性

tmux 会话管理 (点击展开)

请创建一个新的 tmux 会话并运行 top 命令

AI 助手会：

1. 创建新的 tmux 会话
2. 在会话中执行 top 命令
3. 返回会话 ID 供后续使用

文件操作 (点击展开)

请帮我查看 /var/log/syslog 文件的最后 100 行