@bingzi-233/ssh-mcp 1.2.0 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +65 -73
- package/dist/forward.js +108 -0
- package/dist/index.js +1138 -232
- package/dist/sftp-ops.js +160 -0
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,109 +1,101 @@
|
|
|
1
1
|
# ssh-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
纯命令行 SSH/SFTP 工具：在多台远程服务器上执行命令、传输大文件（断点续传）、端口转发、文件管理。支持 CLI 模式和 MCP stdio 模式（`--mcp`）。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@bingzi-233/ssh-mcp)
|
|
6
|
+
[](https://nodejs.org)
|
|
7
|
+
[](https://www.typescriptlang.org)
|
|
8
|
+
[](https://github.com/BingZi-233/ssh-mcp/stargazers)
|
|
9
|
+
[](https://github.com/BingZi-233/ssh-mcp/blob/master/LICENSE)
|
|
10
|
+
[](https://linux.do)
|
|
6
11
|
|
|
7
|
-
|
|
8
|
-
|---|---|
|
|
9
|
-
| `list_servers` | 列出所有已配置的服务器（name / 描述 / 地址 / 用户，**不含密码私钥**） |
|
|
10
|
-
| `run_command` | 在指定 `name` 的服务器上执行一条命令，返回 stdout / stderr / 退出码 |
|
|
11
|
-
| `open_session` | 建立到服务器的长连接会话，返回会话 id 供 `run_command` 复用 |
|
|
12
|
-
| `close_session` | 关闭长连接会话 |
|
|
13
|
-
| `list_sessions` | 列出当前所有活跃的长连接会话 |
|
|
14
|
-
| `upload_file` | 上传本机文件到远程（后台任务，支持断点续传） |
|
|
15
|
-
| `download_file` | 从远程下载文件到本机（后台任务，支持断点续传） |
|
|
16
|
-
| `transfer_status` | 查询传输进度（已传字节、百分比、速度、ETA、状态） |
|
|
17
|
-
| `cancel_transfer` | 取消一个进行中的传输（已传部分保留，可续传） |
|
|
18
|
-
|
|
19
|
-
> - **长连接**：用 `open_session` 建立持久连接，`run_command` 传入 `session` 参数复用，省去重复握手和认证开销。即便复用了连接，每条命令仍在独立 channel 中执行，工作目录和环境变量不保留。
|
|
20
|
-
> - **安全策略**：内置拦截 `rm -rf /`、`dd` 写块设备、`mkfs`、fork 炸弹等高危命令。可在 `servers.json` 的 `security.blocked_patterns` 中追加自定义正则。传入 `force=true` 可绕过。
|
|
21
|
-
> - 命令在独立会话中执行，**命令之间不保留工作目录和环境变量**。需要保持上下文时自行串接，例如 `cd /var/www && git pull`。
|
|
22
|
-
> - 大文件传输是**后台任务**：`upload_file`/`download_file` 立即返回一个传输 id，用 `transfer_status` 轮询进度，不阻塞。
|
|
23
|
-
> - **断点续传**基于目标文件的实际大小：对同一对路径再次发起传输会自动从已传字节处继续，进程重启后依然有效。
|
|
24
|
-
|
|
25
|
-
---
|
|
26
|
-
|
|
27
|
-
## 安装
|
|
28
|
-
|
|
29
|
-
### 方式一：作为 Claude Code 插件（推荐）
|
|
30
|
-
|
|
31
|
-
```shell
|
|
32
|
-
/plugin marketplace add BingZi-233/ssh-mcp
|
|
33
|
-
/plugin install ssh-mcp@bingzi-plugins
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
插件会通过 `npx` 拉起已发布的 npm 包，因此**需要先把包发布到 npm**（见下文「发布到 npm」）。
|
|
37
|
-
|
|
38
|
-
### 方式二：作为 MCP 服务器手动注册
|
|
39
|
-
|
|
40
|
-
```bash
|
|
41
|
-
claude mcp add ssh -- npx -y @bingzi-233/ssh-mcp
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
需要自定义配置文件路径时：
|
|
12
|
+
## CLI 快速上手
|
|
45
13
|
|
|
46
14
|
```bash
|
|
47
|
-
|
|
15
|
+
npm i -g @bingzi-233/ssh-mcp
|
|
16
|
+
|
|
17
|
+
ssh-mcp list-servers # 列出服务器
|
|
18
|
+
ssh-mcp run-command -s prod-web -c "df -h /" # 执行命令
|
|
19
|
+
ssh-mcp batch --servers web1,web2,web3 -c "uptime" # 批量执行
|
|
20
|
+
ssh-mcp upload -s prod-web -l ./dist.tar.gz -r /tmp/ # 上传文件
|
|
21
|
+
ssh-mcp ls -s prod-web -p /var/log # 列出目录
|
|
22
|
+
ssh-mcp forward -s prod-web -L 8080:192.168.1.5:80 # 端口转发
|
|
48
23
|
```
|
|
49
24
|
|
|
50
|
-
|
|
25
|
+
## 命令一览
|
|
51
26
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
27
|
+
| 子命令 | 用途 |
|
|
28
|
+
|---|---|
|
|
29
|
+
| `list-servers` | 列出所有已配置的服务器 |
|
|
30
|
+
| `run-command` | 在远程服务器上执行命令 |
|
|
31
|
+
| `batch` | 在多台服务器上批量执行同一命令 |
|
|
32
|
+
| `open-session` / `close-session` / `list-sessions` | 长连接会话管理 |
|
|
33
|
+
| `upload` / `download` | 大文件传输（后台任务，断点续传） |
|
|
34
|
+
| `transfer-status` / `cancel-transfer` | 传输进度与取消 |
|
|
35
|
+
| `forward` / `list-forwards` / `close-forward` | SSH 端口转发（本地/远程） |
|
|
36
|
+
| `ls` / `stat` | 列出远程目录、查看文件信息 |
|
|
37
|
+
| `rm` / `mkdir` | 删除远程文件/目录、创建远程目录 |
|
|
57
38
|
|
|
58
|
-
|
|
39
|
+
每个子命令运行 `ssh-mcp <子命令> --help` 查看详细用法。
|
|
59
40
|
|
|
60
|
-
##
|
|
41
|
+
## 配置 servers.json
|
|
61
42
|
|
|
62
|
-
|
|
43
|
+
默认从运行目录下 `./servers.json` 读取，或设置环境变量 `SSH_MCP_CONFIG`。
|
|
63
44
|
|
|
64
45
|
```json
|
|
65
46
|
{
|
|
66
|
-
"security": {
|
|
67
|
-
"blocked_patterns": []
|
|
68
|
-
},
|
|
47
|
+
"security": { "blocked_patterns": [] },
|
|
69
48
|
"servers": [
|
|
70
49
|
{
|
|
71
50
|
"name": "prod-web",
|
|
72
|
-
"description": "生产环境
|
|
51
|
+
"description": "生产环境",
|
|
73
52
|
"host": "192.168.1.10",
|
|
74
53
|
"port": 22,
|
|
75
54
|
"username": "deploy",
|
|
76
55
|
"privateKeyPath": "~/.ssh/id_rsa"
|
|
77
|
-
},
|
|
78
|
-
{
|
|
79
|
-
"name": "db",
|
|
80
|
-
"description": "数据库服务器",
|
|
81
|
-
"host": "db.example.com",
|
|
82
|
-
"username": "admin",
|
|
83
|
-
"password": "your-password"
|
|
84
56
|
}
|
|
85
57
|
]
|
|
86
58
|
}
|
|
87
59
|
```
|
|
88
60
|
|
|
89
|
-
|
|
61
|
+
鉴权优先级：私钥 → 密码 → ssh-agent。修改配置无需重启。
|
|
90
62
|
|
|
91
|
-
|
|
92
|
-
2. `password` —— 密码登录
|
|
93
|
-
3. 都没配 → 回退到本机 `ssh-agent`（读 `SSH_AUTH_SOCK`）
|
|
63
|
+
## 端口转发
|
|
94
64
|
|
|
95
|
-
|
|
65
|
+
```bash
|
|
66
|
+
# 本地转发：本机 8080 → 经 SSH 服务器 → 内网 192.168.1.5:80
|
|
67
|
+
ssh-mcp forward -s prod-web -L 8080:192.168.1.5:80
|
|
96
68
|
|
|
97
|
-
|
|
69
|
+
# 远程转发：SSH 服务器 9000 → 回传到本机 localhost:3000
|
|
70
|
+
ssh-mcp forward -s prod-web -R 9000:127.0.0.1:3000
|
|
71
|
+
|
|
72
|
+
ssh-mcp list-forwards
|
|
73
|
+
ssh-mcp close-forward -i f1
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## 批量执行
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
ssh-mcp batch --servers prod-web,prod-api,prod-worker -c "systemctl status nginx"
|
|
80
|
+
```
|
|
98
81
|
|
|
99
|
-
##
|
|
82
|
+
## 安全策略
|
|
83
|
+
|
|
84
|
+
内置拦截高危命令：`rm -rf /`、`dd` 写块设备、`mkfs`、fork 炸弹。在 `servers.json` 的 `security.blocked_patterns` 中追加自定义正则。传 `--force` 跳过检查。
|
|
85
|
+
|
|
86
|
+
## MCP 模式
|
|
87
|
+
|
|
88
|
+
以 MCP stdio 服务运行（供 Claude Code 等 AI 客户端调用）：
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
claude mcp add ssh -- npx -y @bingzi-233/ssh-mcp --mcp
|
|
92
|
+
/plugin marketplace add BingZi-233/ssh-mcp
|
|
93
|
+
/plugin install ssh-mcp@bingzi-plugins
|
|
94
|
+
```
|
|
100
95
|
|
|
101
|
-
|
|
96
|
+
## 社区
|
|
102
97
|
|
|
103
|
-
|
|
104
|
-
- 优先用私钥或 `ssh-agent`，尽量不在配置里写明文密码。
|
|
105
|
-
- 给 SSH 账号最小权限；高危机器考虑用受限账号。
|
|
106
|
-
- 内置命令安全策略会拦截 `rm -rf /`、`dd` 写块设备、`mkfs`、fork 炸弹等高危模式。可在 `security.blocked_patterns` 中追加自定义正则（JSON 字符串，需双重转义，如 `"rm\\\\s.*-rf?\\\\s+/\\\\*"`）。传 `force=true` 可绕过。
|
|
98
|
+
本项目由 [LINUX DO](https://linux.do) 社区孵化并认可。
|
|
107
99
|
|
|
108
100
|
## License
|
|
109
101
|
|
package/dist/forward.js
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
import { createServer, Socket } from "node:net";
|
|
2
|
+
import { createConnection } from "./ssh.js";
|
|
3
|
+
const forwards = new Map();
|
|
4
|
+
/** 存活的本地 net.Server / SSH 连接，用于关闭 */
|
|
5
|
+
const resources = new Map();
|
|
6
|
+
let counter = 0;
|
|
7
|
+
function track(id, conn, server) {
|
|
8
|
+
resources.set(id, { conn, server });
|
|
9
|
+
conn.on("close", () => {
|
|
10
|
+
const f = forwards.get(id);
|
|
11
|
+
if (f)
|
|
12
|
+
f.state = "stopped";
|
|
13
|
+
server?.close();
|
|
14
|
+
});
|
|
15
|
+
conn.on("error", () => {
|
|
16
|
+
const f = forwards.get(id);
|
|
17
|
+
if (f)
|
|
18
|
+
f.state = "stopped";
|
|
19
|
+
server?.close();
|
|
20
|
+
});
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* 启动端口转发。
|
|
24
|
+
*
|
|
25
|
+
* type=local: 监听本机 localPort，流量经 SSH 服务器转发到 remoteHost:remotePort。
|
|
26
|
+
* type=remote: SSH 服务器监听 remotePort，流量经本机转发到 localHost:localPort。
|
|
27
|
+
*/
|
|
28
|
+
export async function startForward(cfg, type, localHost, localPort, remoteHost, remotePort) {
|
|
29
|
+
const conn = await createConnection(cfg, 20_000);
|
|
30
|
+
const id = `f${++counter}`;
|
|
31
|
+
if (type === "local") {
|
|
32
|
+
await new Promise((resolve, reject) => {
|
|
33
|
+
const server = createServer((socket) => {
|
|
34
|
+
conn.forwardOut(localHost, localPort, remoteHost, remotePort, (err, stream) => {
|
|
35
|
+
if (err) {
|
|
36
|
+
socket.destroy();
|
|
37
|
+
return;
|
|
38
|
+
}
|
|
39
|
+
socket.pipe(stream).pipe(socket);
|
|
40
|
+
stream.on("error", () => socket.destroy());
|
|
41
|
+
socket.on("error", () => stream.destroy());
|
|
42
|
+
});
|
|
43
|
+
});
|
|
44
|
+
server.on("error", reject);
|
|
45
|
+
server.listen(localPort, localHost, () => {
|
|
46
|
+
server.removeListener("error", reject);
|
|
47
|
+
track(id, conn, server);
|
|
48
|
+
resolve();
|
|
49
|
+
});
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
else {
|
|
53
|
+
// remote: SSH 服务器暴露端口，转发回本机
|
|
54
|
+
await new Promise((resolve, reject) => {
|
|
55
|
+
conn.forwardIn(remoteHost, remotePort, (err) => {
|
|
56
|
+
if (err)
|
|
57
|
+
reject(err);
|
|
58
|
+
else {
|
|
59
|
+
track(id, conn);
|
|
60
|
+
resolve();
|
|
61
|
+
}
|
|
62
|
+
});
|
|
63
|
+
});
|
|
64
|
+
// 处理来自远程的入站连接
|
|
65
|
+
conn.on("tcp connection", (info, accept) => {
|
|
66
|
+
const stream = accept();
|
|
67
|
+
const sock = new Socket();
|
|
68
|
+
sock.connect(remotePort, localHost, () => {
|
|
69
|
+
sock.pipe(stream).pipe(sock);
|
|
70
|
+
stream.on("error", () => sock.destroy());
|
|
71
|
+
sock.on("error", () => stream.destroy());
|
|
72
|
+
});
|
|
73
|
+
sock.on("error", () => stream.end());
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
const fwd = {
|
|
77
|
+
id,
|
|
78
|
+
server: cfg.name,
|
|
79
|
+
type,
|
|
80
|
+
localHost,
|
|
81
|
+
localPort,
|
|
82
|
+
remoteHost,
|
|
83
|
+
remotePort,
|
|
84
|
+
state: "running",
|
|
85
|
+
createdAt: Date.now(),
|
|
86
|
+
};
|
|
87
|
+
forwards.set(id, fwd);
|
|
88
|
+
return fwd;
|
|
89
|
+
}
|
|
90
|
+
export function getForward(id) {
|
|
91
|
+
return forwards.get(id);
|
|
92
|
+
}
|
|
93
|
+
export function listForwards() {
|
|
94
|
+
return [...forwards.values()];
|
|
95
|
+
}
|
|
96
|
+
export function closeForward(id) {
|
|
97
|
+
const fwd = forwards.get(id);
|
|
98
|
+
if (!fwd || fwd.state === "stopped")
|
|
99
|
+
return false;
|
|
100
|
+
fwd.state = "stopped";
|
|
101
|
+
const res = resources.get(id);
|
|
102
|
+
if (res) {
|
|
103
|
+
res.server?.close();
|
|
104
|
+
res.conn.end();
|
|
105
|
+
resources.delete(id);
|
|
106
|
+
}
|
|
107
|
+
return true;
|
|
108
|
+
}
|