使用说明

SSH MCP服务器

一种模型上下文协议（MCP）服务器，通过基于浏览器的终端监控为Claude Code提供SSH会话管理。

特性

核心功能

持久SSH会话 -跨命令维护状态的命名SSH连接
交互式终端界面 -基于浏览器的终端，支持键盘输入和命令执行
多会话支持 -同时管理多个独立的SSH会话
实时输出流 -通过WebSocket进行实时终端输出，单屏清晰显示
命令历史记录 -使用时间戳和退出代码跟踪执行的命令
会话隔离 -每个会话都维护单独的终端历史和状态

交互式终端功能

直接命令输入 -直接在浏览器终端界面中键入命令
本地回应 -通过终端光标移动立即显示字符
命令行编辑 -全键盘导航（箭头、主页、结束、退格）
终端状态管理 -基于命令执行状态的智能锁定/解锁
消息来源 -正确跟踪浏览器用户与Claude Code的命令
并发执行 -用户和Claude Code命令通过共享SSH会话执行，并排队

高级功能

多种身份验证方法 -SSH密钥（加密/未加密）、用户名/密码、直接密钥内容
命令队列 -FIFO执行可防止用户和Claude Code命令之间的输出交织
WebSocket通信 -用于命令执行和输出流的双向消息传递
会话状态同步 -多个浏览器客户端与终端状态保持同步
清洁终端显示器 -单一输出，保留ANSI颜色和格式

安装和设置

先决条件

Node.js 16+和npm
已安装并配置Claude Code CLI
SSH服务器访问（用于远程连接）
TypeScript（用于开发）

1.克隆和构建

git clone <repository-url> ls-ssh-mcp
cd ls-ssh-mcp
npm install
npm run build

2.用克劳德代码注册

# Use the installation script (recommended)
./install-mcp.sh

# Or manually register
claude mcp add ssh node /absolute/path/to/ls-ssh-mcp/dist/src/mcp-server.js

3.验证安装

# Check that the server was registered
claude mcp list

它是如何工作的：

这 install-mcp.sh 脚本 寄存器 带有自动发现端口的Claude Code服务器
克劳德代码 自动启动 使用SSH工具时的服务器
无需手动启动/停止-服务器按需运行
Web监控界面可在 http://localhost:{port}/session/{session-name}

安装脚本处理端口发现、现有配置的清理和正确的注册。

用法

基本工作流程

连接到SSH服务器：使用 ssh_connect 使用您的凭据
执行命令：使用 ssh_exec 在远程服务器上运行命令
监控会话：使用 ssh_get_monitoring_url 获取浏览器监控URL
管理会话：使用 ssh_list_sessions 和 ssh_disconnect 根据需要

可用的MCP工具

工具	用途	必需参数
`ssh_connect`	建立SSH连接	`name`, `host`, `username`，身份验证方法*
`ssh_exec`	在远程服务器上执行命令	`sessionName`, `command`
`ssh_list_sessions`	列出所有活动的SSH会话	无
`ssh_get_monitoring_url`	获取浏览器监控URL	`sessionName`
`ssh_disconnect`	断开SSH会话	`sessionName`

* 验证方法：选择一个：

password -SSH用户帐户密码
privateKey -直接私钥内容（+可选 passphrase 如果密钥被加密）
keyFilePath -私钥文件的路径（+可选 passphrase 如果密钥被加密）

示例用法

# 1. Connect to a server (multiple authentication methods)

# Option A: Username/password authentication
ssh_connect name="myserver" host="example.com" username="user" password="pass"

# Option B: SSH key file (recommended)
ssh_connect name="myserver" host="example.com" username="user" keyFilePath="~/.ssh/id_rsa"

# Option C: SSH key file with passphrase (encrypted key)
ssh_connect name="myserver" host="example.com" username="user" keyFilePath="~/.ssh/id_ed25519" passphrase="mypassphrase"

# Option D: Direct private key content (unencrypted)
ssh_connect name="myserver" host="example.com" username="user" privateKey="-----BEGIN OPENSSH PRIVATE KEY-----..."

# Option E: Direct private key content (encrypted with passphrase)
ssh_connect name="myserver" host="example.com" username="user" privateKey="-----BEGIN OPENSSH PRIVATE KEY-----..." passphrase="keypassword"

# 2. Execute commands
ssh_exec sessionName="myserver" command="ls -la"
ssh_exec sessionName="myserver" command="htop"

