SSH MCP 工具

English Version (README-EN.md)

这是什么

这是一个基于 MCP (Model Context Protocol) 的 SSH 工具，它能让 AI 模型通过标准化接口访问和管理 SSH 连接。

简单来说，它让 AI 助手能够执行各种 SSH 操作，如连接服务器、执行命令、管理文件等，无需用户手动输入复杂的命令或切换到终端。

快速上手

0. 环境准备

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：

4. 启动服务

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

5. 配置 SSH 连接

使用示例

高级功能

阻塞检测

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

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

复合命令处理

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

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

tmux 集成

完整的 tmux 会话管理支持：

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

增强提示设置

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

添加此设置后，AI 助手将能够更智能地处理 SSH 任务，特别是在需要用户协作的场景中，可以创建共享的 tmux 会话，让远程操作更加高效和透明。

工作原理

贡献指南

欢迎提交 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