内容
<div align="center">
<img src="https://raw.githubusercontent.com/cygnussystems/cygnus-ssh-mcp/master/assets/banner.png" alt="cygnus-ssh-mcp" width="400">
# cygnus-ssh-mcp
**最强大的 SSH MCP 服务器，适用于 AI 助手**
[](https://pypi.org/project/cygnus-ssh-mcp/)
[](https://pypi.org/project/cygnus-ssh-mcp/)
[](https://www.gnu.org/licenses/gpl-3.0)
[]()
*赋予 Claude 对您的 Linux、macOS 和 Windows 服务器的完全控制权，拥有 43 种专用工具*
[安装](#installation) · [快速入门](#quick-start) · [功能](#features) · [文档](docs/)
</div>
---
## 为什么选择 cygnus-ssh-mcp？
大多数 SSH MCP 服务器允许您运行命令。**cygnus-ssh-mcp** 让您**管理服务器**。
| 您获得的功能 | 基本 SSH MCP | cygnus-ssh-mcp |
|--------------|:-------------:|:--------------:|
| 运行命令 | ✅ | ✅ |
| 预配置主机，带有别名 | ❌ | ✅ |
| Sudo 支持（Linux/macOS） | 有限 | ✅ |
| Windows Server 支持 | ❌ | ✅ |
| 后台任务管理 | ❌ | ✅ |
| 行级文件编辑 | ❌ | ✅ |
| 带有输出的命令历史记录 | ❌ | ✅ |
| 递归目录操作 | ❌ | ✅ |
| 存档创建/提取 | ❌ | ✅ |
| 完整的 Unicode 支持 | ? | ✅ |
---
## 安装
```bash
pip install cygnus-ssh-mcp
```
或使用 [uvx](https://docs.astral.sh/uv/) 运行而无需安装：
```bash
uvx cygnus-ssh-mcp
```
---
## 快速入门
### 1. 创建您的主机文件
创建 `~/.mcp_ssh_hosts.toml`：
```toml
# 最小（密码认证）- 仅需填写必填字段
["user@server.example.com"]
password = "your_password"
port = 22
# 带有别名和 sudo（最常见的设置）
["admin@production.example.com"]
password = "your_password"
port = 22
sudo_password = "sudo_pass" # 可选：用于 use_sudo 操作
alias = "prod" # 可选：通过别名连接
description = "生产服务器" # 可选：用于文档
# SSH 密钥认证
["deploy@staging.example.com"]
keyfile = "~/.ssh/id_ed25519"
port = 22
alias = "staging"
# Windows Server（需要 OpenSSH）
["administrator@winserver.example.com"]
password = "your_password"
port = 22
alias = "win-prod"
```
**必填字段：** `port` + (`password` 或 `keyfile`)
**可选字段：** `alias`、`description`、`sudo_password`、`key_passphrase`
> **主机文件位置：** 默认位置为 `~/.mcp_ssh_hosts.toml`。如果未找到，则回退到 `./mcp_ssh_hosts.toml`。
> 使用 `--config /path/to/hosts.toml` 自定义位置。
### 2. 添加到 Claude Desktop
编辑您的 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"ssh": {
"command": "cygnus-ssh-mcp"
}
}
}
```
或使用自定义主机文件位置：
```json
{
"mcpServers": {
"ssh": {
"command": "cygnus-ssh-mcp",
"args": ["--config", "/path/to/my_hosts.toml"]
}
}
}
```
### 3. 开始管理服务器
在 Claude 中，只需说：
> "连接到 prod 并显示磁盘使用情况"
> "编辑 /etc/nginx/nginx.conf 并将 worker_connections 更改为 2048"
> "在 /var/log 中查找所有大于 100MB 的 .log 文件"
---
## 平台支持
cygnus-ssh-mcp 从**任何客户端**（Windows、Linux、macOS）到**任何目标服务器**：
<div align="center">
<img src="https://raw.githubusercontent.com/cygnussystems/cygnus-ssh-mcp/master/assets/ssh_mcp_platforms.png" alt="平台支持" width="600">
</div>
| 来源（客户端） | 目标（服务器） | 状态 |
|---------------|-------------|--------|
| Windows | Linux | ✅ 已测试 |
| Windows | Windows | ✅ 已测试 |
| Linux | Linux | ✅ 已测试 |
| Linux | Windows | ✅ 已测试 |
| macOS | 任意 | ✅ 支持 |
**Windows 目标** 需要安装并运行 OpenSSH 服务器。
---
## 功能
### 主机配置
停止输入凭证。通过别名连接。
```toml
["admin@server.com"]
password = "secret"
port = 22
alias = "web"
```
然后直接： *"连接到 web"*
支持 **密码**、**SSH 密钥** 和 **带有口令的加密密钥**。
---
### 行级文件编辑
精确编辑配置文件 - 无需下载/上传。
```python
# 替换一行
ssh_file_replace_line(
file_path="/etc/nginx/nginx.conf",
match_line="worker_connections 1024;",
new_line="worker_connections 4096;"
)
# 在匹配后插入行
ssh_file_insert_lines_after_match(
file_path="/etc/hosts",
match_line="# 自定义条目",
lines_to_insert=["192.168.1.10 app.local", "192.168.1.11 db.local"]
)
```
**内置安全机制：** 操作失败如果匹配不唯一 - 无意外批量编辑。
---
### 后台任务管理
启动长时间运行的进程并稍后检查。
```python
# 启动备份（立即返回）
ssh_task_launch(command="./backup.sh", stdout_log="/var/log/backup.log")
# 随时检查状态
ssh_task_status(pid=12345) # → 'running' 或 'exited'
# 如有需要，终止
ssh_task_kill(pid=12345, force=True)
```
---
### 全面的 Sudo 支持
每个工具都支持 `use_sudo`。密码会自动处理。
```python
ssh_file_write(path="/etc/app/config.yaml", content="...", use_sudo=True)
ssh_dir_mkdir(path="/opt/myapp", use_sudo=True)
ssh_archive_extract(archive="/backup.tar.gz", dest="/", use_sudo=True)
```
---
### 双重超时系统
从未卡在挂起的命令上。
```python
ssh_cmd_run(
command="./long_script.sh",
io_timeout=60.0, # 如果 60 秒内无输出，则终止
runtime_timeout=3600.0 # 如果总时间超过 1 小时，则终止
)
```
---
### 完整的 Unicode 支持
写入和读取带有表情符号、国际文本和特殊字符的文件 - 在**所有平台**上。
```
✅ ❌ 🎉 • → ≥ ∞ │ ┌ ─ 你好 مرحبا Привет café naïve
```
**工作原理：** `ssh_file_read` 和 `ssh_file_write` 使用 SFTP 进行直接二进制传输，完全绕过 shell 编码问题。这意味着即使在 PowerShell 控制台编码通常会损坏特殊字符的 Windows 目标上，Unicode 也能完美工作。
---
### Windows Server 支持
对带有 OpenSSH 服务器的 Windows 目标提供全面支持：
- **PowerShell 和 CMD** 命令执行
- **Windows 路径处理**（反斜杠、驱动器号、UNC 路径）
- **管理员检测** - 显示会话是否具有提升的权限
- **基于 SFTP 的文件操作** - Unicode 安全，无编码问题
注意：`use_sudo` 在 Windows 上被忽略（无 sudo 等价）。对于提升的操作，请使用管理员帐户连接。
---
### 还有更多...
- **命令历史记录**，带有输出保留和模式过滤
- **递归目录操作**：搜索、复制、删除，带有 dry-run
- **存档操作**：创建和提取 tar.gz
- **系统信息**：OS 版本、内存、磁盘、CPU、运行时间
- **模式搜索**：文件中的正则表达式和纯文本
---
## 所有 43 种工具
### 连接和主机管理（10 种工具）
| 工具 | 描述 |
|------|-------------|
| `ssh_conn_connect` | 使用预配置的主机（通过密钥或别名）连接 |
| `ssh_conn_is_connected` | 检查 SSH 连接是否活动 |
| `ssh_conn_status` | 获取连接状态（用户、主机、OS、cwd） |
| `ssh_conn_host_info` | 获取详细的系统信息 |
| `ssh_conn_verify_sudo` | 验证 sudo 访问权限 |
| `ssh_conn_add_host` | 将新主机添加到配置中 |
| `ssh_host_list` | 列出所有配置的主机 |
| `ssh_host_remove` | 从配置中删除主机 |
| `ssh_host_disconnect` | 断开当前会话 |
| `list_tools` | 列出所有可用的工具 |
### 命令执行（6 种工具）
| 工具 | 描述 |
|------|-------------|
| `ssh_cmd_run` | 执行带有 I/O 和运行时超时的命令 |
| `ssh_cmd_kill` | 终止正在运行的命令 |
| `ssh_cmd_check_status` | 检查命令状态 |
| `ssh_cmd_output` | 检索命令输出 |
| `ssh_cmd_history` | 获取带有过滤的命令历史记录 |
| `ssh_cmd_clear_history` | 清除命令历史记录 |
### 后台任务（3 种工具）
| 工具 | 描述 |
|------|-------------|
| `ssh_task_launch` | 在后台启动命令 |
| `ssh_task_status` | 检查任务是否正在运行 |
| `ssh_task_kill` | 向任务发送信号 |
### 文件操作（12 种工具）
| 工具 | 描述 |
|------|-------------|
| `ssh_file_stat` | 获取文件元数据 |
| `ssh_file_read` | 通过 SFTP 读取文件内容（Unicode 安全） |
| `ssh_file_write` | 创建/覆盖/追加文件 |
| `ssh_file_copy` | 复制文件 |
| `ssh_file_move` | 移动或重命名文件 |
| `ssh_file_transfer` | 上传或下载文件 |
| `ssh_file_find_lines_with_pattern` | 在文件中搜索模式 |
| `ssh_file_get_context_around_line` | 获取匹配周围的上下文 |
| `ssh_file_replace_line` | 替换单行 |
| `ssh_file_replace_line_multi` | 替换多行 |
| `ssh_file_insert_lines_after_match` | 在匹配后插入行 |
| `ssh_file_delete_line_by_content` | 按内容删除行 |
### 目录操作（10 种工具）
| 工具 | 描述 |
|------|-------------|
| `ssh_dir_mkdir` | 创建目录 |
| `ssh_dir_remove` | 删除目录 |
| `ssh_dir_list_files_basic` | 基本目录列表 |
| `ssh_dir_list_advanced` | 带有元数据的递归列表 |
| `ssh_dir_search_glob` | 按模式搜索文件 |
| `ssh_dir_search_files_content` | 在文件中搜索文本 |
| `ssh_dir_calc_size` | 计算目录大小 |
| `ssh_dir_delete` | 删除，带有 dry-run 支持 |
| `ssh_dir_batch_delete_files` | 按模式批量删除 |
| `ssh_dir_copy` | 递归复制目录 |
### 存档操作（2 种工具）
| 工具 | 描述 |
|------|-------------|
| `ssh_archive_create` | 创建 tar.gz 存档 |
| `ssh_archive_extract` | 提取存档 |
---
## 文档
在 [docs/](docs/) 中提供详细指南：
- [概述](docs/10-overview.md)
- [安装](docs/15-installation.md)
- [平台兼容性](docs/20-platform-compatibility.md)
- [Windows 支持](docs/25-windows-support.md)
- [主机配置](docs/30-host-configuration.md)
- [工具参考](docs/40-tools-reference.md)
- [命令执行](docs/50-command-execution.md)
- [进程管理](docs/60-process-management.md)
- [日志记录](docs/70-logging.md)
- [Claude Desktop 设置](docs/80-claude-desktop.md)
---
## 用例
- **DevOps 自动化** - 通过 AI 部署、配置和管理服务器
- **日志分析** - 跨多个服务器搜索和分析日志
- **配置管理** - 精确编辑配置文件
- **备份和恢复** - 创建存档、传输文件、恢复备份
- **系统监控** - 检查状态、验证服务、监控进程
- **安全审计** - 搜索敏感模式、验证配置
---
## 许可证
[GPL-3.0](LICENSE) - 免费且开源。
---
<div align="center">
**由 [Cygnus Systems](https://github.com/cygnussystems) 构建**
*如果您觉得此项目有帮助，请给这个仓库点赞！*
</div>
