Execute Composer commands on remote servers for PHP dependency management.
Manage Docker containers, images, builds, and logs on remote servers via SSH.
Execute Git commands on remote servers for version control operations.
Run MySQL queries and administration commands on remote servers.
Run npm commands on remote servers for package management and project tasks.
Manage Node.js processes with PM2 on remote servers.
Manage Python dependencies and projects with Poetry on remote servers.
Execute PostgreSQL commands and queries on remote servers.
Run Pytest test suites on remote servers for automated testing.
Create and manage persistent terminal sessions using tmux on remote servers.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ssh-licco Check the system uptime and memory usage on the production server."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
让 AI 帮你操作服务器！ 通过自然语言对话，AI 可以帮你执行命令、管理文件、查看日志、部署应用等。
🎓 Skills 文档 - 开发、运维、安装指南
📦 发布指南 - 一体化版本发布命令
🐛 GitHub Issues - 问题反馈
Related MCP server: remote-admin-mcp
🎯 自然语言控制 - 用对话方式操作服务器
🔐 多种认证方式 - 密码、密钥、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 协议，可连接以下目标主机：
操作系统 | 要求 | 备注 |
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），系统会自动识别并进行路径安全校验。
pip install ssh-liccogit clone https://github.com/Echoqili/ssh-licco.git
cd ssh-licco
pip install -e .Python 版本要求： Python 3.10+
打开设置 → MCP → 添加新服务器：
{
"mcpServers": {
"ssh": {
"command": "python -m ssh_mcp.server"
}
}
}{
"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 | 宽松模式 | 测试环境、完全信任的服务器 | 中等 ⭐ |
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"{
"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 - 安全配置详解
为防止任何误操作或越权调用直接打到远程 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 监控。
工具 | 描述 | 核心能力 |
| 连接管理 | 自动读取环境变量/配置，支持密码+密钥认证，可保存配置，登录后自动执行命令 |
| 命令执行 | 自动连接、智能后台检测、长任务等待、超时控制，支持 nohup/screen/tmux 三种后台模式；v2.2.0 起对灾难性命令（rm -rf 绝对路径、mkfs、raw-disk dd、fork-bomb 等）做无条件硬拦截 |
| 会话管理 | 断开指定会话 OR 列出所有活跃会话 |
| 文件传输 | 上传/下载/列表/写入/追加/删除/创建目录/查看元信息（8 种操作）；v2.1.3+ delete 操作新增 Windows/Unix 敏感路径拦截与路径遍历防护 |
| 主机管理 |
|
| Docker 管理 |
|
| 密钥生成 | RSA / Ed25519 密钥对 |
| screen/tmux 会话 | 持久化远程会话管理（create/send/capture/list/kill），SSH 断开后进程依然存活 |
| 进程管理 | 启动/停止/查询远程进程，SSH 端口转发（tunnel_open/tunnel_close/tunnel_list） |
关于 v2.1.0 引入的 3 个审批工具（
ssh_request_approval/ssh_approve_command/ssh_list_approvals）：已从 MCPlist_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 - 运维操作指南
用户：帮我查看服务器上的 Docker 容器
AI：调用 ssh_connect → ssh_execute "docker ps"
[执行结果]
CONTAINER ID IMAGE COMMAND STATUS PORTS
abc123 nginx "nginx" Up 2 days 80:80用户：把这个文件上传到 /var/www/html
AI：调用 ssh_connect → ssh_file_transfer
[上传成功]
本地：./index.html
远程：/var/www/html/index.html
大小：2.3 KB用户：帮我构建 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") 查看进度用户：检查 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 - 开发场景示例
{
"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"
}
}
}
}{
"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"
}
}
}
}{
"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"
}
}
}
}{
"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"
}
}
}
}{
"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 - 包含所有配置选项的详细说明
下表所有变量均被代码读取。注意：
SSH_RATE_LIMIT是 bool 总开关（true/false），SSH_RATE_LIMIT_MAX才是次数上限，两者分开配置主机密钥检查（strict_host_key_checking）不通过 env 配置，请用
ssh_connect工具参数或hosts.json
分类 | 变量 | 默认 | 说明 |
安全 |
|
| 安全级别： |
|
| 路径校验基目录 | |
| (空) | 额外允许的命令（逗号分隔） | |
| (空) | 命令白名单 JSON 文件路径 | |
| (空) | 审计日志文件路径 | |
限流 |
|
| 限流总开关（bool） |
|
| 限流次数上限 | |
|
| 限流窗口（秒） | |
硬拦截 | (无 env) | — | 灾难性命令硬拦截，零配置零绕过 |
连接默认 |
|
| 单 host 模式默认连接参数 |
|
| 连接超时（秒） | |
|
| keepalive 间隔（秒） | |
|
| 会话超时（秒） | |
|
| SSH 客户端实现： | |
|
| 强制 env 配置覆盖 hosts.json | |
| (空) | sudo 密码，配合 |
以下依赖版本冲突已在测试环境中验证，不影响 ssh-licco 的正常使用：
fastapi 需要 starlette<0.51.0
但安装了 starlette 0.52.1影响范围：
✅ ssh-licco: 无影响，正常工作
⚠️ fastapi: 可能存在兼容性问题（如果同时使用 fastapi）
解决方案：
如果只使用 ssh-licco，可以忽略此警告
如果同时使用 fastapi，建议：
pip install starlette==0.50.0pyopenssl 需要 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 的功能。
错误: Connection refused
解决:
检查 SSH 服务是否运行：systemctl status sshd
检查防火墙设置：ufw status
确认端口正确：默认 22
错误: Authentication failed
解决:
检查用户名和密码
尝试使用密钥认证
查看 SSH 日志：/var/log/auth.log
错误: 命令 'xxx' 不在允许列表中
解决:
{
"SSH_SECURITY_LEVEL": "balanced",
"SSH_EXTRA_ALLOWED_COMMANDS": "被阻止的命令"
}docs/API_REFERENCE.md - API 参考和错误处理
MCP_CONFIG_GUIDE.md - 配置故障排查
MCP_CONFIG_GUIDE.md - 完整配置指南
SECURITY_CONFIG_GUIDE.md - 安全配置详解
docs/API_REFERENCE.md - API 参考文档
文档 | 描述 | 位置 |
📖 配置指南 | 完整配置选项和场景 | |
🔐 安全指南 | 安全配置详解 | |
📊 API 参考 | 完整 API 文档 | |
🎓 Skills | 开发、运维、安装指南 | |
📦 发布指南 | 版本发布流程 |
指标 | 状态 |
测试用例 | 244 passed, 0 skipped |
覆盖率 | 16 个源模块全覆盖 |
测试框架 | pytest + pytest-asyncio |
源模块 | 测试文件 | 用例数 |
|
| 7 |
|
| 8 |
|
| 24 |
|
| 8 |
|
| 12 |
|
| 8 |
|
| 18 |
|
| 6 |
|
| 10 |
|
| 10 |
|
| 18 |
|
| 10 |
|
| 18 |
|
| 10 |
|
| 10 |
|
| 30+ |
|
| 14 |
# 运行全部测试
pytest tests/ -v
# 运行特定模块测试
pytest tests/test_security.py -v
# 查看覆盖率
pytest --cov=ssh_mcp --cov-report=term-missing项目提供 sync_version.py 作为唯一版本发布入口，一条命令完成所有版本源同步 + 文档更新 + 一致性自检 + git commit/tag/push，杜绝漏改 VERSION / package.json / SKILL.md 等文件。
# 升 patch（z）：2.7.1 → 2.7.2
python sync_version.py 2.7.2
# 升 minor（y）：2.7.1 → 2.8.0
python sync_version.py 2.8.0
# 升 major（x）：2.7.1 → 3.0.0
python sync_version.py 3.0.0默认行为：改版本源 → 同步文档版本 → 一致性自检 → commit → push → 打 tag → push tag。
# 预览会发生的变更，不写文件、不 commit
python sync_version.py 2.7.2 --dry-run
# 只改文件，不提交、不打 tag
python sync_version.py 2.7.2 --no-commit --no-tag
# 只做一致性自检（CI 中使用）
python sync_version.py --check文件 | 字段 | 说明 |
|
| 唯一真源，其他文件都与其对齐 |
|
| Python 包构建版本 |
| 纯文本 |
|
|
| npm 包版本 |
|
| npm lock 根版本 + |
|
| 文档中的版本标注 |
|
| 文档中的版本标注 |
.github/workflows/pypi.yml 在构建前会执行 python sync_version.py --check，任何版本源不一致都会直接中断发布流程，防止打错版本号。
完整发布流程（含 PyPI 上传、MCP Registry 发布）见 docs/skills/RELEASE_SKILL.md。
Establish an SSH connection to a remote server. If no parameters are provided, auto-connects using environment variables or saved config. Supports password, private key, and agent authentication. Optionally save the config and/or execute a command after connecting.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | SSH server hostname or IP. If omitted, auto-reads from env vars or saved config. | |
| name | No | Use a pre-configured host from hosts.json by name. | |
| port | No | SSH port | |
| command | No | Optional command to execute immediately after connecting. | |
| password | No | SSH password for password-based auth. | |
| username | No | SSH username. If omitted, auto-reads from env vars. | |
| passphrase | No | Passphrase for encrypted private key. | |
| auth_method | No | Authentication method. | private_key |
| save_config | No | Save connection settings to local config file for future use. | |
| sudo_password | No | Sudo password (optional). When set, ssh_execute with use_sudo=true will auto-wrap commands with sudo -S, avoiding plaintext password in process list. | |
| private_key_path | No | Path to private key file for key-based auth. | |
| accept_new_host_key | No | Auto-accept new host keys. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It mentions authentication methods and optional actions, but it does not disclose critical behaviors such as whether the connection creates a persistent session usable by other tools, what the return value is, failure handling, or timeout behavior. This is a significant gap given the sibling tool 'ssh_session' exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and efficiently communicates the core purpose, auto-connect behavior, and optional features. It is front-loaded with the main action and avoids redundancy, earning a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters), lack of annotations, and absence of an output schema, the description is incomplete. It does not explain what the tool returns on success/failure, whether it establishes a persistent session for use with sibling tools, or how it relates to ssh_session. This leaves agents guessing about essential invocation context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented. The description adds some context by referencing auto-connect, authentication methods, and optional save/execute, but it does not add meaning beyond what the schema provides. Per the rubric, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the primary action (establish an SSH connection) and mentions key features like auto-connect, authentication methods, and optional save/execute. However, it does not explicitly differentiate from siblings like ssh_session, which might also establish connections, so it is not fully distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning auto-connect when no parameters are provided and optional post-connect actions, but it does not explicitly state when to prefer this tool over alternatives or provide exclusions. It lacks a clear 'when to use this vs. others' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close an active SSH session. If no session_id is provided, lists all currently active sessions with connection details.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | No | Session ID to disconnect. If omitted, lists all active sessions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It discloses both the destructive close action and the conditional list-all-sessions behavior, including that connection details are returned. It does not mention side effects or permission requirements, but covers the core observable behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The primary action is front-loaded, and the conditional behavior is stated efficiently in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a low-complexity tool with a single optional parameter and no output schema. The description fully explains how to invoke both modes and what to expect when listing, so an agent has enough information to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description already states 'Session ID to disconnect. If omitted, lists all active sessions.' The tool description adds no new parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Close') and resource ('active SSH session'), and adds a conditional listing behavior when no session_id is given. This clearly distinguishes ssh_disconnect from sibling connection, execution, and file-transfer tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this to close an active SSH session, and if no id is supplied it lists active sessions. It does not explicitly name alternatives or exclusion criteria, but the use case is unambiguous from the stated behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage Docker on the remote server. Supports ps (list containers), images (list images), build (build an image in background), and logs (view container logs).
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | SSH server hostname or IP. Alternative to session_id/name, can override hosts.json entry. | |
| name | No | Use a pre-configured host from hosts.json by name. Alternative to session_id. | |
| port | No | SSH port (used with host). | |
| tail | No | Number of log lines to retrieve. | |
| action | Yes | Docker action: ps=list containers, images=list images, build=build an image, logs=view container logs. | |
| context | No | Build context directory for build. | . |
| password | No | SSH password (used with host). | |
| username | No | SSH username (used with host). | |
| image_name | No | Docker image name. Required for build, optional filter for images. | |
| session_id | Yes | Active SSH session ID. If omitted, connects via name/host/env vars. | |
| container_name | No | Container name or ID. Required for logs. | |
| dockerfile_path | No | Path to Dockerfile for build. | ./Dockerfile |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It does disclose that build runs in the background and implies ps/images/logs are read-oriented actions, but it omits details like auth requirements, side effects of build, and failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two focused sentences with no filler: the first states scope and the second lists the supported actions. It is front-loaded and every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a multi-action tool with 12 parameters, the action list plus fully described schema is largely sufficient to invoke correctly. It lacks explicit usage guidance and output details, but no output schema is present and the schema supplies most invocation information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented. The tool description adds no extra parameter-level meaning, so it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific scope – Docker on a remote server – and enumerates the four supported actions (ps, images, build, logs). It is clear enough to distinguish this tool from the SSH sibling tools, though 'Manage' is somewhat broad.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear this is the Docker-specific remote tool, but it never explicitly says when to prefer it over alternatives like ssh_execute, or when not to use it. Usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a command on a remote server. If session_id is omitted, auto-connects using environment variables. Supports background execution for long-running tasks (auto-detected or manual). Use session_type='screen' or 'tmux' for persistent sessions that survive SSH disconnect.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | SSH server hostname or IP. Alternative to session_id/name, can override hosts.json entry. | |
| name | No | Use a pre-configured host from hosts.json by name. Alternative to session_id. | |
| port | No | SSH port (used with host). | |
| wait | No | Wait for background task to complete. | |
| command | Yes | Shell command to execute on the remote server (required). | |
| timeout | No | Command timeout in seconds. Default 120s. For long tasks (docker pull, pg_basebackup), set higher or use background=true. | |
| workdir | No | Working directory for background tasks. | /tmp |
| log_file | No | Log file path for background task output. | /tmp/background_task.log |
| password | No | SSH password (used with host). | |
| use_sudo | No | Wrap command with sudo -S using sudo_password from ssh_connect. Password is passed via stdin, not visible in process list. | |
| username | No | SSH username (used with host). | |
| background | No | Run in background for long-running tasks. Auto-detected if not specified. | |
| session_id | No | Session ID from ssh_connect. If omitted, connects via name/host/env vars. | |
| session_type | No | Background session type: nohup (default), screen, or tmux (persistent). | nohup |
| wait_timeout | No | Max wait time in seconds when wait=True. | |
| confirm_dangerous | No | Bypass security validation for known-dangerous commands (e.g. rm -rf /path). Use with caution — only for operations you explicitly intend to perform. | |
| backup_before_delete | No | For recursive deletion commands (rm -r/rf), explicitly choose whether to backup targets before deleting. Set true to backup to /tmp/ssh_mcp_backup_<timestamp>/ then delete; set false to delete directly. Required when a recursive deletion is detected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does add useful behavior: auto-connection, background auto-detection, and persistent sessions via screen/tmux. However, it does not mention potential destructive side effects or the confirmation/backup safety mechanisms that exist in the parameters, which is relevant for arbitrary remote command execution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action, then gives only the most useful conditional guidance. Every sentence earns its place, with no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (17 parameters, no output schema, no annotations), the description covers the main execution flow but leaves important invocation decisions to parameter descriptions, such as sudo prerequisites and dangerous-command confirmation. It is not incomplete, but it is not sufficiently self-contained for an agent operating without deep schema inspection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds a little context around session_id and session_type, but it does not meaningfully explain parameter precedence such as host vs name vs session_id, or the wait/wait_timeout relationship beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the core action: 'Execute a command on a remote server.' It also gives useful context about connection and background execution modes. It does not explicitly distinguish itself from sibling tools like ssh_process or ssh_file_transfer, but the main intent is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives actionable guidance: use session_id when available, auto-connect via environment variables otherwise, use background execution for long-running tasks, and use screen/tmux for persistent sessions. It does not explicitly state when not to use the tool or name alternatives, but the conditions provided are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transfer and manage files between local and remote server via SFTP. Supports upload, download, list, write (write content directly to remote file), append, delete, mkdir, stat, and remote_copy (server-to-server direct transfer via scp/rsync, avoiding local relay).
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | SSH server hostname or IP. Alternative to session_id/name, can override hosts.json entry. | |
| name | No | Use a pre-configured host from hosts.json by name. Alternative to session_id. | |
| port | No | SSH port (used with host). | |
| content | No | Content to write/append to remote file. Required for write/append. | |
| password | No | SSH password (used with host). | |
| username | No | SSH username (used with host). | |
| direction | Yes | Action: upload, download, list, write (content->remote file), append, delete, mkdir, stat, remote_copy (server-to-server direct transfer). | |
| use_rsync | No | remote_copy: Use rsync instead of scp (better for large directories, supports resume). | |
| local_path | No | Local file path. Required for upload/download. | |
| session_id | Yes | Active SSH session ID. If omitted, connects via name/host/env vars. | |
| remote_path | No | Remote file/directory path. Required for all directions. For remote_copy, this is the source path on the connected server. | |
| target_host | No | remote_copy: Target server hostname/IP. | |
| target_path | No | remote_copy: Destination path on target server. | |
| target_port | No | remote_copy: Target SSH port. | |
| target_user | No | remote_copy: Target SSH username. | root |
| target_password | No | remote_copy: Target server password (uses sshpass). If omitted, assumes key-based auth is configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does disclose that remote_copy uses scp/rsync and avoids local relay, which is useful. But it does not mention authentication fallback behavior, that delete/write/overwrite operations are destructive, or what the tool returns after an operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the core purpose, and then lists operations efficiently. Every phrase earns its place; there is no fluff or redundant restating of parameter names.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 16 parameters, 9 directions, no annotations, and no output schema, the description is serviceable but not complete. It gives a good operation catalog but leaves out connection/session selection context, authentication expectations, destructive-operation warnings, and return-value behavior, which an agent would need to invoke it correctly across all modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter. The description adds a little context around write and remote_copy, but it largely stays at the operation-catalog level rather than adding meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb-resource pair: 'Transfer and manage files between local and remote server via SFTP.' It then enumerates the exact operations, making the tool easily distinguishable from sibling tools like ssh_execute or ssh_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The operation list implies when the tool is appropriate for file transfer and management, and the remote_copy note gives a small usage hint about avoiding local relay. However, it never explicitly contrasts this tool with alternatives such as ssh_execute for running commands or ssh_session for session management.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a new SSH key pair (RSA or Ed25519) for secure key-based authentication. Optionally save to a file path.
| Name | Required | Description | Default |
|---|---|---|---|
| comment | No | Optional comment to identify the key. | |
| key_size | No | Key size for RSA. | |
| key_type | No | Key algorithm type. | ed25519 |
| save_path | No | Optional path to save the generated key files. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure. It mentions optional file saving, but fails to state whether keys are returned when no path is given, whether existing files are overwritten, or security-related behaviors like passphrases and file permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler, front-loading the action and resource, then compactly mentioning options. Every clause adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, no annotations, and 4 optional parameters, the description omits critical operational details: what the response contains, what happens if save_path is omitted, and whether the generated key is available immediately or only on disk.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already documents all 4 parameters (100% coverage), so the description adds little beyond naming RSA/Ed25519 and the optional save path. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states a specific verb ('Generate'), a specific resource ('new SSH key pair'), supported algorithms (RSA or Ed25519), and purpose (authentication). It is clearly distinct from sibling tools focused on sessions, connections, execution, and file transfer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for secure key-based authentication' implies use when creating SSH credentials, but there is no explicit guidance on when to use this tool over alternatives, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage SSH server configurations in hosts.json. Use action=list to view all hosts, action=add to register a new server, action=remove to delete a server.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Server hostname or IP. Required for add. | |
| name | No | Friendly name for the server. Required for add and remove. | |
| port | No | SSH port number. | |
| action | Yes | Action: list all hosts, add a new host, or remove a host. | |
| timeout | No | Connection timeout in seconds. | |
| password | No | SSH password (optional for key auth). | |
| username | No | SSH login username. | root |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It does disclose that removal deletes a server and that the tool manages the persistent hosts.json file. However, it does not describe side effects, permission requirements, return format, or clarify that this tool does not itself establish an SSH connection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The resource and the action pattern are front-loaded, making it easy for an agent to quickly understand the tool's core behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The full parameter documentation and explicit action examples make the invocation requirements mostly clear despite the absence of an output schema. The main gap is that the return/result shape is unspecified, but for a simple configuration-management tool this does not prevent correct selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameter semantics are already fully documented by the input schema. The description only restates the action enum values, adding no new parameter-level meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description anchors on a specific resource ('SSH server configurations in hosts.json') and enumerates concrete actions (list/add/remove). This clearly distinguishes it from operational siblings like ssh_connect, ssh_execute, and ssh_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides action-level usage guidance ('use action=list', 'action=add', 'action=remove') but does not explicitly state when to select this tool over alternatives such as ssh_connect or ssh_session. The intended context is implied through 'hosts.json' and configuration management, not directly contrasted with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage background processes and SSH tunnels on the remote server. Actions: start (launch a detached background process, returns PID), stop (stop a process by PID), status (check if a PID is running), list (list tracked background tasks), tunnel_open (local port forward to remote host:port), tunnel_close (close a tunnel), tunnel_list (list active tunnels).
| Name | Required | Description | Default |
|---|---|---|---|
| pid | No | Process ID (stop/status). | |
| host | No | SSH server hostname or IP. Alternative to session_id/name, can override hosts.json entry. | |
| name | No | Use a pre-configured host from hosts.json by name. Alternative to session_id. | |
| port | No | SSH port (used with host). | |
| action | Yes | Process/tunnel action. | |
| signal | No | Signal to send on stop (TERM, KILL, INT, etc.). | TERM |
| command | No | Command to run (start). | |
| task_id | No | Task ID (stop/status, alternative to pid). | |
| workdir | No | Working directory (start). | /tmp |
| log_file | No | Log file path (start). Default /tmp/bg_<taskid>.log | |
| password | No | SSH password (used with host). | |
| username | No | SSH username (used with host). | |
| local_port | No | Local listen port (tunnel_open). | |
| session_id | Yes | Active SSH session ID. If omitted, connects via name/host/env vars. | |
| remote_host | No | Remote target host (tunnel_open). | |
| remote_port | No | Remote target port (tunnel_open). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It discloses that start launches a detached background process and returns a PID, and that stop uses a PID, but omits details on error handling, idempotency, side effects, authentication requirements, or whether actions are destructive. The behavior is partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph with the purpose front-loaded, followed by a concise action list. It is efficiently structured, though the list of actions could be slightly more compact without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 16 parameters and 7 actions, the description covers the actions but does not specify which parameters are required for each action, nor does it clarify connection options (session_id vs host/name vs environment variables). No output schema exists, so return formats for actions like list, status, or tunnel_list remain undefined, leaving gaps for an agent to fill.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, but the description adds crucial meaning by mapping actions to their relevant parameters (e.g., start uses command, stop uses pid, tunnel_open uses local_port/remote_host/remote_port). This goes beyond the generic schema descriptions and aids correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it manages background processes and SSH tunnels on a remote server, enumerating seven specific actions. This distinguishes it from siblings like ssh_execute (likely foreground execution) and ssh_session (session lifecycle management).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the action list but there is no explicit guidance on when to use this tool versus alternatives like ssh_execute for foreground commands or ssh_session for session management. No when-not-to-use conditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage persistent screen/tmux sessions on the remote server for long-running interactive tasks (deploy, build, test, REPL). Sessions survive SSH disconnect. Actions: create (new detached session running a command), send (send keys/command to a session), capture (read current screen), list (list sessions), kill (kill a session).
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | SSH server hostname or IP. Alternative to session_id/host_name, can override hosts.json entry. | |
| name | No | Session name. Required for create/send/capture/kill. Only letters, digits, _, ., - allowed. | |
| port | No | SSH port (used with host). | |
| lines | No | Number of lines to capture (tmux capture-pane -S). | |
| action | Yes | create=new detached session, send=send keys/command to a session, capture=read current screen content, list=list sessions, kill=kill a session. | |
| command | No | Command to run initially (create) or to send (send). | |
| password | No | SSH password (used with host). | |
| username | No | SSH username (used with host). | |
| host_name | No | Use a pre-configured host from hosts.json by name. Alternative to session_id. | |
| session_id | Yes | Active SSH session ID. If omitted, connects via name/host/env vars. | |
| session_type | No | Use screen or tmux backend. | screen |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the behavioral burden. It discloses persistence and action meanings (create is detached, capture reads current screen), but does not mention the destructive irreversibility of kill, authentication needs, session/host precedence, or edge-case behavior on nonexistent sessions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the first front-loads purpose and context, the second compactly enumerates all actions. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema is rich and fully covers parameters, and the description covers the tool's overall behavior and all actions. However, with no output schema, it leaves gaps around return format for capture/list, which connection identity (session_id vs host_name vs host) takes precedence, and whether kill requires confirmation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already documented in the input schema. The description's action list essentially restates the action enum values without adding new parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific purpose ('Manage persistent screen/tmux sessions... for long-running interactive tasks') and enumerates the five actions with concrete semantics. Differentiates from siblings by emphasizing persistence and surviving SSH disconnect, which clearly separates it from one-off ssh_execute.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: use for long-running interactive tasks like deploy, build, test, and REPL, and notes sessions survive disconnect. Stops short of explicitly naming alternatives or stating when not to use this tool, so it misses the full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.7.2ssh_connectssh_disconnectssh_dockerssh_executessh_file_transferssh_generate_keyssh_hostssh_processssh_sessionScored across 9 tools
ssh_execute, ssh_session, and ssh_process all overlap in running commands, background execution, and persistent sessions, making it unclear which tool to select for a given task. ssh_connect and ssh_disconnect also blur the line between network connections and screen/tmux sessions.
All tools share the ssh_ prefix, but the pattern mixes verb-style names (ssh_connect, ssh_execute, ssh_disconnect) with noun-style names (ssh_session, ssh_process, ssh_host, ssh_docker) and one verb_noun compound (ssh_generate_key). This is readable but not a fully consistent convention.
Nine tools form a reasonable surface for an SSH remote-management server, covering connection, execution, file transfer, sessions, processes, host config, Docker, and keys. Each tool is broad enough to avoid requiring an excessive number of separate tools.
The toolkit covers most core SSH workflows: connect/disconnect, execute, persistent sessions, file transfer, background processes, host management, Docker, and key generation. Minor gaps like reverse SSH tunneling and key listing/removal are missing, but agents can work around these via ssh_execute.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
