TermSSH MCP

✨ 为什么选择 TermSSH MCP

大多数用于 AI 工作流的 SSH 工具都是围绕 运行命令 → 获取输出 → 结束 构建的。

当实际任务需要交互时，这种方式就会失效：

• 安装程序需要回答问题

• Shell 需要保持状态

• 调试需要多个步骤

• 部署需要上传文件并进行终端控制

• 代理需要观察、反应并继续执行

TermSSH MCP 正是为了填补这一空白而构建的。

它不再假定一切都是单次命令，而是为 MCP 客户端提供了一种真正的操作员式工作流：

打开 Shell → 写入输入 → 读取输出 → 保持上下文 → 上传文件 → 继续工作

Related MCP server: ssh-mcp

🧠 它有何不同

终端优先

交互式终端会话是核心模型，而非事后补充。

代理就绪

专为 MCP 客户端、编码代理和自动化循环设计。

有状态工作流

重用活动会话，使多步骤任务感觉自然且可靠。

包含上传功能

通过 SFTP 移动脚本、配置、有效载荷和生成的工件。

跨平台

适用于 Linux 和 Windows SSH 目标。

简洁的工具界面

专注于终端控制和远程文件传输的 MCP 工具。

🚀 核心功能

• 交互式 SSH 终端会话

• 增量终端读/写流

• 默认托管终端会话重用

• 可选的强制多会话创建

• 通过 SFTP 进行本地文件上传

• 直接文本和 base64 内容上传

• 终端调整大小支持

• Linux 和 Windows SSH 目标支持

• 面向 AI 工具的 MCP 原生接口

🧰 工具集

upload-file

使用 SFTP 将本地文件从 MCP 主机上传到远程 SSH 服务器。

参数

• localPath — 本地源文件路径

• remotePath — 远程主机上的目标路径

• createDirectories — 如果需要，创建缺失的父目录

• overwrite — 如果存在，替换现有的远程文件

• mode — 可选的 POSIX 模式，例如 0644

upload-content

将直接文本或 base64 内容上传到远程服务器。

参数

• content — 原始文本或 base64 有效载荷

• encoding — utf8 或 base64

• remotePath — 远程主机上的目标路径

• createDirectories — 如果需要，创建缺失的父目录

• overwrite — 如果存在，替换现有的远程文件

• mode — 可选的 POSIX 模式，例如 0644

terminal-start

启动交互式远程终端会话。

参数

• cwd — Shell 启动后的可选工作目录

• shell — 可选的 Shell 二进制文件

• platformHint — auto、linux 或 windows

• elevated — 配置后尝试 su 提权

• cols — 终端宽度

• rows — 终端高度

• env — 可选的环境变量

• multiSession — 设置为 true 以强制创建新的托管会话，而不是重用现有会话

terminal-write

将输入写入活动终端会话。

参数

• sessionId — 目标会话 ID

• input — 要发送的文本

• appendNewline — 如果需要，自动附加换行符

terminal-read

从终端会话读取缓冲输出。

参数

• sessionId — 目标会话 ID

• sinceSequence — 仅返回比给定序列号更新的输出

• maxChars — 限制返回输出的大小

• waitForMs — 可选的短轮询延迟

terminal-resize

调整活动终端会话的大小。

参数

• sessionId — 目标会话 ID

• cols — 新宽度

• rows — 新高度

terminal-close

在本地关闭终端会话。

参数

• sessionId — 目标会话 ID

🔄 典型工作流

flowchart LR
    A[terminal-start] --> B[terminal-write]
    B --> C[terminal-read]
    C --> D{Need file?}
    D -- Yes --> E[upload-file / upload-content]
    D -- No --> F{Continue session?}
    E --> F
    F -- Yes --> B
    F -- No --> G[terminal-close]

这特别适用于：

• 交互式包安装

• 远程设置和配置

• 带有工件上传的部署

• 跨多个步骤的服务调试

• 上下文至关重要的有状态 Shell 工作流

🛠 安装

克隆仓库

git clone https://github.com/rayss868/termssh-mcp.git
cd termssh-mcp
npm install
npm run build

全局安装

npm install -g termssh-mcp

⚙ 配置

必需的 CLI 参数

• host — 远程机器的主机名或 IP 地址

• user — SSH 用户名

可选的 CLI 参数

• port — SSH 端口，默认为 22

• password — SSH 密码

• key — 私有 SSH 密钥路径

• sudoPassword — 面向 sudo 的工作流的可选密码

• suPassword — 基于 su 的提权的可选密码

• timeout — SSH 就绪超时（毫秒），默认为 60000

• maxChars — 命令长度验证限制，默认为 1000；使用 none 或 0 开启无限制模式

🧩 MCP 配置示例

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=1.2.3.4",
        "--port=22",
        "--user=root",
        "--password=pass",
        "--timeout=30000",
        "--maxChars=none"
      ]
    }
  }
}

SSH 密钥示例

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=example.com",
        "--user=root",
        "--key=/path/to/private/key"
      ]
    }
  }
}

🤖 Claude Code 示例

在 Claude Code 中注册服务器：

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD

使用 SSH 密钥认证：

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=example.com --user=root --key=/path/to/private/key

使用扩展超时：

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=192.168.1.100 --user=admin --password=your_password --timeout=120000 --maxChars=none

🎯 适用场景

开发人员

• 来自 AI 编码工具的远程 Shell 访问

• 有状态的调试会话

• 脚本和配置交付

DevOps / 基础设施团队

• 服务检查

• 部署支持

• 多步骤远程操作

代理构建者

• 终端原生的 MCP 工作流

• 可重用会话

• 受控的远程自动化循环

🏗 开发

构建项目：

npm run build

运行测试：

npm test

使用 MCP Inspector：

npm run inspect

📁 项目结构

• src/index.ts — MCP 服务器入口点和工具注册

• src/ssh-connection-manager.ts — SSH 连接和终端生命周期处理

• src/upload.ts — 上传辅助工具和交互式会话元数据辅助工具

• src/core.ts — 共享验证和 SSH 实用程序原语

• test/upload-and-terminal.test.ts — 上传/会话单元测试覆盖

• test/maxChars.test.ts — 命令验证覆盖

• test/smoke.ssh.test.ts — 当前导出行为的冒烟测试

🗺 路线图构想

• 更丰富的会话元数据检查

• 更好的远程会话可观测性

• 可选的会话持久化功能

• 更多针对 Claude Code 和 MCP 工具的示例

• 面向部署的工作流模板

🔐 安全说明

TermSSH MCP 提供通过 SSH 对系统的远程访问。 请仅在您拥有或明确授权管理的基础设施上使用它。

📜 许可证

在 MIT 许可证 下发布。

🤝 贡献

欢迎贡献。 请参阅 CONTRIBUTING.md 获取贡献指南，并参阅 CODE_OF_CONDUCT.md 了解预期行为。