# XTerminal_mcp

**Repository Path**: saku/xterminal_mcp

## Basic Information

- **Project Name**: XTerminal_mcp
- **Description**: 面向服务器代码调试场景的完整操作指南。把 XTerminal 里已保存的 SSH 连接交给 AI 客户端（Claude Desktop / Cursor / Claude Code），让 AI 直接在你的服务器上执行命令、读写文件、上传下载。
 建议先用 config.json 白名单限定主机，并在对话里明确允许操作的范围（如只动 /www/myapp）。高危操作（删库、rm -rf）请人工确认。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ssh-mcp-server

把 XTerminal 里已保存的 SSH 连接，通过 **MCP（Model Context Protocol）** 暴露给外部 AI 客户端（Claude Desktop、Cursor、Claude Code 等），让 AI 可以直接在你的服务器上执行命令、读写文件、上传下载、浏览目录树 —— 特别适合 **PHP/Web 代码调试**。

> 📖 完整中文操作手册见 **[docs/USAGE.md](docs/USAGE.md)**（含 PHP 调试工作流与示例）。

```
AI 客户端 (Claude Desktop / Cursor / Claude Code)
   │  MCP stdio (JSON-RPC over stdin/stdout)
   ▼
ssh-mcp-server (Node.js 进程)
   ├─ src/index.js   MCP 服务器：注册 12 个工具
   ├─ src/hosts.js   只读解析 XTerminal 连接库（sql.js，WebAssembly SQLite）
   ├─ src/ssh.js     ssh2 封装：连接、执行命令、SFTP
   ▼
%APPDATA%\XTerminal\sqlite\local-store.db   ← 你已保存的 SSH 连接（含凭据）
        └────────── SSH 直连你的服务器
```

## 要求

- Windows + Node.js >= 20（已测试 v20.20.2）
- 本机已安装并登录过 XTerminal（连接数据在 `%APPDATA%\XTerminal\sqlite\local-store.db`）

## 安装

```powershell
cd E:\soft\ssh-mcp-server
npm install
```

## 注册到 AI 客户端

本服务器以 **stdio 子进程**方式由 AI 客户端启动，不需要手动运行。

### Claude Desktop

编辑 `claude_desktop_config.json`（`%APPDATA%\Claude\claude_desktop_config.json`），加入：

```json
{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["E:\\soft\\ssh-mcp-server\\src\\index.js"]
    }
  }
}
```

### Cursor

Settings → MCP → Add new MCP server：

- Type：`command`
- Command：`node`
- Arguments：`E:\soft\ssh-mcp-server\src\index.js`

### Claude Code（CLI）

```bash
claude mcp add ssh -- node E:\soft\ssh-mcp-server\src\index.js
```

## 工具清单（12 个）

| 工具 | 参数 | 说明 |
|---|---|---|
| `ssh_list_hosts` | 无 | 列出 XTerminal 已保存的连接（id/标题/host/端口/用户名，**不含密码**） |
| `ssh_exec` | host, command, timeout?, cwd? | 执行命令，返回 stdout/stderr/退出码（默认 60s 超时） |
| `ssh_sftp_list` | host, path? | 列出远程目录 |
| `ssh_sftp_read` | host, path | 读取远程**文本**文件（UTF-8，上限 5MB） |
| `ssh_sftp_write` | host, path, content | 写入远程文本文件 |
| `ssh_sftp_stat` | host, path | 远程文件信息 |
| `ssh_sftp_upload` | host, localPath, remotePath | 上传**本地文件**到远程（支持二进制） |
| `ssh_sftp_download` | host, remotePath, localPath, maxBytes? | 下载远程文件到本机（支持二进制，默认上限 50MB） |
| `ssh_sftp_tree` | host, path, depth? | 递归目录树（默认深度 3，上限 10，不跟随链接） |
| `ssh_sftp_mkdir` | host, path | 逐级创建远程目录（等同 `mkdir -p`） |
| `ssh_sftp_delete` | host, path, recursive? | 删除远程文件/目录（recursive 递归删除） |
| `ssh_sftp_rename` | host, fromPath, toPath | 重命名/移动远程文件或目录 |

`host` 参数可填连接 id、标题或 host。`localPath`/`localPath` 是 **MCP server 所在电脑**上的路径。

## 配置

### 环境变量

| 变量 | 说明 |
|---|---|
| `XTERMINAL_DB_PATH` | 覆盖 XTerminal 数据库路径（默认 `%APPDATA%\XTerminal\sqlite\local-store.db`） |
| `XTERMINAL_CONFIG` | 覆盖配置文件路径（默认项目根 `config.json`） |

### 主机白名单（可选）

复制 `config.example.json` 为 `config.json`，只允许指定主机被 AI 使用：

```json
{
  "hosts": {
    "allow": ["主机id1", "主机标题2"]
  }
}
```

不在白名单的主机，工具调用会被拒绝。

## 测试

```powershell
cd E:\soft\ssh-mcp-server
npm test
```

覆盖：连接库解析（样例 + 真实 db）、ssh2 参数组装与错误路径、MCP 握手/tools/list（12 工具）/白名单。
手动端到端验证脚本见 `e2e-manual.js`（`node e2e-manual.js`）：真实连接服务器验证 exec + SFTP 全流程
（含 upload/download/mkdir/delete 写操作，仅在 `/tmp` 与 `E:\work\temp` 的 `ssh-mcp-e2e-*` 临时文件内进行，用完即删）。

## ⚠️ 安全警告（务必阅读）

- **XTerminal 的 SSH 密码是明文存储的**，本工具读取并使用它们（仅在内存中，任何工具输出都不含密码）。
- **把本 server 注册给某个 AI 客户端，等于把其中所有服务器的控制权交给该 AI** —— AI 可以执行任意命令（包括破坏性命令）、读写删除任意文件，无需额外确认。
- 只在本机、只注册给你信任的客户端；不要把配置给远程/共享/不可信的客户端使用。
- 建议先用 `config.json` 白名单限定可访问的主机，并在对话中给 AI 明确的操作边界。
- 本工具**只读** XTerminal 数据，不会修改你的连接配置。

## 已知限制

- 不支持多跳代理（`sshProxyChain`）——调用时会明确报错。
- `authType` 为登录凭证（credential）等其他类型暂不支持。
- `ssh_sftp_read` 仅支持文本（UTF-8）且上限 5MB；大文件/二进制请用 `upload`/`download`。
- 密码/密钥来自 XTerminal 数据库；若 XTerminal 更新了存储格式，需同步更新 `src/hosts.js`。