S
SkillNav

io.github.Echoqili/ssh-licco

编码与调试

by echoqili

SSH Model Context Protocol Server，可让 AI 助手连接 SSH 服务器、执行命令，并支持远程运维自动化。

2GitHub

什么是 io.github.Echoqili/ssh-licco？

SSH Model Context Protocol Server，可让 AI 助手连接 SSH 服务器、执行命令，并支持远程运维自动化。

README

🚀 SSH LICCO

<!-- mcp-name: io.github.Echoqili/ssh-licco -->

PyPI version Python 3.10-3.13 License: MIT MCP Registry

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

📚 文档导航

快速开始

核心功能

高级主题

开发资源

✨ 特性亮点

  • 🎯 自然语言控制 - 用对话方式操作服务器
  • 🔐 多种认证方式 - 密码、密钥、Agent 转发
  • 🔗 长连接支持 - 自动保活（30 秒心跳），避免账户锁定
  • ⏱️ 可配置超时 - Banner 超时 (60s)、会话超时 (2 小时)
  • 📦 异步高性能 - 基于 AsyncSSH 的异步架构
  • 🛡️ 完善的异常处理 - 统一的错误处理机制
  • 📊 会话管理 - 支持多个并发 SSH 会话
  • 📁 SFTP 文件传输 - 上传、下载、目录管理
  • 🔑 密钥管理 - 生成和管理 SSH 密钥对
  • 📝 审计日志 - 完整的操作审计记录
  • 🚀 连接池 - 高性能连接复用
  • 📊 批量执行 - 多主机并行命令执行
  • 🐳 Docker 支持 - Docker 构建和状态监控
  • 📋 后台任务 - 异步任务执行和状态跟踪

📦 快速安装

方式一：pip 安装（推荐）

bash
pip install ssh-licco

方式二：MCP 安装

bash
mcp install io.github.Echoqili/ssh-licco

方式三：从源码安装

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

Python 版本要求： Python 3.10, 3.11, 3.12, 3.13

⚠️ 依赖版本兼容性

已知依赖冲突

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

1. starlette 版本冲突

code
fastapi 需要 starlette<0.51.0
但安装了 starlette 0.52.1

影响范围：

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

解决方案：

  • 如果只使用 ssh-licco，可以忽略此警告
  • 如果同时使用 fastapi，建议：
    bash
    pip install starlette==0.50.0

2. cryptography 版本冲突

code
pyopenssl 需要 cryptography<45
但安装了 cryptography 46.0.5

影响范围：

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

解决方案：

  • 如果只使用 ssh-licco，可以忽略此警告
  • 如果同时使用 pyopenssl，建议：
    bash
    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 客户端
  • pydantic - 数据验证

而 starlette 和 cryptography 是通过 mcp 间接引入的。ssh-licco 本身不直接使用这些库的 API，因此版本冲突不会影响 ssh-licco 的功能。

🚀 快速开始

1️⃣ 配置 MCP 服务器

在 Trae / Cursor / Claude Desktop 中使用

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

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

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

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

json
{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco",
      "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，适合快速开发）👨‍💻

方式 B：交互式配置

启动后，系统会提示输入连接信息：

bash
python -m ssh_mcp.server

🔐 安全配置

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

多级安全策略

级别名称适用场景安全评分
STRICT严格模式生产环境、公共服务器最高 ⭐⭐⭐
BALANCED平衡模式开发环境、个人服务器（默认）高 ⭐⭐
RELAXED宽松模式测试环境、完全信任的服务器中等 ⭐

快速配置

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

Windows PowerShell:

powershell
$env:SSH_SECURITY_LEVEL = "balanced"
$env:SSH_EXTRA_ALLOWED_COMMANDS = "git,pip,npm"
python -m ssh_mcp.server

Linux/Mac:

bash
export SSH_SECURITY_LEVEL="balanced"
export SSH_EXTRA_ALLOWED_COMMANDS="git,pip,npm"
python -m ssh_mcp.server

方式 2：MCP 配置文件

json
{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco",
      "env": {
        "SSH_SECURITY_LEVEL": "balanced",
        "SSH_EXTRA_ALLOWED_COMMANDS": "git,pip,npm",
        "SSH_BASE_DIR": "/home"
      }
    }
  }
}

