MCP Ssh Manager

🚀 MCP SSH 管理器

MCP SSH 管理器是一款强大的 Model Context Protocol (MCP) 服务器，它能让 Claude Code 无缝管理多个 SSH 连接。用户可以直接在 Claude Code 中控制远程服务器、执行命令以及传输文件。

🚀 快速开始

1. 克隆仓库

git clone https://github.com/yourusername/mcp-ssh-manager.git
cd mcp-ssh-manager

2. 安装依赖

npm install
pip install -r tools/requirements.txt

3. 配置服务器

运行交互式配置工具：

python tools/server_manager.py

选择选项 2 来添加服务器。你需要提供以下信息：

• 服务器名称（例如，production、staging）
• 主机/IP 地址
• 用户名
• 端口（默认：22）
• 认证方式（密码或 SSH 密钥）

4. 安装到 Claude Code

# 个人使用（仅当前用户）
claude mcp add ssh-manager node /path/to/mcp-ssh-manager/src/index.js

# 团队共享（在项目中创建 .mcp.json）
claude mcp add ssh-manager --scope project node /path/to/mcp-ssh-manager/src/index.js

# 所有项目使用
claude mcp add ssh-manager --scope user node /path/to/mcp-ssh-manager/src/index.js

5. 开始使用！

在 Claude Code 中，你现在可以执行以下操作：

"List all my SSH servers"
"Execute 'ls -la' on production server"  # 如果设置了默认目录，则使用默认目录
"Run 'docker ps' on staging"
"Upload config.json to production:/etc/app/config.json"
"Download logs from staging:/var/log/app.log"

使用默认目录： 如果你将 /var/www/html 设置为生产服务器的默认目录，以下命令是等效的：

• "Run 'ls' on production" → 在 /var/www/html 中执行
• "Run 'ls' on production in /tmp" → 在 /tmp 中执行（覆盖默认目录）

✨ 主要特性

• 🔗 多 SSH 连接 - 可从单个界面管理无限数量的 SSH 服务器
• 🔐 安全认证 - 支持密码和 SSH 密钥两种认证方式
• 📁 文件操作 - 在本地和远程系统之间上传和下载文件
• ⚡ 命令执行 - 在远程服务器上运行命令，并支持工作目录
• 📂 默认目录 - 为每个服务器设置默认工作目录，方便使用
• 🎯 轻松配置 - 通过 .env 文件和引导式配置工具进行简单设置
• 🔧 连接测试 - 内置工具可验证服务器连接性
• 🚀 智能部署 - 新增！自动处理文件部署和权限问题
• 🔑 sudo 支持 - 新增！安全地以 sudo 权限执行命令
• 🏷️ 服务器别名 - 新增！使用短别名代替完整的服务器名称

📦 安装指南

先决条件

• Node.js（v16 或更高版本）
• Python 3.8+
• 安装 Claude Code CLI
• npm（随 Node.js 一起安装）

💻 使用示例

基础用法

在 Claude Code 中执行命令的基础示例：

"List all my SSH servers"

高级用法

使用高级工具进行文件部署和以 sudo 权限执行命令：

# 使用 ssh_deploy 工具部署文件
"ssh_deploy production ['config.json'] {'owner': 'root', 'permissions': '644', 'backup': true, 'restart': false}"

# 使用 ssh_execute_sudo 工具以 sudo 权限执行命令
"ssh_execute_sudo production 'apt update' 'sudo_password' '/tmp'"

📚 详细文档

可用的 MCP 工具

核心工具

• ssh_list_servers：列出所有配置的 SSH 服务器及其详细信息。
• ssh_execute：在远程服务器上执行命令。
  • 参数：server（名称）、command、cwd（可选工作目录）
  • 注意：如果未提供 cwd，则使用服务器的默认目录（如果已配置）
• ssh_upload：将文件上传到远程服务器。
  • 参数：server、local_path、remote_path
• ssh_download：从远程服务器下载文件。
  • 参数：server、remote_path、local_path

高级工具（v1.2+）

• ssh_deploy 🚀：自动处理文件部署的权限和备份。
  • 参数：server、files（数组）、options（所有者、权限、备份、重启）
  • 自动处理权限问题并创建备份
• ssh_execute_sudo 🔐：以 sudo 权限执行命令。
  • 参数：server、command、password（可选）、cwd（可选）
  • 安全处理 sudo 密码，不会在日志中暴露
• ssh_alias 🏷️：管理服务器别名，方便访问。
  • 参数：action（添加/删除/列出）、alias、server
  • 示例：为 "production" 服务器创建别名 "prod"
• ssh_command_alias 📝：管理常用命令的别名。
  • 参数：action（添加/删除/列出/建议）、alias、command
  • 别名从活动配置文件加载
  • 示例：为项目自定义别名
• ssh_hooks 🎣：管理 SSH 操作的自动化钩子。
  • 参数：action（列出/启用/禁用/状态）、hook
  • 钩子从活动配置文件加载
  • 示例：项目特定的验证和自动化
• ssh_profile 📚：管理不同项目类型的配置文件。
  • 参数：action（列出/切换/当前）、profile
  • 可用配置文件：默认、frappe、docker、nodejs
  • 示例：在不同项目配置之间切换

