Linux SSH MCP - WindTerm 风格终端模拟器

🚀 WindTerm 风格的终端模拟器，通过 Model Context Protocol (MCP) 与 AI 助手集成

通过自然语言管理多台 Linux 服务器：多标签页 SSH 会话、命令执行、文件传输、工作区持久化，全部暴露为 AI 助手可调用的 MCP 工具。

核心功能

🖥️ 多标签页 SSH 会话管理

• 多标签页：像浏览器一样同时管理多台服务器的终端会话

• 会话切换：在多个活跃会话间快速切换

• 工作区持久化：把一组服务器会话保存为命名工作区，随时恢复

🤖 AI 助手集成（MCP 2.0）

• 17 个 MCP 工具：终端管理、命令执行、文件传输、会话控制全覆盖

• 自然语言驱动：用一句话创建会话、执行命令、传输文件

• stdio 传输：与 Claude Code 等 MCP 客户端无缝对接

📁 文件传输（SFTP）

• 上传 / 下载文件

• 直接读取远端文件内容

⚡ 跨平台

• 纯 asyncssh 实现，Windows / Linux / macOS 均可运行，无需本地 PTY

系统要求

• Python 3.9+

• 可访问的 SSH 服务器

快速开始

安装

# 从 PyPI 安装
pip install linux-ssh-mcp

# 开发模式（克隆仓库后）
pip install -e ".[dev]"

接入 Claude Code

claude mcp add linux-ssh-mcp python -m linux_ssh_mcp.cli_v2

接入后，AI 助手即可通过自然语言操作你的服务器：

"连接到 web-server，执行 df -h 查看磁盘空间" "把本地的 deploy.sh 上传到生产服务器的 /opt/app/" "保存当前所有会话为'日常巡检'工作区"

服务器配置（可选）

首次使用可生成示例配置：

linux-ssh-mcp init          # 生成 ~/.ssh-mcp/servers.json
linux-ssh-mcp check         # 检查配置并列出已配置服务器

配置文件 servers.json 示例：

{
  "version": "2.0",
  "servers": {
    "web-server": {
      "id": "web-server",
      "host": "192.168.1.100",
      "port": 22,
      "username": "admin",
      "password": "your_password"
    }
  }
}

配置文件搜索路径（按优先级）：

1. SSH_MCP_CONFIG_PATH 环境变量

2. ~/.ssh-mcp/servers.json

3. 平台特定目录：Windows %APPDATA%/ssh-mcp/、Linux/macOS ~/.config/ssh-mcp/

4. 当前工作目录 ./servers.json

5. 项目根目录 servers.json

命令行工具

# 启动 MCP 服务器（供 Claude Code 连接）
linux-ssh-mcp server
linux-ssh-mcp server --debug       # 调试日志

# 检查配置
linux-ssh-mcp check

# 创建示例配置
linux-ssh-mcp init

# 测试终端连接
linux-ssh-mcp test 192.168.1.100 admin --password your_password --port 22

也可通过 Python 模块运行：

python -m linux_ssh_mcp.cli_v2 server
python -m linux_ssh_mcp.mcp_server_v2

MCP 工具清单

AI 助手通过以下 17 个工具操作终端（由 WindTermMCPServer 在 mcp_server_v2.py 中注册）：

未指定 tab_id 的工具默认作用于当前活跃标签页。

Python API

import asyncio
from linux_ssh_mcp.simple_terminal_manager import (
    SimpleTerminalSessionManager, ServerConfig,
)

async def main():
    manager = SimpleTerminalSessionManager()

    # 创建并连接一个终端会话
    config = ServerConfig(
        id="web-server",
        host="192.168.1.100",
        port=22,
        username="admin",
        password="your_password",
        timeout=30,
    )
    tab = await manager.create_tab(config, title="Web Server")

    # 执行命令并读取输出
    await tab.send_input("uptime")
    print("\n".join(tab.get_output(20)))

    # 保存为工作区，之后可恢复
    await manager.save_workspace("daily-check")

    await manager.shutdown()

asyncio.run(main())

包导出的主要符号（linux_ssh_mcp）：

• SimpleTerminalSessionManager、SimpleTabSession、ServerConfig、TabStatus — MCP 服务器实际使用的会话栈

• TerminalSessionManager、PTYManager、TerminalProtocolHandler — 完整 PTY 栈（真 PTY + 终端协议，尚未接入 MCP 服务器）

• EnhancedSSHManager — SSH 连接池管理

• ScriptingEngine — 脚本自动化引擎

架构说明

本项目包含两套并行的会话实现：

1. Simple 栈（生产路径） —— WindTermMCPServer → SimpleTerminalSessionManager → asyncssh 直接通过 asyncssh 执行命令并把输出收集到内存缓冲。跨平台、零本地依赖，AI 助手调用的就是这条链路。适合命令式操作（占运维场景绝大多数）。

2. Full PTY 栈 —— TerminalSessionManager → terminal_emulator（真 PTY + ANSI/VT100/xterm-256color）+ EnhancedSSHManager 功能更完整，支持真正的交互式终端（如 vim、top 等全屏程序）。目前仅被 test 命令使用，尚未接入 MCP 服务器。

详见 CLAUDE.md 的架构章节。

开发

# 运行测试套件（生产路径 Simple 栈 + 终端模拟器）
python -m pytest tests/

# 运行单个测试
python -m pytest tests/test_simple_terminal_manager.py -v

# 代码质量
black src/ tests/        # 格式化（行宽 88）
mypy src/                # 类型检查
flake8 src/              # 风格检查

Full 栈的 PTY+SSH 集成测试默认跳过；设置环境变量 SSH_MCP_TEST_HOST 指向一台可达的 SSH 服务器后才会运行。

构建发布

python -m build
python -m twine upload dist/*

入口点

许可证

MIT License

Built with ❤️ for the Linux SSH management community