📖 详细文档

🛠️ 可用工具

SSH 连接管理

工具描述示例
ssh_connect建立 SSH 连接连接服务器
ssh_disconnect断开 SSH 连接释放连接资源
ssh_list_sessions查看活动会话管理多个连接

命令执行

工具描述示例
ssh_execute执行 SSH 命令ls -la, docker ps
ssh_background_task后台任务执行Docker 构建、长时间运行任务
ssh_task_status查看后台任务状态检查任务进度

文件管理

工具描述示例
ssh_upload_file上传文件部署代码
ssh_download_file下载文件获取日志
ssh_list_directory列出目录内容查看文件结构

系统管理

工具描述示例
ssh_get_info获取系统信息CPU、内存、磁盘
ssh_check_service检查服务状态PostgreSQL、Nginx
ssh_docker_buildDocker 构建构建镜像
ssh_docker_statusDocker 状态容器状态

📖 详细文档

💡 使用示例

示例 1：执行命令

code
用户：帮我查看服务器上的 Docker 容器
AI：正在执行 `docker ps` 命令...

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

示例 2：文件上传

code
用户：把这个文件上传到 /var/www/html
AI：正在上传文件到 /var/www/html...

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

示例 3：后台任务

code
用户：帮我构建 Docker 镜像
AI：正在启动后台任务执行 `docker build -t myapp .`...

[任务启动]
Task ID: a1b2c3d4
命令：docker build -t myapp .
日志：/tmp/background_task.log

使用 ssh_task_status 查看进度

示例 4：数据库检查

code
用户：检查 PostgreSQL 是否正常运行
AI：正在执行 `pg_isready -h localhost -p 5432`...

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

📖 更多示例

📋 完整配置示例

场景 1：Web 开发者

