Skip to main content
Glama
deenesjakoruzh
oaslananka

mcp-ssh-tool

by oaslananka
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

mcp-ssh-tool

LobeHub npm version Official MCP Registry License: MIT npm downloads

一个模型上下文协议 (MCP) SSH 客户端服务器，为 GitHub Copilot 和 VS Code 提供自主 SSH 操作。无需手动提示或 GUI 交互即可实现自然语言 SSH 自动化。

官方 MCP 注册表条目：io.github.oaslananka/mcp-ssh-tool
注册表元数据：https://registry.modelcontextprotocol.io/v0.1/servers/io.github.oaslananka%2Fmcp-ssh-tool/versions/latest

快速入门

安装

  • 全局安装（推荐）：npm install -g mcp-ssh-tool

  • 一次性运行：npx mcp-ssh-tool

MCP 客户端配置（VS Code / Claude Desktop / 其他）

添加到您的 MCP 配置（mcp.json、.vscode/mcp.json 或 Claude Desktop MCP 配置）中：

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

使用示例

配置完成后，您可以使用自然语言与您的 MCP 客户端进行交互：

  • SSH 连接：“使用 SSH 密钥以 admin 身份连接到服务器 192.168.1.100”

  • 文件操作：“读取服务器上 /etc/nginx/nginx.conf 的内容”

  • 命令执行：“在远程服务器上运行 'systemctl status nginx'”

  • 软件包管理：“在 Ubuntu 服务器上安装 htop 软件包”

  • 服务控制：“重启 nginx 服务”

  • Claude Desktop：“连接到我的服务器并检查磁盘使用情况”

  • 安装软件包/服务栈：“在我的远程服务器上安装 nginx”

  • 读取配置文件：“读取文件 /etc/nginx/nginx.conf”

  • 重启服务：“重启 nginx 服务”

  • 浏览日志：“列出 /var/log 中的文件”

可用工具

  • ssh_open_session - 使用各种身份验证方法建立 SSH 连接

  • ssh_close_session - 关闭 SSH 会话

  • ssh_list_sessions - 列出所有活动的 SSH 会话

  • ssh_ping - 检查会话是否存活且响应正常

  • ssh_list_configured_hosts - 列出 ~/.ssh/config 中的主机

  • ssh_resolve_host - 解析 SSH 配置中的主机别名

  • proc_exec - 远程执行命令（带有可选超时）

  • proc_sudo - 以 sudo 权限执行命令

  • fs_read, fs_write, fs_list, fs_stat, fs_mkdirp, fs_rmrf, fs_rename - 文件系统操作

  • ensure_package - 具有 present 和 absent 状态的软件包管理

  • ensure_service - 包括 restarted 在内的服务控制

  • ensure_lines_in_file - 具有 present 和 absent 状态的文件行管理

  • patch_apply - 将补丁应用于文件

  • os_detect - 系统信息检测

  • get_metrics - JSON 或 Prometheus 格式的服务器指标

  • proc_exec_stream - 带有分块输出的流式命令执行

  • file_upload, file_download - SFTP 文件传输助手

  • tunnel_local_forward, tunnel_remote_forward, tunnel_close, tunnel_list - 隧道管理

可用资源

  • mcp-ssh-tool://sessions/active - 以 JSON 格式显示的活动会话

  • mcp-ssh-tool://metrics/json - 以 JSON 格式显示的指标快照

  • mcp-ssh-tool://metrics/prometheus - Prometheus 指标导出

  • mcp-ssh-tool://ssh-config/hosts - 解析后的本地 SSH 主机别名

概述

SSH MCP 服务器充当 GitHub Copilot 与通过 SSH 连接的远程系统之间的桥梁。它支持：

  • 非交互式 SSH 操作 - 无需提示或 GUI 交互

  • 多种身份验证方法 - 密码、SSH 密钥或 SSH 代理

  • 会话管理 - 具有 TTL 和 LRU 驱逐机制的自动连接池

  • 文件系统操作 - 通过 SFTP 读取、写入、列出和管理远程文件，对于未公开 SFTP 子系统的主机，提供 SSH shell 回退方案

  • 进程执行 - 远程运行命令和 sudo 操作

  • 高级自动化 - 软件包管理、服务控制和配置管理

  • 安全性 - 自动屏蔽日志中的敏感数据

