SSH LICCO MCP Server

🚀 SSH LICCO

AI にサーバー操作を任せましょう！ 自然言語で会話するだけで、AI がコマンドの実行、ファイルの管理、ログの確認、アプリケーションのデプロイなどを支援します。

---

📚 ドキュメント案内

クイックスタート

• 🐣 初心者向けガイド - 基礎知識がなくても始められます（ここから始めるのがおすすめです）
• ⬇️ インストールガイド - 2 種類のインストール方法
• 🚀 クイックスタート - 5 分で使い始められます
• 📋 設定テンプレート - すぐに使える設定

主な機能

• 🔐 セキュリティ設定 - 多段階のセキュリティポリシー
• 🛠️ 利用可能なツール - 全機能の一覧
• 💡 使用例 - 実際の利用シナリオ

高度なトピック

• 📖 完全な設定ガイド - すべての設定オプションの詳細
• 🔧 トラブルシューティング - よくある問題の解決方法
• 📊 API リファレンス - API の詳細ドキュメント

開発リソース

• 🎓 Skills ドキュメント - 開発、運用、インストールのガイド
• 📦 リリースガイド - 統合バージョンリリースコマンド
• 🐛 GitHub Issues - 問題の報告

---

✨ 主な特長

• 🎯 自然言語による操作 - 会話形式でサーバーを操作
• 🔐 複数の認証方式 - パスワード、鍵、エージェント転送
• 🔗 長時間接続に対応 - 自動キープアライブ（30 秒間隔のハートビート）でアカウントのロックを防止
• ⏱️ タイムアウトを設定可能 - バナーのタイムアウト（60 秒）、セッションのタイムアウト（2 時間）に対応し、自動再接続も可能
• 📦 高性能な非同期処理 - Paramiko に基づく非同期アーキテクチャ（スレッドプール + asyncio）
• 🛡️ 充実した例外処理 - 統一されたエラー処理機構（7 層の例外階層）
• 📊 セッション管理 - 複数の SSH セッションを同時に利用可能（最大 10 件、1 ホストあたり 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 ポート転送（トンネル）
• 🔍 ウォッチドッグ - タスク監視、ハートビート検出、グローバル例外処理
• 🛡️ ファイル転送パスの安全性検証 - ssh_file_transfer の delete では Windows／Unix のパス形式を自動判別し、機密性の高いパスとパストラバーサルを遮断

---

🖥️ ターゲットホストの対応状況

SSH-LICCO は標準の SSH/SFTP プロトコルに基づいており、以下のターゲットホストに接続できます。

OS	要件	備考
Linux	OpenSSH 7.0+	推奨。すべての機能に完全対応
Windows Server	OpenSSH for Windows / PowerShell Remoting over SSH	v2.1.3+ では Windows のパス形式と安全性検証に対応
macOS	システム標準の OpenSSH	完全対応

ヒント：Windows サーバーに接続する場合は、Windows 形式のパス（例：C:\temp\file.txt）を使用してください。システムが自動的に形式を判別し、パスの安全性を検証します。

---

📦 クイックインストール

方法 1：pip でインストール（推奨）

pip install ssh-licco

方法 2：ソースからインストール

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 で、迅速な開発に適しています）👨‍💻

---

🔐 セキュリティ設定

新しい強化済みデフォルト値と移行に関する説明は、セキュリティ境界と強化設定 をご覧ください。 接続時にはデフォルトでホスト鍵が検証され、確認パラメーターによるコマンドポリシーの回避はできなくなりました。また、ファイル転送の実行ディレクトリは分離されています。 以下の表はプロジェクトのモードを説明するものであり、サードパーティープラットフォームのセキュリティ評価ではありません。

重要：v0.2.1 以降、ssh-licco では複数段階のセキュリティポリシーを利用でき、用途に応じて柔軟に設定できます。

複数段階のセキュリティポリシー

レベル	名称	用途	保護強度
STRICT	厳格モード	本番環境、パブリックサーバー	最高 ⭐⭐⭐
BALANCED	バランスモード	開発環境、個人用サーバー（デフォルト）	高 ⭐⭐
RELAXED	緩和モード	テスト環境、完全に信頼できるサーバー	中 ⭐

クイック設定

方法 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 - 5 種類の利用シナリオ例を含む、完全な設定ガイド
• 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 个审批工具因流程闭环风险已下线）

工具	描述	核心能力
ssh_connect	连接管理	自动读取环境变量/配置，支持密码+密钥认证，可保存配置，登录后自动执行命令
ssh_execute	命令执行	自动连接、智能后台检测、长任务等待、超时控制，支持 nohup/screen/tmux 三种后台模式；v2.2.0 起对灾难性命令（rm -rf 绝对路径、mkfs、raw-disk dd、fork-bomb 等）做无条件硬拦截
ssh_disconnect	会话管理	断开指定会话 OR 列出所有活跃会话
ssh_file_transfer	文件传输	上传/下载/列表/写入/追加/删除/创建目录/查看元信息（8 种操作）；v2.1.3+ delete 操作新增 Windows/Unix 敏感路径拦截与路径遍历防护
ssh_host	主机管理	action=list/add/remove 增删查主机配置
ssh_docker	Docker 管理	action=ps/images/build/logs 全生命周期管理
ssh_generate_key	密钥生成	RSA / Ed25519 密钥对
ssh_session	screen/tmux 会话	持久化远程会话管理（create/send/capture/list/kill），SSH 断开后进程依然存活
ssh_process	进程管理	启动/停止/查询远程进程，SSH 端口转发（tunnel_open/tunnel_close/tunnel_list）

