SSH LICCO MCP Server

🚀 SSH LICCO

让 AI 帮你操作服务器！ 通过自然语言对话，AI 可以帮你执行命令、管理文件、查看日志、部署应用等。

---

📚 文档导航

快速开始

• [🐣 新手指南](docs/BEGINNER_GUIDE.md) - 零基础上手（推荐从这开始）
• [⬇️ 安装指南](#-快速安装) - 2 种安装方式
• [🚀 快速开始](#-快速开始) - 5 分钟上手
• [📋 配置模板](#-完整配置示例) - 开箱即用的配置

核心功能

• [🔐 安全配置](#-安全配置) - 多级安全策略
• [🛠️ 可用工具](#-可用工具) - 完整功能列表
• [💡 使用示例](#-使用示例) - 实际应用场景

高级主题

• [📖 完整配置指南](MCP_CONFIG_GUIDE.md) - 所有配置选项详解
• [🔧 故障排除](docs/API_REFERENCE.md) - 常见问题解决
• [📊 API 参考](docs/API_REFERENCE.md) - 详细 API 文档

开发资源

• [🎓 Skills 文档](docs/skills/) - 开发、运维、安装指南
• [📦 发布指南](#-发布指南一体化命令) - 一体化版本发布命令
• [🐛 GitHub Issues](https://github.com/Echoqili/ssh-licco/issues) - 问题反馈

---

✨ 特性亮点

• 🎯 自然语言控制 - 用对话方式操作服务器
• 🔐 多种认证方式 - 密码、密钥、Agent 转发
• 🔗 长连接支持 - 自动保活（30 秒心跳），避免账户锁定
• ⏱️ 可配置超时 - Banner 超时 (60s)、会话超时 (2 小时)，支持自动重连
• 📦 异步高性能 - 基于 Paramiko 的异步架构（线程池 + asyncio）
• 🛡️ 完善的异常处理 - 统一的错误处理机制（7 层异常层次）
• 📊 会话管理 - 支持多个并发 SSH 会话（最大 10 个，每主机 3 个）
• 📁 SFTP 文件传输 - 上传、下载、目录管理
• 🖊️ 远程文件编辑 - 直接写入/追加文件内容，无需下载再上传
• 🔑 密钥管理 - 生成和管理 SSH 密钥对（RSA/Ed25519）
• 📝 审计日志 - 完整的操作审计记录（JSON 结构化日志）
• 🚀 连接池 - 高性能连接复用（PooledConnection + ConnectionPool）
• 📊 批量执行 - 多主机并行命令执行（BatchExecutor + AsyncBatchExecutor）
• 🐳 Docker 支持 - Docker 构建和状态监控
• 📋 后台任务 - 可靠的后台进程启动（nohup + bash -c 包装，单次 SSH 调用无竞态）
• 🖥️ screen/tmux 会话 - 持久化远程会话，SSH 断开后进程依然存活
• 🪟 Windows 服务器支持 - 支持 Windows Server（OpenSSH for Windows）与 Linux/macOS 目标主机
• 🔍 进程管理 - 启动/停止/查询远程进程、SSH 端口转发（tunnel）
• 🔍 看门狗 - 任务监控、心跳检测、全局异常处理
• 🛡️ 文件传输路径安全校验 - ssh_file_transfer delete 自动识别 Windows / Unix 路径风格并拦截敏感路径与路径遍历

---

🖥️ 目标主机支持

SSH-LICCO 基于标准 SSH/SFTP 协议，可连接以下目标主机：

提示：连接 Windows 服务器时，请使用 Windows 风格路径（如 C:\temp\file.txt），系统会自动识别并进行路径安全校验。

---

📦 快速安装

方式一：pip 安装（推荐）

pip install ssh-licco

方式二：从源码安装

git clone https://github.com/Echoqili/ssh-licco.git

cd ssh-licco pip install -e .

Python 版本要求： Python 3.10+

---

🚀 快速开始

1️⃣ 配置 MCP 服务器

在 Trae / Cursor / Claude Desktop 中使用

打开设置 → MCP → 添加新服务器：

{

"mcpServers": { "ssh": { "command": "python -m ssh_mcp.server" } } }

2️⃣ 配置 SSH 连接（可选但推荐）

方式 A：环境变量配置（推荐）

{

"mcpServers": { "ssh": { "command": "python -m ssh_mcp.server", "env": { "SSH_HOST": "192.168.1.100", "SSH_USER": "root", "SSH_PASSWORD": "your_password", "SSH_PORT": "22", "SSH_TIMEOUT": "60", "SSH_KEEPALIVE_INTERVAL": "30", "SSH_SESSION_TIMEOUT": "7200", "SSH_CLIENT_TYPE": "common" } } } }

环境变量说明：

• SSH_HOST: SSH 服务器地址
• SSH_USER: 用户名
• SSH_PASSWORD: 密码
• SSH_PORT: 端口（默认 22）
• SSH_TIMEOUT: 连接超时（秒）
• SSH_KEEPALIVE_INTERVAL: 保活间隔（秒）
• SSH_SESSION_TIMEOUT: 会话超时（秒）
• SSH_CLIENT_TYPE: SSH 客户端类型（可选，默认 common）
• common - paramiko（稳定可靠，推荐）⭐
• performance - asyncssh（高性能，适合高并发）🚀
• development - fabric（简化 API，适合快速开发）👨💻

---

🔐 安全配置

新增加固默认值与迁移说明见 [安全边界与加固配置](docs/SECURITY.md)： 连接默认验证主机密钥，确认参数不再绕过命令策略，文件传输执行目录隔离。 下表是项目的模式说明，不是第三方平台的安全评分。

重要：从 v0.2.1 开始，ssh-licco 提供多级安全策略，可根据使用场景灵活配置。

多级安全策略

快速配置

方式 1：环境变量（推荐）

Windows PowerShell:

$env:SSH_SECURITY_LEVEL = "balanced"

$env:SSH_EXTRA_ALLOWED_COMMANDS = "git,pip,npm"

Linux/Mac:

export SSH_SECURITY_LEVEL="balanced"

export SSH_EXTRA_ALLOWED_COMMANDS="git,pip,npm"

方式 2：MCP 配置文件

{

"mcpServers": { "ssh": { "command": "python -m ssh_mcp.server", "env": { "SSH_SECURITY_LEVEL": "balanced", "SSH_EXTRA_ALLOWED_COMMANDS": "git,pip,npm", "SSH_BASE_DIR": "/home" } } } }

📖 详细文档

• [MCP_CONFIG_GUIDE.md](MCP_CONFIG_GUIDE.md) - 完整配置指南，包含 5 种使用场景示例
• [SECURITY_CONFIG_GUIDE.md](SECURITY_CONFIG_GUIDE.md) - 安全配置详解

🛡️ 硬拦截灾难性命令（v2.2.0 新增）

为防止任何误操作或越权调用直接打到远程 shell，ssh-licco 在所有安全级别下都无条件拦截以下灾难性命令模式，无法通过 `confirm_dangerous=true`、`confirmation_layer=N`、调整 `SSH_SECURITY_LEVEL` 等任何方式绕过：

• rm -rf 作用于绝对路径（含 /、/*、/path、/path/*，-fr 变体同效）
• mkfs.* 任意文件系统格式化
• dd if=/dev/(zero|random|urandom) of=/dev/(sd|nvme) 覆写裸盘
• bash fork-bomb（:(){ :|:& };: 及空白变体）
• chmod -R 777 / / chmod -R 000 / 根目录递归改权限
• > /dev/(sd|nvme) / >> /dev/(sd|nvme) 裸设备重定向

如确需执行上述操作，请直接通过 SSH 登录服务器（绕过 MCP 网关）进行。安全且可逆的替代方案：

# 旧做法（v2.2.0 之前）：rm -rf /path/to/junk  ← 现已被硬拦截

推荐做法：mv 到回收站，约定时间后清理

mv /path/to/junk /tmp/.trash_$(date +%s)/

命中硬拦截时会输出 WARNING 审计日志（含 category 与命令），便于 SOC 监控。

---

🛠️ 可用工具（v2.2.0 维持 9 个；v2.1.0 曾增加的 3 个审批工具因流程闭环风险已下线）

关于 v2.1.0 引入的 3 个审批工具（ssh_request_approval / ssh_approve_command / ssh_list_approvals）：已从 MCP list_tools() 移除，代码已在 v2.2.0 删除（ssh_mcp/approval.py、ssh_mcp/handlers/approval.py）。审批流程依赖 AI 自报命令、运维侧背书，存在闭环风险；v2.2.0 的硬拦截更直接——灾难性命令在 MCP 网关层就被拒绝，运维侧不需要再走"先申请再审批"流程。

📖 详细文档

• [docs/API_REFERENCE.md](docs/API_REFERENCE.md) - 完整 API 参考
• [docs/skills/ssh-mcp-ops/SKILL.md](docs/skills/ssh-mcp-ops/SKILL.md) - 运维操作指南

---

💡 使用示例

示例 1：执行命令

用户：帮我查看服务器上的 Docker 容器

AI：调用 ssh_connect → ssh_execute "docker ps"

[执行结果] CONTAINER ID IMAGE COMMAND STATUS PORTS abc123 nginx "nginx" Up 2 days 80:80

示例 2：文件上传

用户：把这个文件上传到 /var/www/html

AI：调用 ssh_connect → ssh_file_transfer

[上传成功] 本地：./index.html 远程：/var/www/html/index.html 大小：2.3 KB

示例 3：Docker 构建（长任务）

用户：帮我构建 Docker 镜像

AI：调用 ssh_execute(background=True) 后台执行 docker build...

[后台任务已启动] Session ID: a1b2c3d4 命令：docker build -t myapp . 使用 ssh_execute(session_id="a1b2c3d4", command="cat /tmp/build.log") 查看进度

示例 4：数据库检查

用户：检查 PostgreSQL 是否正常运行

AI：调用 ssh_execute "pg_isready -h localhost -p 5432"

[检查结果] localhost:5432 - accepting connections ✅ PostgreSQL 运行正常

📖 更多示例

• [docs/skills/ssh-mcp-ops/SKILL.md](docs/skills/ssh-mcp-ops/SKILL.md) - 运维操作示例
• [docs/skills/ssh-mcp-dev/SKILL.md](docs/skills/ssh-mcp-dev/SKILL.md) - 开发场景示例

---

📋 完整配置示例

场景 1：Web 开发者

{

"mcpServers": { "ssh": { "command": "python -m ssh_mcp.server", "env": { "SSH_SECURITY_LEVEL": "balanced", "SSH_EXTRA_ALLOWED_COMMANDS": "git,npm,docker,composer,pm2", "SSH_BASE_DIR": "/var/www", "SSH_HOST": "192.168.1.100", "SSH_USER": "deploy", "SSH_PASSWORD": "your-password" } } } }

场景 2：Python 开发者

{

"mcpServers": { "ssh": { "command": "python -m ssh_mcp.server", "env": { "SSH_SECURITY_LEVEL": "balanced", "SSH_EXTRA_ALLOWED_COMMANDS": "pip,poetry,python3,pytest,black", "SSH_HOST": "192.168.1.100", "SSH_USER": "developer", "SSH_PASSWORD": "your-password" } } } }

场景 3：数据库管理员

{

"mcpServers": { "ssh": { "command": "python -m ssh_mcp.server", "env": { "SSH_SECURITY_LEVEL": "balanced", "SSH_EXTRA_ALLOWED_COMMANDS": "psql,mysql,mongosh,pg_isready", "SSH_HOST": "192.168.1.100", "SSH_USER": "dbadmin", "SSH_PASSWORD": "your-password" } } } }

场景 4：系统管理员

{

"mcpServers": { "ssh": { "command": "python -m ssh_mcp.server", "env": { "SSH_SECURITY_LEVEL": "relaxed", "SSH_EXTRA_ALLOWED_COMMANDS": "sudo,apt,yum,systemctl,journalctl,docker,kubectl", "SSH_HOST": "192.168.1.100", "SSH_USER": "root", "SSH_PASSWORD": "your-password" } } } }

场景 5：生产环境（最高安全）

{

"mcpServers": { "ssh": { "command": "python -m ssh_mcp.server", "env": { "SSH_SECURITY_LEVEL": "strict", "SSH_HOST": "192.168.1.100", "SSH_USER": "app-user", "SSH_PASSWORD": "your-password", "SSH_BASE_DIR": "/home/app-user" } } } }

📖 更多配置

• [MCP_CONFIG_GUIDE.md](MCP_CONFIG_GUIDE.md) - 包含所有配置选项的详细说明

🌐 完整环境变量速查（v2.3.0）

下表所有变量均被代码读取。注意：

- SSH_RATE_LIMIT 是 bool 总开关（true/false），SSH_RATE_LIMIT_MAX 才是次数上限，两者分开配置

- 主机密钥检查（strict_host_key_checking）不通过 env 配置，请用 ssh_connect 工具参数或 hosts.json

---

⚠️ 依赖版本兼容性

已知依赖冲突

以下依赖版本冲突已在测试环境中验证，不影响 ssh-licco 的正常使用：

1. starlette 版本冲突

fastapi 需要 starlette<0.51.0

但安装了 starlette 0.52.1

影响范围：

• ✅ ssh-licco: 无影响，正常工作
• ⚠️ fastapi: 可能存在兼容性问题（如果同时使用 fastapi）

解决方案：

• 如果只使用 ssh-licco，可以忽略此警告
• 如果同时使用 fastapi，建议：

  pip install starlette==0.50.0

2. cryptography 版本冲突

pyopenssl 需要 cryptography<45

但安装了 cryptography 46.0.5

影响范围：

• ✅ ssh-licco: 无影响，正常工作
• ⚠️ pyopenssl: 可能存在兼容性问题（如果同时使用 pyopenssl）

解决方案：

• 如果只使用 ssh-licco，可以忽略此警告
• 如果同时使用 pyopenssl，建议：

  pip install cryptography==44.0.0

测试环境

测试通过的配置：

• ✅ starlette 0.52.1 + ssh-licco 0.4.1
• ✅ cryptography 46.0.5 + ssh-licco 0.4.1
• ✅ mcp 1.26.0 + ssh-licco 0.4.1

测试场景：

• ✅ SSH 连接和执行命令
• ✅ 文件上传和下载
• ✅ 后台任务执行
• ✅ Docker 构建和监控
• ✅ 多语言后台命令自动检测

为什么允许这些冲突？

ssh-licco 的核心依赖是：

• mcp - MCP 协议实现
• asyncssh - SSH 客户端
• paramiko - SSH 客户端（稳