agent-ssh

SSH 远程管理 CLI 工具，支持在远程服务器上执行命令和传输文件。可独立作为 CLI 使用，也可作为 MCP Server 运行。

安装

全局安装

npm install -g agent-ssh
agent-ssh --help

本地安装

npm install
npm run build
node dist/cli.js --help

本地 link（发布前）

npm link
agent-ssh --help

CLI 命令

| 命令 | 功能 | |------|------| | exec <command> | 远程执行命令 | | upload <local> <remote> | 上传文件 | | download <remote> <local> | 下载文件 | | upload-dir <local> <remote> | 上传目录 | | download-dir <remote> <local> | 下载目录 | | list-servers | 列出已配置的服务器 | | read <path> | 读取远程文件内容（支持行偏移和限制） | | write <path> <content> | 写入/覆盖远程文件（自动创建目录） | | edit <path> | 精确替换远程文件内容（原子化多段替换） | | find <pattern> | 在远程服务器上按 glob 模式查找文件 | | grep <pattern> | 在远程服务器上搜索文件内容 | | ls [path] | 列出远程目录内容 | | --mcp | 以 MCP Server 模式运行 |

使用示例

# 使用配置文件中的服务器
agent-ssh exec "df -h" -s production
agent-ssh upload ./file.txt /root/file.txt -s development
agent-ssh download /var/log/app.log ./logs/ -s production
agent-ssh list-servers

# 文件操作
agent-ssh read /etc/hostname -s production
agent-ssh write /tmp/test.txt "hello world" -s production
agent-ssh edit /etc/nginx.conf --old "worker 1" --new "worker 4" -s production
agent-ssh find "*.log" --path /var/log -s production
agent-ssh grep "error" --path /var/log --glob "*.log" -C 3 -s production
agent-ssh ls /etc -s production

# 直接指定连接参数
agent-ssh exec "ls -la" -H 192.168.1.100 -u root -p password
agent-ssh upload ./deploy.sh /opt/deploy.sh -H 192.168.1.100 -u root --private-key ~/.ssh/id_rsa

# 后台运行（进程在连接关闭后继续存活）
agent-ssh exec "node server.js" --detach -s production
agent-ssh exec "python bot.py" --bg -s production  # --bg 是 --detach 的别名

# JSON 格式输出
agent-ssh exec "uname -a" -s production --json
agent-ssh read /etc/hostname --json -s production
agent-ssh find "*.conf" --path /etc --json -s production

新增命令详解

read — 读取远程文件

# 读取完整文件
agent-ssh read /var/log/syslog -s production

# 从第 100 行开始读取 20 行（offset 是 0-based）
agent-ssh read /var/log/syslog --offset 100 --limit 20 -s production

# JSON 输出
agent-ssh read /etc/hostname --json -s production

write — 写入远程文件

# 写入简单内容
agent-ssh write /tmp/config.json '{"debug": true}' -s production

# 自动创建父目录
agent-ssh write /opt/app/config/settings.yml "key: value" -s production

注意：写入复杂多行内容时，建议先用 exec 创建文件，或通过 upload 上传本地文件。

edit — 编辑远程文件（精确替换、原子化）

# 单段替换
agent-ssh edit /etc/hosts --old "127.0.0.1" --new "0.0.0.0" -s production

# 多段替换（通过 JSON 文件）
cat > edits.json << 'EOF'
[
  {"oldText": "version: 1", "newText": "version: 2"},
  {"oldText": "port: 80", "newText": "port: 443"}
]
EOF
agent-ssh edit /etc/myapp/config.yml --edits-file edits.json -s production

# 显示 unified diff
agent-ssh edit /tmp/test.txt --old "hello" --new "world" --show-diff -s production

安全特性：oldText 必须精确匹配且在文件中唯一出现。如果验证失败，远程文件不会被修改。

find — 查找远程文件

# 按扩展名查找
agent-ssh find "*.log" --path /var/log -s production

# 限制结果数量
agent-ssh find "*.conf" --path /etc --limit 5 -s production

# JSON 输出（包含文件大小和修改时间）
agent-ssh find "*.js" --path /var/www --json -s production

grep — 搜索远程文件内容

# 基本搜索
agent-ssh grep "root" --path /etc -s production

# 大小写不敏感 + 限定文件类型
agent-ssh grep "error" --path /var/log --glob "*.log" --ignore-case -s production

# 带上下文行
agent-ssh grep "TODO" --path /var/www/src -C 3 -s production

# 固定字符串搜索（非正则）
agent-ssh grep "special[chars]" --path /etc --literal -s production

注意：-p 短选项已被 --password 占用，搜索路径请使用 --path。

ls — 列出远程目录

# 列出默认目录（/root）
agent-ssh ls -s production

# 列出指定目录
agent-ssh ls /etc -s production

# JSON 输出（包含类型、大小、权限、修改时间等元数据）
agent-ssh ls /var/log --json -s production

配置文件

创建 .agent-ssh/config.json 在命令执行的目录下：

{
  "servers": {
    "production": {
      "host": "192.168.1.100",
      "port": 22,
      "username": "root",
      "password": "your_password",
      "timeout": 60000
    },
    "development": {
      "host": "192.168.1.50",
      "port": 2222,
      "username": "admin",
      "privateKey": "/path/to/id_rsa",
      "timeout": 30000
    }
  },
  "defaultServer": "development"
}

配置文件搜索顺序

1. AGENTS_SSH_CLI_CONFIG 环境变量指定路径
2. 当前目录下的 .agent-ssh/config.json
3. 项目目录下的 ssh-cli.config.json
4. 当前目录下的 ssh-cli.config.json
5. 用户主目录下的 .ssh-cli-config.json

配置参数说明

| 参数 | 必填 | 默认值 | 说明 | |------|------|--------|------| | host | 是 | - | SSH 服务器地址 | | port | 否 | 22 | SSH 端口 | | username | 是 | - | 用户名 | | password | 否 | - | 密码（与 privateKey 二选一） | | privateKey | 否 | - | 私钥路径或内容（与 password 二选一） | | timeout | 否 | 30000 | 超时时间（毫秒） |

认证方式

支持两种认证方式，password 和 privateKey 二选一即可：

密码认证：

agent-ssh exec "ls" -H 192.168.1.100 -u root -p mypassword

私钥认证：

agent-ssh exec "ls" -H 192.168.1.100 -u root -k ~/.ssh/id_rsa

MCP Server 模式

保留完整的 MCP 协议兼容性，可作为 Agent 的 MCP Server 使用。

agent-ssh --mcp

可用 MCP 工具

| 工具 | 说明 | |------|------| | ssh_list_servers | 列出所有已配置的服务器 | | ssh_execute_command | 执行命令 | | ssh_upload_file | 上传文件 | | ssh_download_file | 下载文件 | | ssh_upload_directory | 上传目录 | | ssh_download_directory | 下载目录 | | ssh_read_file | 读取远程文件内容（支持 offset/limit） | | ssh_write_file | 写入/覆盖远程文件（自动创建目录） | | ssh_edit_file | 编辑远程文件（原子化多段精确替换） | | ssh_find_files | 按 glob 模式查找远程文件 | | ssh_grep | 搜索远程文件内容（支持上下文/通配符） | | ssh_list_dir | 列出远程目录内容 |

MCP 客户端配置

{
  "mcpServers": {
    "agent-ssh": {
      "command": "agent-ssh",
      "args": ["--mcp"]
    }
  }
}