关于 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 - 完整 API 参考
• 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-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 - 包含所有配置选项的详细说明

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

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

• SSH_RATE_LIMIT 是 bool 总开关（true/false），SSH_RATE_LIMIT_MAX 才是次数上限，两者分开配置
• 主机密钥检查（strict_host_key_checking）不通过 env 配置，请用 ssh_connect 工具参数或 hosts.json

分类	变量	默认	说明
安全	SSH_SECURITY_LEVEL	balanced	安全级别：strict / balanced / relaxed
	SSH_BASE_DIR	/home	Unix 远程 SFTP 路径校验基目录
	SSH_LOCAL_BASE_DIR	当前工作目录	本地文件上传源与下载目标的允许目录
	SSH_EXTRA_ALLOWED_COMMANDS	(空)	额外允许的命令（逗号分隔）
	SSH_ALLOWED_COMMANDS_FILE	(空)	命令白名单 JSON 文件路径
	SSH_AUDIT_LOG_PATH	(空)	审计日志文件路径
限流	SSH_RATE_LIMIT	true	限流总开关（bool）
	SSH_RATE_LIMIT_MAX	30	限流次数上限
	SSH_RATE_LIMIT_WINDOW	60	限流窗口（秒）
硬拦截	(无 env)	—	灾难性命令硬拦截，零配置零绕过
连接默认	SSH_HOST / SSH_PORT / SSH_USER / SSH_PASSWORD	127.0.0.1 / 22 / root / (空)	单 host 模式默认连接参数
	SSH_TIMEOUT	60	连接超时（秒）
	SSH_KEEPALIVE_INTERVAL	30	keepalive 间隔（秒）
	SSH_SESSION_TIMEOUT	7200	会话超时（秒）
	SSH_CLIENT_TYPE	paramiko	SSH 客户端实现：paramiko / asyncssh
	SSH_FORCE_ENV_CONFIG	false	强制 env 配置覆盖 hosts.json
	SSH_SUDO_PASSWORD	(空)	sudo 密码，配合 use_sudo=true 走 sudo -S

---

⚠️ 依赖版本兼容性

已知依赖冲突

以下依赖版本冲突已在测试环境中验证，不影响 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 客户端（稳定模式）
• pydantic - 数据验证

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

---

🔧 故障排查

常见问题

1. 连接失败

错误: Connection refused

解决:

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

2. 认证失败

错误: Authentication failed

解决:

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

3. 命令被阻止

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

解决:

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

📖 详细文档

• docs/API_REFERENCE.md - API 参考和错误处理
• docs/skills/ssh-mcp-troubleshoot/SKILL.md - 故障排除指南
• MCP_CONFIG_GUIDE.md - 配置故障排查

---

🎓 学习资源

Skills 文档

• 📦 发布指南 - 完整的版本发布流程
• 🔧 开发指南 - 开发环境和流程
• 🛠️ 运维指南 - 运维操作最佳实践
• ⚙️ 安装指南 - 安装和配置步骤
• 🔍 故障排除 - 常见问题解决

配置文档

• MCP_CONFIG_GUIDE.md - 完整配置指南
• SECURITY_CONFIG_GUIDE.md - 安全配置详解

API 文档

• docs/API_REFERENCE.md - API 参考文档

---

🔗 相关链接

项目资源

• GitHub: https://github.com/Echoqili/ssh-licco
• PyPI: https://pypi.org/project/ssh-licco/
• MCP Registry: https://registry.modelcontextprotocol.io/servers/io.github.Echoqili/ssh-licco
• Issues: https://github.com/Echoqili/ssh-licco/issues

文档索引

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

---

🧪 测试

测试状态

指标	状态
测试用例	311 passed, 0 skipped
覆盖率	16 个源模块全覆盖
测试框架	pytest + pytest-asyncio

测试模块覆盖

源模块	测试文件	用例数
exceptions.py	test_exceptions.py	7
connection_config.py	test_connection_config.py	8
security.py	test_security.py	24
logging_config.py	test_logging_config.py	8
audit_logger.py	test_audit_logger.py	12
executor.py	test_executor.py	8
watchdog.py	test_watchdog.py	18
key_manager.py	test_key_manager.py	6
config_manager.py	test_config_manager.py	10
clients/interface.py	test_factory.py	10
clients/paramiko_client.py	test_paramiko_client.py	18
clients/factory.py	test_factory.py	10
session_manager.py	test_session_manager.py	18
connection_pool.py	test_connection_pool.py	10
batch_executor.py	test_batch_executor.py	10
server.py	test_server.py	30+
service.py	test_service.py	14

运行测试

# 运行全部测试
pytest tests/ -v

# 运行特定模块测试
pytest tests/test_security.py -v

# 查看覆盖率
pytest --cov=ssh_mcp --cov-report=term-missing

---

📦 发布流程

先在独立分支同步版本并运行测试：

python sync_version.py 2.8.1 --no-commit --no-tag
python sync_version.py --check
python -m pytest tests -q
node --test tests/install.test.cjs

代码合并后推送 vX.Y.Z 标签，现有发布流程依次执行版本校验、测试、打包、 PyPI 上传、公开安装源码核验，再创建或补齐 GitHub Release。 不需要向 npm 注册表发布；Node 安装包通过 GitHub Release 下载。

支持手动只验证，以及针对原标签恢复中断的发布。网络查询失败时停止上传； 已有 PyPI 文件和 Release 安装包不会重复覆盖。 详细操作及凭据配置见 发布与失败恢复。

---

📊 版本历史