架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  GitHub Copilot │────│  SSH MCP Server  │────│  Remote Systems │
│     / VS Code   │    │                  │    │   (via SSH)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │ MCP stdio protocol    │ Session management    │ SSH + optional SFTP
         │                       │ LRU cache + TTL       │
         │                       │ Auth strategies       │

嵌入式 / BusyBox 目标

一些嵌入式目标公开了 SSH 命令执行，但未提供 SFTP 子系统，这在基于 Dropbear 或 BusyBox 的系统中很常见。在这种情况下，ssh_open_session 仍然会成功并报告 sftpAvailable: false。核心文件工具（如 fs_read、fs_write、fs_stat、fs_list、fs_mkdirp、fs_rmrf 和 fs_rename）会自动回退到基于 shell 的实现。

安装

先决条件

  • Node.js ≥ 20 (LTS)

  • 目标系统的 SSH 访问权限

  • 用于身份验证的 SSH 密钥或凭据

从 npm 安装

npm install -g mcp-ssh-tool

从源码构建

git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm install
npm run build
npm link

CLI 标志

  • --help / -h：显示用法和示例。

  • --version / -v：打印版本。

  • --stdio：强制使用 stdio 模式（默认）。

注意： 这是一个 MCP stdio 服务器。终端不是交互式 shell；请使用 MCP 客户端（Claude Desktop、VS Code MCP 等）或通过 stdio 发送 JSON-RPC。

平台说明

  • Linux / macOS： 使用带有安全引用的 POSIX shell 包装器。默认临时目录：/tmp。

  • Windows 目标： 需要 OpenSSH 服务器/代理；密钥发现会检查 C:\Users\<you>\.ssh\。命令已包装以实现 PowerShell 安全执行。软件包/服务助手在 Windows 目标上被有意禁用。

  • 主机密钥： 默认放宽主机密钥检查。设置 STRICT_HOST_KEY_CHECKING=true 并可选地设置 KNOWN_HOSTS_PATH 以强制执行验证。

ChatGPT Desktop 集成

快速设置

npm run setup:chatgpt

此命令会自动配置 ChatGPT Desktop 以使用 mcp-ssh-tool。

手动设置

添加到您的 ChatGPT Desktop MCP 配置中：

  • macOS：~/Library/Application Support/ChatGPT/mcp.json

  • Windows：%APPDATA%\ChatGPT\mcp.json

  • Linux：~/.config/chatgpt/mcp.json

