mcp-ssh

SSH MCP 工具 (mcp-ssh) 提供一个标准化的接口，让 AI 模型通过 MCP 访问和管理 SSH 连接、执行命令、管理 tmux 会话以及进行文件传输等操作。通过 Cursor MCP 等环境，您可以把桥接脚本 bridging_ssh_mcp.py 作为一个 MCP 服务暴露出来，AI 助手即可对已配置的 SSH 连接执行单条命令、处理复合命令、创建和管理 tmux 会话、上传/下载文件以及监控远程进程。使用时，先在 MCP 配置中指定服务器的执行命令和脚本路径；随后通过自然语言指令向 AI 助手发出请求，例如创建 SSH 连接、在服务器上执行命令、或在 tmux 会话中运行长期任务。AI 助手会返回结构化、可读的结果，支持错误恢复与实时执行状态更新。工具的核心能力包括：智能阻塞检测以避免会话卡死、对包含 && 和 ; 的复合命令的智能处理、完整的 tmux 集成以实现持久化会话、以及安全的认证方式和文件传输支持。简单来说，mcp-ssh 让 AI 能够像人类一样远程管理服务器，而无需手动编写复杂的命令。

前提条件

• Python 3.11 及以上
• Node.js 和 npm
• Git
• tmux（远程服务器需要）

安装步骤

1. 克隆仓库并安装依赖

   git clone https://github.com/shuakami/mcp-ssh.git
   cd mcp-ssh
   npm install
   npm run build
   

2. 运行和集成

   • 根据需要使用 Node 还是直接通过 Python 运行桥接脚本。若作为 MCP 服务接入 Cursor，请使用如下配置（示例中使用 Python3 来执行 bridging_ssh_mcp.py）
   • 确保 bridging_ssh_mcp.py 可访问，并了解相关环境要求，如 SSH 配置、密钥路径等。

3. Docker 运行（可选）

   • 构建镜像并以数据卷挂载的方式运行，这与 README 中的 Docker 使用说明保持一致。

   docker build -t mcp-ssh .
   docker volume create mcp-ssh-data
   docker run -it -v mcp-ssh-data:/root/.mcp-ssh -v ~/.ssh:/root/.ssh mcp-ssh
   

4. 配置 MCP 服务（Cursor 等）

   • 在 Cursor 的 mcp.json 中添加 ssh-mcp 条目，指向 bridging_ssh_mcp.py（路径请替换为实际路径）。示例见 README 的操作说明。

注意事项与提示:

• 确保 bridging_ssh_mcp.py 与所需的 SSH 配置、密钥位置、以及远程主机可访问性一致。
• 如在 Windows、macOS、或 Linux 上使用不同的启动命令，请参照 README 的示例配置进行调整。
• 环境变量可用于传递凭据或配置项，请在 mcpServers 配置中的 env 部分填入 VAR 名称与描述。
• 运行时如遇阻塞或超时，请利用工具提供的等待超时和强制执行选项进行处理。
• Docker 使用时，建议挂载本地的 .ssh 目录以便复用现有密钥，同时将数据卷用于保持连接和凭证的持久化。
• 如需在多种远程服务器上同时管理，请为每个服务器配置单独的条目并在 AI 对话中区分清晰的连接名称。