MCP SSH 远程连接工具

📖 项目介绍

这是一个功能完整的 MCP (Model Context Protocol) SSH工具，支持通过SSH私钥连接到远程服务器，执行命令，并保持长时间连接。它提供了完整的SSH会话管理功能，包括连接建立、命令执行、连接断开和状态监控。

NPM 仓库地址: @zb2947244682/mcp-ssh

🚀 核心功能

此 MCP 服务提供了强大的SSH远程管理工具：

🔗 connect_ssh 工具

建立SSH连接到远程服务器，支持私钥认证和连接管理。

参数说明

| 参数 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| | host | 字符串 | ✅ | - | 远程服务器地址 | | port | 数字 | ❌ | 22 | SSH端口号 | | username | 字符串 | ✅ | - | SSH用户名 | | privateKey | 字符串 | ✅ | - | SSH私钥内容（PEM格式） | | passphrase | 字符串 | ❌ | - | 私钥密码（如果有的话） | | connectionName | 字符串 | ❌ | - | 连接名称（用于标识连接） |

使用示例

{
  "tool": "connect_ssh",
  "parameters": {
    "host": "192.168.1.100",
    "port": 22,
    "username": "admin",
    "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
    "connectionName": "生产服务器"
  }
}

📝 execute_command 工具

在已连接的SSH会话中执行远程命令。

参数说明

| 参数 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| | connectionId | 字符串 | ✅ | - | SSH连接的ID | | command | 字符串 | ✅ | - | 要执行的命令 | | timeout | 数字 | ❌ | 30000 | 命令执行超时时间(毫秒) |

使用示例

{
  "tool": "execute_command",
  "parameters": {
    "connectionId": "abc123",
    "command": "ls -la /var/log",
    "timeout": 60000
  }
}

🔌 disconnect_ssh 工具

断开指定的SSH连接。

参数说明

| 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | connectionId | 字符串 | ✅ | 要断开的SSH连接ID |

使用示例

{
  "tool": "disconnect_ssh",
  "parameters": {
    "connectionId": "abc123"
  }
}

📊 get_ssh_stats 工具

获取SSH连接的统计信息和当前状态。

参数说明

无需参数，直接调用即可获取统计信息。

⚙️ 配置说明

在 Cursor 中配置

将以下配置添加到您的 Cursor mcp.json 文件中：

{
  "mcp-ssh": {
    "command": "npx",
    "args": [
      "-y",
      "@zb2947244682/mcp-ssh@latest"
    ]
  }
}

通过 npx 直接运行

您可以通过以下命令直接从命令行运行此 MCP 项目：

npx @zb2947244682/mcp-ssh@latest

本地开发配置

如果您在本地开发环境中使用，可以将以下配置添加到您的 Cursor mcp.json 文件中：

{
  "mcp-ssh": {
    "command": "node",
    "args": ["D:\\Codes\\MCPRepo\\mcp-ssh\\index.js"]
  }
}

🔧 特性

• ✅ 安全连接 - 支持SSH私钥认证
• ✅ 连接管理 - 自动生成唯一连接ID
• ✅ 长时间会话 - 支持保持连接状态
• ✅ 命令执行 - 完整的远程命令执行
• ✅ 超时控制 - 可配置的命令执行超时
• ✅ 错误处理 - 完善的错误信息和处理
• ✅ 状态监控 - 实时连接状态和统计
• ✅ 多连接支持 - 同时管理多个SSH连接

📋 使用流程

1. 建立SSH连接

# 使用 connect_ssh 工具建立连接
# 需要提供：主机地址、用户名、私钥等

2. 执行远程命令

# 使用 execute_command 工具执行命令
# 需要提供：连接ID、要执行的命令

3. 断开连接

# 使用 disconnect_ssh 工具断开连接
# 需要提供：连接ID

4. 查看状态

# 使用 get_ssh_stats 工具查看统计信息
# 无需参数，直接调用

🔐 安全说明

• 私钥安全 - 私钥内容通过MCP协议传输，请确保传输安全
• 连接超时 - 默认30秒连接超时，可防止长时间等待
• 命令超时 - 默认30秒命令执行超时，防止命令卡死
• 连接清理 - 自动清理断开的连接，释放资源

💡 最佳实践

1. 连接命名 - 为重要连接设置有意义的名称
2. 超时设置 - 根据网络情况调整超时时间
3. 错误处理 - 注意检查命令执行结果和错误输出
4. 资源管理 - 及时断开不需要的连接
5. 权限控制 - 确保SSH用户有足够的权限执行所需命令

🐛 常见问题

连接失败

• 检查主机地址和端口是否正确
• 确认SSH服务是否运行
• 验证私钥格式是否正确（PEM格式）
• 检查私钥密码是否正确
• 确认防火墙设置允许SSH连接

命令执行失败

• 检查命令语法是否正确
• 确认用户权限是否足够
• 检查网络连接是否稳定
• 尝试重新连接SSH

连接断开

• 检查网络稳定性
• 确认服务器SSH配置
• 查看连接统计信息

📚 技术细节

• SSH协议 - 使用SSH2协议进行安全连接
• 连接池 - 支持多个并发SSH连接
• 心跳机制 - 自动保持连接活跃
• 异步处理 - 非阻塞的命令执行
• 内存管理 - 自动清理断开的连接

让AI成为你的远程服务器管理助手！ 🚀