Skip to content
/ mcp-ssh Public

🔐 SSH MCP Tool - AI-powered SSH management through MCP protocol | 基于MCP协议的SSH工具，为AI提供SSH远程操作能力

31 stars 5 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

shuakami/mcp-ssh

BranchesTags

Repository files navigation

SSH MCP 工具

ISC License Node.js TypeScript SSH

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 行

AI 助手会：

  1. 检查文件权限
  2. 使用适当的命令读取文件
  3. 格式化并返回内容

高级功能

阻塞检测

SSH MCP 工具内置了智能的阻塞检测机制：

  • 自动检测交互式程序（如 vim、nano）
  • 识别后台运行的阻塞进程
  • 支持设置等待超时时间（最长10分钟）
  • 提供强制执行选项（使用 force 参数）

复合命令处理

支持执行包含 && 和 ; 的复合命令：

  • 智能拆分和执行多个命令
  • 保持命令执行顺序
  • 提供详细的执行状态
  • 支持错误处理和回滚

tmux 集成

完整的 tmux 会话管理支持：

  • 创建和管理持久化会话
  • 支持发送按键序列
  • 实时捕获会话输出
  • 智能处理会话状态

增强提示设置

为了更好地使用 SSH MCP 工具与远程服务器协作，建议在 Cursor 中添加以下 CursorRules 设置：

推荐的 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！在提交之前，请：

  1. 查看现有的 Issue 和 PR
  2. 遵循项目的代码风格
  3. 添加适当的测试用例
  4. 更新相关文档

许可证

本项目采用 ISC 许可证 - 详见 LICENSE 文件

If this project helps you, please give it a Star ⭐️ (｡♥‿♥｡)

使用 Docker 运行 (推荐)

您也可以在 Docker 容器中运行此工具。这是推荐的使用方式，因为它可以避免与您的本地环境产生任何潜在的冲突。

  1. 构建 Docker 镜像:

    docker build -t mcp-ssh .

  2. 运行 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

About

🔐 SSH MCP Tool - AI-powered SSH management through MCP protocol | 基于MCP协议的SSH工具，为AI提供SSH远程操作能力

Topics

nodejs tmux ssh devops automation typescript terminal ai mcp cursor remote-management ai-tools model-context-protocol

Resources

Readme
Activity

Stars

31 stars

Watchers

2 watching

Forks

5 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages