linux-remote-mcp
Provides tools for managing Docker containers on remote Linux hosts, including listing, running, stopping, viewing logs, and executing commands within containers.
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., "@linux-remote-mcp show system info for 192.168.1.100"
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.
🖥️ linux-remote MCP Server
通过 SSH 远程控制 Linux 机器的 MCP Server。35 个工具,覆盖会话管理、文件传输、系统运维、Docker 管理和 CTF 攻防场景。支持同时连接多台机器,自动适配不同发行版。
🚀 快速开始
1. 安装
git clone https://github.com/yu-xiaohaozi/linux-remote-mcp.git
cd linux-remote-mcp
pip install -e .2. 配置 MCP 客户端
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"linux-remote": {
"command": "python",
"args": ["-m", "linux_remote"]
}
}
}Reasonix / 其他支持 MCP 的客户端:直接将上述配置加入你的 config.toml 或 .mcp.json。
3. 开始使用
→ session_connect(target="192.168.1.100", user="root", password="xxx")
✅ Connected to root@192.168.1.100:22 [sess-1]
→ sys_info(session_id="sess-1")
CentOS 7 / 3.10.0 kernel / 4GB RAM / 50GB disk
→ pkg_install(session_id="sess-1", packages="nginx docker.io")
✅ Installed via yumRelated MCP server: VPS MCP Server
✨ 特性
特性 | 说明 |
🔌 SSH 会话池 | 持久连接,支持同时管理多台机器 |
🧠 智能适配 | 自动识别 apt/yum/dnf/pacman、systemd/sysvinit、ufw/firewalld |
🔐 双模式认证 | 密码登录 + SSH 密钥,临时传参或预配置别名 |
🎯 CTF 专用 | 反弹 Shell 生成、端口扫描、一键 HTTP 服务、nc 监听 |
🐳 Docker 管理 | 容器启停、日志查看、容器内命令执行 |
📦 开箱即用 | pip install 一条命令,无需额外配置 |
🏗️ 架构
┌──────────────┐ MCP Protocol ┌──────────────────┐ SSH ┌────────────┐
│ AI Agent │ ◄────────────────── ► │ linux-remote │ ◄────────── ► │ Linux VM │
│ (Claude etc) │ (stdio/JSON-RPC) │ MCP Server │ (asyncssh) │ (任意发行版) │
└──────────────┘ └──────────────────┘ └────────────┘
│
~/.linux-remote/
hosts.yaml (可选)持久会话 vs 短连接
每个 session_connect 创建一个持久 SSH 会话,后续所有操作通过 session_id 引用。支持同时持有多个会话,在多台机器间自由切换。调用 session_disconnect 或进程退出时自动清理。
📋 工具参考
🔌 会话管理 (3)
工具 | 参数 | 说明 |
|
| 连接主机(IP 或预配置别名) |
|
| 断开指定会话 |
| — | 列出所有活跃会话及运行时长 |
⚡ 命令 & 文件 (6)
工具 | 参数 | 说明 |
|
| 执行任意 Shell 命令 |
|
| 上传文件 (SFTP) |
|
| 下载文件 (SFTP) |
|
| 写入文件内容 |
|
| 读取文件内容 |
|
| 检查文件/目录是否存在 |
🗂️ 主机配置 (3)
工具 | 参数 | 说明 |
|
| 保存主机别名 |
|
| 删除主机别名 |
| — | 列出所有已保存的主机 |
🖥️ 系统管理 (11)
工具 | 参数 | 说明 |
|
| 系统概览(OS/内核/CPU/内存/磁盘) |
|
| 列出 uid≥1000 的用户 |
|
| 安装软件包(自动识别包管理器) |
|
| 更新所有系统包 |
|
| 列出已安装包(支持过滤) |
|
| 启停服务(start/stop/restart/enable/disable/status) |
|
| 列出运行中的服务 |
|
| 进程列表(按 CPU/内存排序) |
|
| 终止进程 |
|
| 创建用户(可选密码+sudo) |
|
| 删除用户及家目录 |
🌐 网络 (3)
工具 | 参数 | 说明 |
|
| 检查端口是否监听及归属进程 |
|
| 列出所有监听 TCP 端口 |
|
| 开放防火墙端口(ufw/firewalld/iptables) |
🐳 Docker (5)
工具 | 参数 | 说明 |
|
| 列出容器 |
|
| 运行容器 |
|
| 停止(可选删除)容器 |
|
| 查看容器日志 |
|
| 在容器内执行命令 |
🚩 CTF 工具 (4)
工具 | 参数 | 说明 |
|
| 一键启动 Python HTTP 文件服务 |
|
| nc 监听端口(接收连接/Shell) |
|
| 生成反弹 Shell 命令(bash/python/nc/php/perl/ruby) |
|
| 内网快速端口扫描 |
📖 使用示例
场景一:多机运维
# 同时连接 Web 服务器和数据库服务器
session_connect(target="web-prod", user="root", password="xxx") → sess-1
session_connect(target="db-prod", user="root", password="xxx") → sess-2
# 在 Web 服务器装 Nginx
pkg_install(session_id="sess-1", packages="nginx")
svc_manage(session_id="sess-1", service="nginx", action="start")
# 在数据库服务器装 MySQL
docker_run(session_id="sess-2", image="mysql:8", name="db",
ports="3306:3306", env="MYSQL_ROOT_PASSWORD=secret")
# 查看两边状态
exec(session_id="sess-1", command="systemctl status nginx")
docker_ps(session_id="sess-2")场景二:CTF 攻防
# 连接 Kali 攻击机
session_connect(target="kali-vm") → sess-1
# 内网扫描目标
ctf_scan_ports(session_id="sess-1", target="192.168.1.50", ports="1-1000")
# 生成反弹 Shell,在你的机器上先开监听
ctf_listen_port(session_id="sess-1", port=4444)
ctf_reverse_shell(ip="10.0.0.1", port=4444, shell_type="python")
# 把生成的 payload 粘贴到目标机器执行
# 快速传文件
ctf_serve_http(session_id="sess-1", port=8080, directory="/tmp/payloads")场景三:环境搭建
session_connect(target="dev-server", user="root", password="xxx")
# 一键安装开发环境
pkg_install(session_id="sess-1", packages="git python3 nodejs docker.io")
user_add(session_id="sess-1", username="dev", password="dev123", sudo=true)
# 部署服务
docker_run(session_id="sess-1", image="nginx:alpine", name="web", ports="80:80")
firewall_allow(session_id="sess-1", port=80)🔧 预配置主机
不想每次输入 IP 和密码?用别名保存:
host_add(alias="kali", host="192.168.1.50", user="kali", password="your-password")
host_add(alias="centos", host="192.168.1.100", user="root", password="your-password")之后直接 session_connect(target="kali") 即可。配置文件存储在 ~/.linux-remote/hosts.yaml:
hosts:
kali:
host: 192.168.1.50
port: 22
user: kali
password: your-password
centos:
host: 192.168.1.100
port: 22
user: root
password: your-password也支持 SSH 密钥:
hosts:
prod-server:
host: 10.0.0.5
user: root
key_file: ~/.ssh/id_rsa📦 依赖
包 | 用途 |
| MCP 协议框架 |
| 异步 SSH 连接池 |
| 主机配置文件解析 |
Python ≥ 3.10
🤝 贡献
欢迎提 Issue 和 PR!如果你有常用的运维操作希望封装成高层工具,请在 Issue 中描述场景。
📄 License
Available Tools
35 toolsctf_listen_portC
Start a netcat listener to receive connections/shells.
Inputs: port (required), session_id (required), protocol.
ctf_reverse_shellB
Generate a reverse shell one-liner. Give YOUR ip and port where you're listening.
Inputs: ip (required), port (required), shell_type.
ctf_scan_portsB
Quick port scan from the remote machine using bash /dev/tcp.
Inputs: target (required), session_id (required), ports.
ctf_serve_httpC
Quickly serve a directory over HTTP (Python http.server).
Inputs: session_id (required), port, directory.
docker_execC
Execute a command inside a running Docker container.
Inputs: command (required), container (required), session_id (required).
docker_logsC
Get recent logs from a Docker container.
Inputs: container (required), session_id (required), tail.
docker_psA
List Docker containers (running by default; use all=true for all).
Inputs: session_id (required), all.
docker_runB
Run a Docker container with ports, env, volumes, restart policy.
Inputs: image (required), session_id (required), env, name, +4 more.
docker_stopC
Stop (and optionally remove) a Docker container.
Inputs: container (required), session_id (required), remove.
execB
Execute a shell command on a remote session. Returns stdout, stderr, exit_code.
Inputs: command (required), session_id (required), timeout.
file_downloadB
Download a file from the remote host via SFTP.
Inputs: local_path (required), session_id (required), remote_path (required).
file_existsC
Check whether a file or directory exists on the remote host.
Inputs: path (required), session_id (required).
file_readC
Read the full text content of a remote file.
Inputs: session_id (required), remote_path (required), max_bytes.
file_uploadC
Upload a local file to the remote host via SFTP.
Inputs: local_path (required), session_id (required), remote_path (required).
file_writeB
Write string content directly to a remote file (creates or overwrites).
Inputs: content (required), session_id (required), remote_path (required), mode.
firewall_allowB
Open a port in firewall. Auto-detects ufw/firewalld/iptables.
Inputs: port (required), session_id (required), protocol.
host_addB
Save a host configuration (alias, host, user, password/key) for quick reuse.
Inputs: host (required), alias (required), port, user, +3 more.
host_listA
List all saved host configurations.
Inputs: no named parameters.
host_removeB
Remove a saved host configuration.
Inputs: alias (required).
pkg_installC
Install packages. Auto-detects apt/yum/dnf/pacman/apk.
Inputs: packages (required), session_id (required).
pkg_listC
List installed packages, optionally filtered by name.
Inputs: session_id (required), filter.
pkg_updateC
Update all system packages. Auto-detects package manager.
Inputs: session_id (required).
port_checkB
Check if a specific port is listening and what process uses it.
Inputs: port (required), session_id (required).
port_listenC
List all listening TCP ports with process info.
Inputs: session_id (required).
proc_killB
Kill a process by PID. Default signal 15 (SIGTERM).
Inputs: pid (required), session_id (required), signal.
proc_listB
List top processes sorted by cpu or memory.
Inputs: session_id (required), count, sort_by.
session_connectA
Connect to a Linux host via SSH. target: IP/hostname or a pre-configured alias. Use password or key_file for ad-hoc connections.
Inputs: target (required), port, user, key_file, +2 more.
session_disconnectB
Disconnect an active SSH session.
Inputs: session_id (required).
session_listA
List all active SSH sessions with host, user, uptime.
Inputs: no named parameters.
svc_listC
List currently running services.
Inputs: session_id (required).
svc_manageB
Manage a service: start/stop/restart/enable/disable/status. Auto-detects systemd/sysvinit.
Inputs: action (required), service (required), session_id (required).
sys_infoA
Get system overview: OS, kernel, uptime, CPU, memory, disk.
Inputs: session_id (required).
sys_usersB
List human users on the system (uid >= 1000).
Inputs: session_id (required).
user_addB
Create a Linux user, optionally with password and sudo access.
Inputs: username (required), session_id (required), sudo, password.
user_delC
Delete a Linux user and their home directory.
Inputs: username (required), session_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 35 tools
Each tool targets a distinct action or resource (e.g., exec vs ctf_listen_port vs port_listen), with clear boundaries even in similar areas like port scanning and checking.
Most tools follow a consistent verb_noun pattern (e.g., file_download, session_connect), but 'exec' is a single verb without a prefix, causing a minor inconsistency.
35 tools is on the higher end but justifiable given the comprehensive coverage of remote Linux administration, including Docker, firewall, and CTF utilities.
Covers all core administrative tasks: session, file, package, service, process, user, system info, Docker, firewall, and basic networking—no obvious gaps for typical remote admin needs.
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Persistent Linux computers for AI agents: desktop, signed-in browser, vault, apps and shell.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to perform autonomous penetration testing on any Linux distribution via SSH with persistent tmux sessions, supporting interactive tools like Metasploit, reverse shells, and complex multi-step security workflows.18MIT
- AlicenseAqualityDmaintenanceEnables AI agents to connect to and control a Virtual Private Server via SSH. It provides a comprehensive suite of tools for remote file system operations, session management, and shell command execution.1012 npm2ISC
- AlicenseAqualityDmaintenanceEnables AI assistants to securely execute remote SSH commands, perform file transfers, and monitor system status through a standardized interface. It features robust security controls including command whitelisting, blacklisting, and credential isolation to prevent unauthorized operations.1023 npmMIT

cygnus-ssh-mcpofficial
AlicenseAqualityBmaintenanceEnables AI assistants to manage remote servers via SSH with 43 specialized tools for command execution, file editing, directory operations, and background tasks across Linux, macOS, and Windows.4695 PyPI9GPL 3.0