{
  "mcpServers": {
    "ssh-mcp-server": {
      "name": "ssh-mcp-server",
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

有关详细用法，请参阅 docs/chatgpt-usage.md。

Codex 集成

快速设置

全局安装该软件包，然后将其注册到 Codex：

npm install -g mcp-ssh-tool
codex mcp add ssh-mcp -- mcp-ssh-tool

如果您不想全局安装，可以通过 npx 注册它：

codex mcp add ssh-mcp -- npx -y mcp-ssh-tool

验证

检查 Codex 是否能看到 MCP 服务器：

codex mcp list
codex mcp get ssh-mcp

您应该会看到一个已启用的 stdio 服务器，其命令为 mcp-ssh-tool 或 npx。

可选的安全加固

要在 Codex 管理的服务器进程中强制执行主机密钥验证：

codex mcp remove ssh-mcp
codex mcp add ssh-mcp \
  --env STRICT_HOST_KEY_CHECKING=true \
  --env KNOWN_HOSTS_PATH=/path/to/known_hosts \
  -- mcp-ssh-tool

添加服务器后，重启 Codex 或打开一个新会话，然后尝试简单的工具调用，例如列出活动会话或打开 SSH 连接。

VS Code Copilot 集成

用户级配置（推荐）

打开 VS Code 并按 Ctrl+Shift+P，然后运行 "MCP: Open User Configuration"。

添加到您的 mcp.json 中：

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

工作区级配置

在您的工作区中创建 .vscode/mcp.json：

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

验证

  1. 重启 VS Code

  2. 打开 Copilot Chat

  3. SSH MCP 工具应出现在可用工具列表中

  4. 测试：“以 admin 身份连接到 192.168.1.100 并运行 'uname -a'”

Claude Desktop、Antigravity 和其他 MCP 客户端

任何能够启动 stdio 服务器的 MCP 兼容客户端都可以使用 mcp-ssh-tool。 确切的设置界面或配置文件因客户端而异，但过程相同：

  1. 安装软件包：

npm install -g mcp-ssh-tool

  1. 注册一个启动以下命令的 stdio MCP 服务器：

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

  1. 如果客户端使用 mcpServers 风格的模式而不是 servers，请使用等效条目：

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

对于 Claude Desktop，在其 MCP 配置中使用上述相同的 stdio 命令模式。 对于 Antigravity 或其他 MCP 客户端，请使用客户端自己的 MCP 设置 UI 或配置格式，但将其指向相同的可执行命令。

使用示例

基本连接和命令执行

"Connect to 10.11.12.13 as deployer with password 'mypass' and run 'df -h'"

文件操作

"Connect to server.example.com as admin, read /etc/nginx/nginx.conf and show me the server blocks"

系统管理

"Connect to 192.168.1.50 as root, install htop package, start nginx service, and list /var/www contents"

配置管理

"Connect to web-server as admin, add these lines to /etc/hosts:
192.168.1.10 db-server
192.168.1.20 cache-server
Then restart networking service"

即用型提示词建议

"connect to my server and check disk usage"
"install nginx on my remote server"
"read the file /etc/nginx/nginx.conf"
"restart the nginx service"
"list files in /var/log"

专业提示

  • 多个会话：每个主机或环境打开一个会话，并在您在生产、预发布和开发机器之间切换时，使用 ssh_list_sessions 和 ssh_ping 保持它们处于活动状态。

  • 针对 BusyBox/Dropbear 的 SFTP 回退：在未公开 SFTP 子系统的嵌入式系统上，ssh_open_session 仍然可以成功并返回 sftpAvailable: false，核心 fs_* 工具会自动回退到基于 shell 的实现。

  • 主机密钥验证：在 MCP 服务器环境中设置 STRICT_HOST_KEY_CHECKING=true，并可选地设置 KNOWN_HOSTS_PATH 以进行更严格的生产级 SSH 验证。

API 参考

架构

src/
├── container.ts       - Dependency injection wiring
├── config.ts          - ConfigManager (env + programmatic overrides)
├── index.ts           - CLI entry point & graceful shutdown
├── mcp.ts             - MCP server (thin: delegates to ToolRegistry)
├── tools/
│   ├── registry.ts    - ToolRegistry (routes CallTool requests)
│   ├── types.ts       - ToolProvider interface
│   ├── session.provider.ts
│   ├── process.provider.ts
│   ├── fs.provider.ts
│   ├── ensure.provider.ts
│   ├── system.provider.ts
│   ├── transfer.provider.ts
│   └── tunnel.provider.ts
├── session.ts         - SessionManager (LRU cache + TTL)
├── resources.ts       - MCP resources for sessions, metrics, and SSH hosts
├── telemetry.ts       - Optional OpenTelemetry tracing
├── rate-limiter.ts    - Sliding window rate limiter
├── metrics.ts         - Prometheus-compatible metrics
├── safety.ts          - Command safety warnings (non-blocking)
└── ...                - fs-tools, process, ensure, detect, ...

添加新的工具组

  1. 创建实现 ToolProvider 的 src/tools/<your-namespace>.provider.ts

  2. 在 src/tools/index.ts 中注册它

  3. 将单元测试添加到 test/unit/tools/<your-namespace>.provider.test.ts

无需更改 mcp.ts。

会话工具

ssh_open_session

{
  "host": "example.com",
  "username": "admin",
  "port": 22,
  "auth": "auto",
  "password": "optional",
  "privateKey": "optional-inline-key",
  "privateKeyPath": "optional-path",
  "passphrase": "optional",
  "useAgent": false,
  "readyTimeoutMs": 20000,
  "ttlMs": 900000
}

返回：

{
  "sessionId": "ssh-1645123456789-1",
  "host": "example.com",
  "username": "admin",
  "expiresInMs": 900000
}

ssh_close_session

{
  "sessionId": "ssh-1645123456789-1"
}

ssh_list_sessions, ssh_ping, ssh_list_configured_hosts, ssh_resolve_host

  • ssh_list_sessions 返回带有剩余 TTL 的活动会话。

  • ssh_ping 检查会话的存活性和延迟。

  • ssh_list_configured_hosts 读取 ~/.ssh/config。

  • ssh_resolve_host 将 SSH 主机别名扩展为连接参数。

命令工具

proc_exec

{
  "sessionId": "ssh-1645123456789-1",
  "command": "ls -la /home",
  "cwd": "/tmp",
  "env": {
    "DEBUG": "1"
  },
  "timeoutMs": 30000
}

proc_sudo

{
  "sessionId": "ssh-1645123456789-1",
  "command": "systemctl restart nginx",
  "password": "sudo-password",
  "cwd": "/etc",
  "timeoutMs": 30000
}

两者均返回：

{
  "code": 0,
  "stdout": "command output",
  "stderr": "",
  "durationMs": 245
}

文件工具

  • fs_read

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "encoding": "utf8"
}

  • fs_write

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/tmp/config.txt",
  "data": "server_name example.com;\nlisten 80;",
  "mode": 420
}

  • fs_stat 返回 size、mtime、mode 和 type。

  • fs_list 返回 { "entries": [...], "nextToken": "optional" }。

  • fs_mkdirp 递归创建目录。

  • fs_rmrf 递归删除文件或目录。

  • fs_rename 重命名或移动路径。

配置和自动化工具

ensure_package

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "present",
  "sudoPassword": "optional"
}