# 3. Get monitoring URL for real-time terminal
ssh_get_monitoring_url sessionName="myserver"
# Returns: http://localhost:8082/session/myserver

# 4. List all active sessions
ssh_list_sessions

# 5. Disconnect when done
ssh_disconnect sessionName="myserver"

交互式Web终端

浏览器界面提供完全交互式的终端体验：

终端输入和导航

直接命令输入 -直接在终端中键入命令，就像本机SSH客户端一样
本地回应 -当您移动光标键入时，字符会立即出现
命令行编辑 -使用箭头键、主页、结束和退格键进行完全编辑
终端锁定 -界面在命令执行期间锁定，完成后解锁

实时功能

实时输出流 -通过WebSocket实时查看命令结果
并发命令 -用户键入的命令和Claude Code命令无缝执行
会话同步 -多个浏览器窗口保持同步
命令历史记录 -完整的历史记录，包括时间戳和退出代码

高性能

消息来源 -终端跟踪命令是来自用户输入还是克劳德代码
队列管理 -命令按顺序执行，不混合输出
状态持久性 -在浏览器重新连接时保持会话状态
清洁输出显示器 -单一命令输出，无重复或格式问题

用法：导航到监控URL并与终端交互，就像本地SSH会话一样。键入命令，按Enter键，立即查看结果。Claude Code还可以在同一会话中执行命令而不受干扰。

SSH身份验证方法

服务器支持多种SSH身份验证方法，并具有自动回退功能：

1.SSH密钥文件（推荐）

最适合：常规使用、自动化部署、具有安全意识的用户
支持：RSA、ED25519、ECDSA密钥格式
加密：加密密钥（带密码）和未加密密钥
路径扩展：支持波浪号扩展(~/.ssh/id_rsa)

# Unencrypted key
ssh_connect name="prod" host="server.com" username="deploy" keyFilePath="~/.ssh/id_ed25519"

# Encrypted key with passphrase
ssh_connect name="secure" host="server.com" username="admin" keyFilePath="~/.ssh/id_rsa" passphrase="mysecretpass"

2.用户名/密码

最适合：快速测试、一次性连接、遗留系统
安全说明：安全性低于基于密钥的身份验证

ssh_connect name="test" host="server.com" username="user" password="password"

3.直接私钥内容（遗留）

最适合：程序化使用，带密钥管理的CI/CD系统
备注：需要粘贴完整的私钥内容

ssh_connect name="ci" host="server.com" username="deploy" privateKey="-----BEGIN OPENSSH PRIVATE KEY-----..."

身份验证优先级

privateKey （如有提供）-最高优先级
keyFilePath （如有提供）-推荐方法
password （如有提供）-回退方法

配置

环境变量

SSH_TIMEOUT -SSH操作超时（毫秒）（默认值：30000）
MAX_SESSIONS -最大并发SSH会话数（默认值：10）
LOG_LEVEL -日志记录级别：“错误”、“警告”、“信息”、“调试”（默认值：“信息”）

Web服务器端口由安装脚本自动发现和管理。

发展

设置开发环境

# Install dependencies
npm install

# Run in development mode with auto-reload
npm run dev

# Run tests
npm test

# Run E2E tests (requires SSH server on localhost)
npm run test:e2e

# Build for production
npm run build

# Lint code
npm run lint

测试要求

要运行测试，您需要：

SSH服务器在本地主机上运行
测试用户帐户： test_user 带密码 password123
或者在测试文件中配置自己的测试凭据

项目结构

├── src/
│   ├── mcp-server.ts              # Main server orchestrator
│   ├── mcp-ssh-server.ts          # MCP protocol handler  
│   ├── web-server-manager.ts      # Web interface server + WebSocket handlers
│   ├── ssh-connection-manager.ts  # SSH session management + command queuing
│   └── types.ts                   # TypeScript definitions + command source types
├── static/                        # Interactive xterm.js terminal interface
│   ├── terminal-input-handler.js  # Browser input handling and state management
│   └── [xterm.js assets]          # Terminal rendering components
├── plans/
│   ├── interactive-terminal-epic.md # Complete implementation documentation
│   └── [other planning docs]      # Additional project planning
├── tests/                         # Comprehensive test suite
│   ├── story*.test.ts             # User story validation tests
│   ├── e2e-*.test.ts             # End-to-end functionality tests
│   └── manual-tests/             # Manual testing scripts and plans
├── install-mcp.sh                 # Installation script
└── dist/                          # Compiled output

