ssh-licco 0.1.1

SSH Model Context Protocol Server - Enable SSH functionality for AI models

🚀 SSH LICCO

让 AI 帮你操作服务器！

SSH LICCO 是一个基于 Model Context Protocol (MCP) 的 SSH 服务器，让 AI 助手（Trae、Cursor、Claude Desktop 等）能够直接连接和管理你的 SSH 服务器。通过自然语言对话，AI 可以帮你执行命令、管理文件、查看日志、部署应用等。

✨ 核心特性

• 🎯 自然语言控制 - 直接用对话方式操作服务器
• 🔐 多种认证方式 - 支持密码、密钥、Agent 转发
• 🔗 长连接支持 - 自动保活，避免频繁连接导致账户锁定
• 📦 多客户端支持 - Paramiko、Fabric、AsyncSSH 可插拔
• 🛡️ 完善的异常处理 - 统一的异常体系和错误处理
• 📊 会话管理 - 支持多个并发 SSH 会话
• 📁 SFTP 文件传输 - 上传、下载、列出目录
• 🔑 密钥管理 - 生成、保存和管理 SSH 密钥对
• 📝 详细日志记录 - 支持多级日志和文件输出
• 🚀 高性能异步 - 基于 asyncio 的异步架构
• 🔌 连接池 - 高性能连接复用
• 📊 批量执行 - 多主机并行命令执行
• 📝 审计日志 - 完整操作审计记录

技术栈

• Python 3.10 - 3.13
• MCP SDK 1.0+
• AsyncSSH 2.17.0+
• Pydantic 2.0+
• asyncio 异步架构

📦 安装

方式一：pip 安装（推荐）

pip install ssh-licco

方式二：从源码安装

git clone https://github.com/Echoqili/ssh-licco.git
cd ssh-licco
pip install -e .

开发环境安装

git clone https://github.com/Echoqili/ssh-licco.git
cd ssh-licco
pip install -e ".[dev]"

Python 版本要求：

• ✅ Python 3.10, 3.11, 3.12, 3.13
• ❌ Python 3.9 及以下版本不支持
• ❌ Python 3.14 及以上版本未测试

🚀 快速开始

1. 配置 MCP 服务器

在 Trae / Cursor 中使用

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

{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco"
    }
  }
}

在 Claude Desktop 中使用

配置文件位置：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco"
    }
  }
}

2. 配置 SSH 主机（可选但推荐）

方式 1：使用配置文件

cp config/hosts.json.example config/hosts.json

编辑 config/hosts.json：

{
  "ssh_hosts": [
    {
      "name": "生产服务器",
      "host": "192.168.1.100",
      "port": 22,
      "username": "root",
      "password": "your_password",
      "timeout": 30
    },
    {
      "name": "测试服务器",
      "host": "192.168.1.101",
      "port": 2222,
      "username": "admin",
      "password": "test123"
    }
  ]
}

方式 2：直接在 MCP 配置中指定

{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco",
      "env": {
        "SSH_HOST": "192.168.1.100",
        "SSH_USER": "root",
        "SSH_PASSWORD": "your_password",
        "SSH_KEEPALIVE_INTERVAL": "30",
        "SSH_SESSION_TIMEOUT": "7200",
        "SSH_CLIENT_TYPE": "asyncssh"
      }
    }
  }
}

3. 开始使用

重启 AI 应用后，直接用自然语言对话：

示例 1：查看服务器状态

帮我看看服务器的负载情况

示例 2：执行命令

在服务器上执行 docker ps 查看运行中的容器

示例 3：管理文件

列出 /var/log 目录下的所有文件

示例 4：安装软件

在服务器上安装 nginx

示例 5：上传文件

把本地的 config.yaml 上传到服务器的 /etc 目录

🔥 长连接功能（避免账户锁定）

频繁连接 SSH 服务器可能导致账户被锁定。SSH LICCO 默认启用长连接和自动保活：

• 自动保活：每 30 秒发送心跳包，保持连接活跃
• 持久会话：默认保持 2 小时，避免频繁重连
• 可配置：根据需求调整保活间隔和会话时长

配置参数

{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco",
      "env": {
        "SSH_HOST": "43.143.207.242",
        "SSH_USER": "root",
        "SSH_PASSWORD": "your-password",
        "SSH_KEEPALIVE_INTERVAL": "30",
        "SSH_SESSION_TIMEOUT": "7200"
      }
    }
  }
}

🔌 连接池（高性能）

SSH LICCO 支持连接池功能，提供高效的连接复用：

• 连接复用：避免频繁建立连接的开销
• 健康检查：自动检测并回收无效连接
• 线程安全：支持并发访问
• 配置灵活：可调整最大连接数、空闲时间等

连接池配置

from ssh_mcp import ConnectionConfig, PoolConfig, ConnectionPool

# 配置连接池
pool_config = PoolConfig(
    min_size=1,           # 最小连接数
    max_size=10,          # 最大连接数
    max_idle_time=300,    # 最大空闲时间（秒）
    max_use_count=100,   # 单连接最大使用次数
    acquire_timeout=30    # 获取连接超时（秒）
)

# 创建连接池
config = ConnectionConfig(
    host="192.168.1.100",
    username="admin",
    private_key_path="~/.ssh/id_rsa"
)
pool = ConnectionPool(config, pool_config)
pool.initialize()

# 使用连接池
with pool.acquire() as client:
    result = client.execute_command("ls -la")

📊 批量执行（多主机管理）

支持批量并行执行命令，管理多台服务器：

• 并行执行：多主机同时执行命令
• 失败隔离：单主机异常不影响其他主机
• 进度回调：实时反馈执行进度
• 异步支持：AsyncBatchExecutor 实现高并发