state 支持 present 和 absent。

ensure_service

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "restarted",
  "sudoPassword": "optional"
}

state 支持 started、stopped、restarted、enabled 和 disabled。

ensure_lines_in_file

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "lines": [
    "192.168.1.10 db-server",
    "192.168.1.20 cache-server"
  ],
  "state": "present",
  "createIfMissing": true,
  "sudoPassword": "optional"
}

state 支持 present 和 absent。

patch_apply

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "diff": "@@ -1 +1 @@\n-old\n+new"
}

os_detect

返回远程平台、发行版、版本、软件包管理器、初始化系统、shell 和临时目录。

get_metrics

返回服务器指标。默认输出为 JSON；可选的 { "format": "prometheus" } 会发出 Prometheus 文本格式。

身份验证

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

身份验证策略优先级

  1. 密码（如果提供）

  2. SSH 密钥（内联 → 路径 → 自动发现）

  3. SSH 代理（如果可用）

SSH 密钥自动发现

服务器会自动在以下位置搜索 SSH 密钥：

  • ~/.ssh/id_ed25519

  • ~/.ssh/id_rsa

  • ~/.ssh/id_ecdsa

注意： 由于安全考虑，不再支持 DSA 密钥 (id_dsa)。

自定义密钥目录：设置 SSH_DEFAULT_KEY_DIR 环境变量。

示例

密码身份验证：

{
  "host": "server.com",
  "username": "admin",
  "auth": "password",
  "password": "secret"
}

SSH 密钥（内联）：

{
  "host": "server.com",
  "username": "admin",
  "auth": "key",
  "privateKey": "-----BEGIN PRIVATE KEY-----\n...",
  "passphrase": "optional"
}

SSH 密钥（文件路径）：

{
  "host": "server.com",
  "username": "admin",
  "auth": "key",
  "privateKeyPath": "/home/user/.ssh/id_rsa"
}

SSH 代理：

{
  "host": "server.com",
  "username": "admin",
  "auth": "agent"
}

配置

环境变量

变量

描述

默认值

LOG_LEVEL

日志级别 (error, warn, info, debug)

info

LOG_FORMAT

日志输出格式 (plain, json)

plain

STRICT_HOST_KEY_CHECKING

启用严格的 SSH 主机密钥验证

false

KNOWN_HOSTS_PATH

自定义 known_hosts 文件路径

~/.ssh/known_hosts

Install Server
A
security – no known vulnerabilities
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/oaslananka/mcp-ssh-tool'

If you have feedback or need assistance with the MCP directory API, please join our Discord server