SSH MCP

SSH MCP + 本地 Web 面板：配置多台 Linux 服务器，多选激活后供 Cursor / AI 通过 MCP 操作。

功能

• MCP 工具：list_servers / list_active_servers / exec / upload / download / list_dir / read_file / write_file / test_connection / process_list / process_kill / port_listeners / disk_usage / system_info / service_status / service_restart / tail_log / file_stat / mkdir / rm / mv / cp
• exec 支持 sudo: true
• GUI：服务器 CRUD、密码/私钥认证、多选激活、连接测试
• 凭据本地 AES-GCM 加密存储（data/master.key + data/servers.json）

安装（npm）

npm i -g @renqf/sshmcp
sshmcp mcp    # MCP stdio（Cursor 用）
sshgui        # GUI/API，默认打开浏览器（等同 sshmcp api）

Cursor MCP 配置示例：

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

或用 npx（无需全局安装）：

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@renqf/sshmcp", "mcp"]
    }
  }
}

本地开发

npm install
npm run api          # http://127.0.0.1:3789  （启动后自动打开 GUI）
npm run gui:dev      # http://127.0.0.1:5179  （开发态 GUI，代理到 API）
npm run mcp          # stdio MCP server
npm test

启动 API 时默认自动打开浏览器面板；若不需要自动打开，设置 SSHMCP_OPEN_BROWSER=0。

生产一体启动：

npm run build
sshgui
# 或: npm run api / sshmcp api
# 打开 http://127.0.0.1:3789

Cursor MCP 配置示例（开发态）

{
  "mcpServers": {
    "sshmcp": {
      "command": "npx",
      "args": ["tsx", "src/mcp/server.ts"],
      "cwd": "C:/Users/rqf/Desktop/sshmcp"
    }
  }
}

生产安装后更简单：

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

确保 GUI（sshgui）与 MCP（sshmcp）默认共用用户目录下的同一份配置；一般无需再设 SSHMCP_DATA_DIR。

AI 使用约定

1. 操作前先调用 list_servers 或 list_active_servers（二者均只返回当前激活池；未激活的不出现）
2. 所有操作工具必须传 serverId，且该 id 必须在当前激活池中
3. 多选激活 = 可用池，不是「一条命令打全部机器」
4. 要让某台机器出现在 MCP 列表里：在 GUI 勾选激活后再操作
5. 进程管理：process_list / process_kill / port_listeners；查 root 占用的端口进程名时加 sudo: true
6. 系统/文件：disk_usage / system_info / service_status / service_restart（默认 sudo）/ tail_log / file_stat / mkdir / rm / mv / cp

环境变量

| 变量 | 默认 | 说明 | |------|------|------| | SSHMCP_DATA_DIR | Windows: %APPDATA%\sshmcpmacOS/Linux: ~/.config/sshmcp | 配置与密钥目录（可选覆盖） | | SSHMCP_API_PORT | 3789 | HTTP API 端口 | | SSHMCP_OPEN_BROWSER | 开启 | 设为 0/false 可关闭启动时自动打开 GUI |