json
{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco",
      "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 开发者

json
{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco",
      "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：数据库管理员

json
{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco",
      "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：系统管理员

json
{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco",
      "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：生产环境（最高安全）

json
{
  "mcpServers": {
    "ssh": {
      "command": "ssh-licco",
      "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"
      }
    }
  }
}

📖 更多配置

🔧 故障排查

常见问题

1. 连接失败

错误: Connection refused

解决:

  • 检查 SSH 服务是否运行：systemctl status sshd
  • 检查防火墙设置：ufw status
  • 确认端口正确：默认 22

2. 认证失败

错误: Authentication failed

解决:

  • 检查用户名和密码
  • 尝试使用密钥认证
  • 查看 SSH 日志：/var/log/auth.log

3. 命令被阻止

错误: 命令 'xxx' 不在允许列表中

解决:

json
{
  "SSH_SECURITY_LEVEL": "balanced",
  "SSH_EXTRA_ALLOWED_COMMANDS": "被阻止的命令"
}

4. 后台任务失败

错误: 'SSHMCPServer' object has no attribute '_logger'

解决: 升级到最新版本 v0.2.3+

bash
pip install --upgrade ssh-licco

📖 详细文档

🎓 学习资源

Skills 文档

配置文档

API 文档

🔗 相关链接

项目资源

文档索引

文档描述位置
📖 配置指南完整配置选项和场景MCP_CONFIG_GUIDE.md
🔐 安全指南安全配置详解SECURITY_CONFIG_GUIDE.md
📊 API 参考完整 API 文档docs/API_REFERENCE.md
🎓 Skills开发、运维、安装指南docs/skills/
📦 发布指南版本发布流程docs/skills/RELEASE_SKILL.md

📊 版本历史

版本日期主要变更
v0.2.32026-03-14修复 _logger 初始化 bug
v0.2.22026-03-14安全配置增强（有 bug）
v0.2.12026-03-13多级安全策略、环境变量配置
v0.2.02026-03-12安全验证模块、命令白名单
v0.1.72026-03-11基础功能、后台任务

🤝 贡献指南

欢迎贡献代码、文档和建议！

开发流程

  1. Fork 项目
  2. 创建特性分支
  3. 提交变更
  4. 推送到分支
  5. 创建 Pull Request

开发资源

📄 许可证

MIT License - 详见 LICENSE

💬 获取帮助

遇到问题？

  1. 查看文档: MCP_CONFIG_GUIDE.md
  2. 故障排除: docs/skills/ssh-mcp-troubleshoot/SKILL.md
  3. 提交 Issue: GitHub Issues

社区支持

  • GitHub Discussions
  • MCP Community
  • Stack Overflow (tag: ssh-licco)

Made with ❤️ by Echoqili

Last updated: 2026-03-14

常见问题

io.github.Echoqili/ssh-licco 是什么？

SSH Model Context Protocol Server，可让 AI 助手连接 SSH 服务器、执行命令，并支持远程运维自动化。

相关 Skills

网页构建器

by anthropics

Universal
热门

面向复杂 claude.ai HTML artifact 开发，快速初始化 React + Tailwind CSS + shadcn/ui 项目并打包为单文件 HTML，适合需要状态管理、路由或多组件交互的页面。

✎ 在 claude.ai 里做复杂网页 Artifact 很省心，多组件、状态和路由都能顺手搭起来，React、Tailwind 与 shadcn/ui 组合效率高、成品也更精致。

编码与调试
未扫描114.1k

前端设计

by anthropics

Universal
热门

面向组件、页面、海报和 Web 应用开发，按鲜明视觉方向生成可直接落地的前端代码与高质感 UI，适合做 landing page、Dashboard 或美化现有界面，避开千篇一律的 AI 审美。

✎ 想把页面做得既能上线又有设计感，就用前端设计：组件到整站都能产出，难得的是能避开千篇一律的 AI 味。

编码与调试
未扫描114.1k

网页应用测试

by anthropics

Universal
热门

用 Playwright 为本地 Web 应用编写自动化测试，支持启动开发服务器、校验前端交互、排查 UI 异常、抓取截图与浏览器日志，适合调试动态页面和回归验证。

✎ 借助 Playwright 一站式验证本地 Web 应用前端功能，调 UI 时还能同步查看日志和截图，定位问题更快。

编码与调试
未扫描114.1k

相关 MCP Server

GitHub

编辑精选

by GitHub

热门

GitHub 是 MCP 官方参考服务器，让 Claude 直接读写你的代码仓库和 Issues。

✎ 这个参考服务器解决了开发者想让 AI 安全访问 GitHub 数据的问题，适合需要自动化代码审查或 Issue 管理的团队。但注意它只是参考实现，生产环境得自己加固安全。

编码与调试
83.4k

Context7 文档查询

编辑精选

by Context7

热门

Context7 是实时拉取最新文档和代码示例的智能助手，让你告别过时资料。

✎ 它能解决开发者查找文档时信息滞后的问题，特别适合快速上手新库或跟进更新。不过，依赖外部源可能导致偶尔的数据延迟，建议结合官方文档使用。

编码与调试
52.2k

io.github.tldraw/tldraw

编辑精选

by tldraw

热门

tldraw 是让 AI 助手直接在无限画布上绘图和协作的 MCP 服务器。

✎ 这解决了 AI 只能输出文本、无法视觉化协作的痛点——想象让 Claude 帮你画流程图或白板讨论。最适合需要快速原型设计或头脑风暴的开发者。不过，目前它只是个基础连接器，你得自己搭建画布应用才能发挥全部潜力。

编码与调试
46.3k

评论