配置

配置文件

SSH 管理器使用配置文件为不同项目类型配置别名和钩子：

1. 设置活动配置文件：

• 环境变量：export SSH_MANAGER_PROFILE=frappe
• 配置文件：创建 .ssh-manager-profile 文件并指定配置文件名称
• 默认：如果未指定，则使用 default 配置文件

2. 可用配置文件：

• default - 基本 SSH 操作
• frappe - 特定于 Frappe/ERPNext
• docker - Docker 容器管理
• nodejs - Node.js 应用程序
• 可在 profiles/ 目录中创建自定义配置文件

环境变量

服务器在 .env 文件中按以下模式进行配置：

# 服务器配置模式
SSH_SERVER_[NAME]_HOST=hostname_or_ip
SSH_SERVER_[NAME]_USER=username
SSH_SERVER_[NAME]_PASSWORD=password  # 用于密码认证
SSH_SERVER_[NAME]_KEYPATH=~/.ssh/key  # 用于 SSH 密钥认证
SSH_SERVER_[NAME]_PORT=22  # 可选，默认为 22
SSH_SERVER_[NAME]_DEFAULT_DIR=/path/to/dir  # 可选，默认工作目录
SSH_SERVER_[NAME]_DESCRIPTION=Description  # 可选

# 示例
SSH_SERVER_PRODUCTION_HOST=prod.example.com
SSH_SERVER_PRODUCTION_USER=admin
SSH_SERVER_PRODUCTION_PASSWORD=secure_password
SSH_SERVER_PRODUCTION_PORT=22
SSH_SERVER_PRODUCTION_DEFAULT_DIR=/var/www/html
SSH_SERVER_PRODUCTION_DESCRIPTION=Production Server
SSH_SERVER_PRODUCTION_SUDO_PASSWORD=secure_sudo_pass  # 可选，用于自动部署

服务器管理工具

Python 管理工具 (tools/server_manager.py) 提供以下功能：

1. 列出服务器 - 查看所有已配置的服务器
2. 添加服务器 - 交互式服务器配置
3. 测试连接 - 验证服务器连接性
4. 删除服务器 - 删除服务器配置
5. 更新 Claude Code - 在 Claude Code 中配置 MCP
6. 安装依赖 - 设置所需的软件包

项目结构

mcp-ssh-manager/
├── src/
│   └── index.js           # 主要的 MCP 服务器实现
├── tools/
│   ├── server_manager.py  # 交互式服务器管理
│   ├── test-connection.py # 连接测试工具
│   └── requirements.txt   # Python 依赖项
├── examples/
│   ├── .env.example       # 示例配置
│   └── claude-code-config.example.json
├── package.json           # Node.js 依赖项
├── .env                   # 你的服务器配置（从 .env.example 创建）
└── README.md             # 本文件

测试

测试服务器连接

python tools/test-connection.py production

验证 MCP 安装

claude mcp list

在 Claude Code 中检查服务器状态

/mcp

高级用法

文档

• DEPLOYMENT_GUIDE.md - 部署策略和权限处理
• ALIASES_AND_HOOKS.md - 命令别名和自动化钩子
• 实际示例和最佳实践

故障排除

MCP 工具不可用

1. 确保已安装 MCP：claude mcp list
2. 安装后重启 Claude Code
3. 检查服务器日志中的错误

连接失败

1. 测试连接：python tools/test-connection.py [server_name]
2. 验证网络连接
3. 检查防火墙规则
4. 确保远程服务器上的 SSH 服务正在运行

权限被拒绝

1. 验证用户名和密码/密钥
2. 检查 SSH 密钥权限：chmod 600 ~/.ssh/your_key
3. 确保用户在远程服务器上具有必要的权限

贡献

我们欢迎贡献！请参阅 CONTRIBUTING.md 了解详细信息。

开发设置

1. 分叉仓库
2. 克隆并安装依赖项
3. 设置预提交钩子 以保证代码质量：

./scripts/setup-hooks.sh

4. 创建你的功能分支
5. 进行更改（提交时钩子将进行验证）
6. 推送到你的分支
7. 打开拉取请求

代码质量

本项目使用自动化质量检查：

• ESLint 用于 JavaScript 代码检查
• Black 用于 Python 代码格式化
• Flake8 用于 Python 代码检查
• Prettier 用于代码格式化
• 预提交钩子 用于自动验证
• 密钥检测 以防止凭证泄露 手动运行验证：./scripts/validate.sh

🔧 技术细节

安全最佳实践

1. 切勿提交 .env 文件 - 始终使用 .env.example 作为模板
2. 尽可能使用 SSH 密钥 - 比密码更安全
3. 限制服务器访问 - 使用最小必要权限
4. 定期轮换凭证 - 定期更新密码和密钥

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

🙏 致谢

• 为 Claude Code 构建
• 使用 Model Context Protocol
• 通过 node-ssh 处理 SSH
• 使用 Paramiko 进行服务器管理

📧 支持

如有问题、疑问或建议：

• 在 GitHub Issues 上打开问题
• 在创建新问题之前检查现有问题

为 Claude Code 社区精心打造 ❤️