安全考虑

SSH会话仅保存在内存中
凭据未持久化
默认情况下，Web界面在本地主机上运行
尽可能使用SSH密钥身份验证

建筑

总体设计

SSH MCP服务器实现了一个复杂的架构，将Claude Code的MCP工具与交互式浏览器终端无缝集成：

┌─────────────────┐    stdio    ┌─────────────────┐    WebSocket    ┌─────────────────┐
│   Claude Code   │◄──────────►│   MCP Server    │◄──────────────►│ Browser Terminal│
└─────────────────┘   commands  └─────────────────┘   bidirectional └─────────────────┘
                                          │
                                          ▼
                                ┌─────────────────┐
                                │ SSH Connection  │
                                │    Manager      │
                                │  (with Queue)   │
                                └─────────────────┘
                                          │
                                          ▼ 
                                ┌─────────────────┐
                                │  Remote SSH     │
                                │     Server      │
                                └─────────────────┘

核心组件

MCP服务器：通过stdio协议处理Claude Code通信（无网络端口）
Web服务器：通过HTTP和WebSocket提供交互式终端接口
SSH连接管理器：具有命令队列的集中式会话管理
交互式终端：带输入处理的基于浏览器的xterm.js接口

主要建筑特征

1. 统一指挥执行

Claude Code工具和浏览器用户输入都通过相同的SSH会话执行
命令按FIFO顺序排队，以防止输出交织
源归因跟踪命令是来自“用户”还是“克劳德”

2. 实时通信

MCP协议：Claude Code和服务器之间的stdio传输
网络套接字：浏览器和服务器之间的双向通信
SSH连接：具有流式输出的持久shell通道

3. 状态管理

会话保持：SSH会话维护所有命令源的状态
终端同步：多个浏览器客户端保持同步
队列管理：命令按顺序执行，并进行适当的清理

港口管理

MCP通信：仅使用stdio传输（带Claude代码的stdin/stdout）
web界面：单个自动发现端口同时服务于HTTP路由和WebSocket连接
端口发现：安装脚本发现可用端口并存储为 WEB_PORT 环境变量
URL生成：MCP工具返回指向web界面的监视URL

交互式终端架构

浏览器侧组件

xterm.js终端：渲染具有完全VT100兼容性的终端接口
输入处理：管理键盘输入、本地回显和命令提交
WebSocket客户端：处理与服务器的双向通信
状态管理器：跟踪终端锁定/解锁状态和命令执行

服务器端处理

WebSocket处理程序：处理来自浏览器的终端输入消息
命令路由器：将命令路由到具有源属性的SSH连接管理器
输出广播器：将命令结果流回到所有连接的客户端
队列协调员：确保混合命令源的正确执行顺序

部署模式

生产：使用SSH工具时，Claude Code会自动按需启动服务器
发展：使用独立端口发现进行手动测试
交互模式：浏览器客户端可以连接现有的SSH会话并与之交互

数据流

克劳德代码命令: ssh_exec → MCP服务器→ SSH管理器→ 队列→ SSH会话
浏览器命令：终端输入→ 网络套接字→ Web服务器→ SSH管理器→ 队列→ SSH会话
输出流：SSH会话→ SSH管理器→ 网络套接字→ 浏览器终端
状态更新：命令完成→ 终端解锁（仅适用于用户命令）

故障排除

常见问题

注册后服务器未启动：

# Check if Claude Code recognizes the server
claude mcp list

# Verify build exists
ls -la dist/src/mcp-server.js

# Test the server directly
node dist/src/mcp-server.js

端口冲突：

# Re-run installation to discover new port
./install-mcp.sh

# Verify new configuration
claude mcp get ssh

SSH连接失败：

验证SSH服务器是否正在运行且可访问
检查凭据（用户名/密码或私钥）
如果使用密码，请确保SSH服务器允许密码身份验证

Web界面不可访问：

使用 ssh_get_monitoring_url 获取当前端口的正确URL
检查服务器是否正在运行： ps aux | grep mcp-server

日志和调试

# Enable debug logging when using Claude Code
export LOG_LEVEL=debug

# Check MCP server configuration
claude mcp get ssh

# Test server manually with debug output
LOG_LEVEL=debug node dist/src/mcp-server.js

许可证

MIT许可证-请参阅许可证文件以获取详细信息。