✨ 为什么选择 TermSSH MCP

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

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

安装程序需要回答问题
Shell 需要保持状态
调试需要多个步骤
部署需要上传文件并进行终端控制
代理需要观察、反应并继续执行

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

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

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

🧠 它有何不同

终端优先

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

代理就绪

专为 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 了解预期行为。