批量执行示例

from ssh_mcp import (
    ConnectionConfig, 
    BatchExecutor, 
    AsyncBatchExecutor
)

# 配置多台主机
hosts = [
    ConnectionConfig(host="192.168.1.100", username="admin", private_key_path="~/.ssh/id_rsa"),
    ConnectionConfig(host="192.168.1.101", username="admin", private_key_path="~/.ssh/id_rsa"),
    ConnectionConfig(host="192.168.1.102", username="admin", private_key_path="~/.ssh/id_rsa"),
]

# 同步批量执行
executor = BatchExecutor(hosts, max_workers=10)
result = executor.execute("uptime")

print(f"成功: {result.success_count}, 失败: {result.failed_count}")
for host_result in result.results:
    print(f"{host_result.host}: {host_result.stdout}")

# 异步批量执行
async_executor = AsyncBatchExecutor(hosts, max_concurrent=50)
result = await async_executor.execute("df -h")

📝 审计日志

完整的操作审计日志，满足合规要求：

• 结构化日志：JSON 格式便于分析
• 操作记录：连接、执行命令、文件传输
• 认证审计：成功/失败认证记录

使用审计日志

from ssh_mcp import get_audit_logger, AuditEventType

# 初始化审计日志
audit = get_audit_logger("logs/audit.log")

# 记录连接事件
audit.log_connect(
    username="admin",
    host="192.168.1.100",
    port=22,
    client_type="asyncssh",
    session_id="session-123"
)

# 记录命令执行
audit.log_command(
    username="admin",
    host="192.168.1.100",
    command="ls -la",
    return_code=0,
    stdout_length=1024,
    stderr_length=0,
    session_id="session-123"
)

详细配置说明见 CONFIG_GUIDE.md

🛠️ 可用工具

工具	说明	示例
ssh_config	配置 SSH 连接信息	配置服务器地址、用户名、密码
ssh_login	使用保存的配置登录	登录后执行命令
ssh_connect	直接连接 SSH	支持预配置主机或即时连接
ssh_execute	执行命令	在会话中执行任意命令
ssh_disconnect	断开连接	关闭指定会话
ssh_list_sessions	列出活跃会话	查看所有 SSH 会话
ssh_generate_key	生成 SSH 密钥	创建 RSA 或 ED25519 密钥对
ssh_file_transfer	SFTP 文件传输	上传、下载、列出目录

详细使用说明见 USAGE.md

🏗️ 架构设计

SSH LICCO 采用分层架构设计，遵循最佳实践：

核心模块

ssh_mcp/
├── clients/              # SSH 客户端层（可插拔）
│   ├── interface.py     # 抽象接口定义
│   ├── paramiko_client.py  # Paramiko 实现
│   ├── additional_clients.py # 其他客户端实现
│   └── factory.py       # 客户端工厂
├── service.py           # 业务服务层
├── session_manager.py   # 会话管理
├── connection_config.py # 配置模型
├── connection_pool.py  # 连接池管理
├── batch_executor.py   # 批量执行器
├── audit_logger.py     # 审计日志
├── exceptions.py        # 统一异常体系
├── logging_config.py    # 日志管理
└── server.py           # MCP 服务端

设计模式

• 工厂模式：SSHClientFactory 动态创建客户端
• 策略模式：支持多种 SSH 客户端实现
• 单例模式：全局 SSHService 实例
• 上下文管理器：自动连接/断开管理

客户端支持

当前仅支持 AsyncSSH 客户端：

客户端	类型	特点	安装
AsyncSSH	异步	高并发性能，异步架构，默认且唯一	pip install asyncssh

说明： 为了简化维护和优化性能，本项目目前仅支持 AsyncSSH 客户端。AsyncSSH 提供：

• ✅ 异步架构，高并发性能
• ✅ 低资源占用
• ✅ 现代化的 API 设计
• ✅ 活跃的社区支持

配置客户端类型

当前默认且仅支持 AsyncSSH 客户端，无需额外配置。

如需指定（兼容性）：

{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco",
      "env": {
        "SSH_CLIENT_TYPE": "asyncssh"
      }
    }
  }
}

详见 🔌 客户端类型配置指南

🔒 安全注意事项

⚠️ 重要提示：

1. 密码安全 - 密码仅本地存储，建议使用后清除配置文件
2. 不要分享 - 不要在公开场合分享服务器密码
3. 密钥认证 - 优先使用 SSH 密钥认证而非密码
4. 普通用户 - 尽量使用普通用户而非 root 用户
5. 文件权限 - 确保 config/hosts.json 文件权限设置为 600
6. 环境变量 - 使用环境变量存储敏感信息更安全

📚 文档

• 📖 使用指南 - 详细的工具使用说明
• ⚙️ 配置指南 - 完整的配置选项说明
• 🐳 Docker 超时问题 - Docker 构建相关问题
• 📝 API 参考 - API 接口文档
• ❓ 故障排除 - 常见问题和解决方案

💻 开发

运行测试

pytest

代码检查

# 代码格式化
ruff check ssh_mcp

# 类型检查
mypy ssh_mcp

构建文档

cd docs
mkdocs build

🤝 贡献

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

详见 CONTRIBUTING.md

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🙏 致谢

• MCP SDK - Model Context Protocol
• Paramiko - SSH 库
• Fabric - 高级 SSH 库
• AsyncSSH - 异步 SSH 库

📬 联系方式

• 项目地址: https://github.com/Echoqili/ssh-licco
• 问题反馈: https://github.com/Echoqili/ssh-licco/issues
• PyPI: https://pypi.org/project/ssh-licco/

---

Made with ❤️ by SSH LICCO Team