Skip to main content
Glama
deenesjakoruzh
classfang

ssh-mcp-server

by classfang
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

🔐 ssh-mcp-server

NPM Version GitHub forks GitHub Repo stars GitHub Issues or Pull Requests GitHub Issues or Pull Requests GitHub Issues or Pull Requests GitHub Issues or Pull Requests

基于 SSH 的 MCP（模型上下文协议）服务器，允许通过 MCP 协议远程执行 SSH 命令。

English Document | 中文文档

📝 项目概述

ssh-mcp-server 是一个桥接工具，使 AI 助手和其他支持 MCP 协议的应用程序能够通过标准化接口执行远程 SSH 命令。这使得 AI 助手可以在不直接向 AI 模型暴露 SSH 凭据的情况下，安全地操作远程服务器、执行命令并获取结果。

欢迎加入微信群：

wx_1.png

Related MCP server: SSH MCP Server

✨ 核心功能

  • 🔒 安全连接：支持多种安全的 SSH 连接方式，包括密码认证和私钥认证（支持密码短语）

  • 🛡️ 命令安全控制：通过灵活的黑名单和白名单机制精确控制允许执行的命令范围，防止危险操作

  • 🔄 标准化接口：符合 MCP 协议规范，可与支持该协议的 AI 助手无缝集成

  • 📂 文件传输：支持双向文件传输，可将本地文件上传至服务器或从服务器下载文件

  • 🔑 凭据隔离：SSH 凭据完全在本地管理，绝不会暴露给 AI 模型，增强了安全性

  • 🚀 开箱即用：无需全局安装，可直接使用 NPX 运行，部署方便快捷

📦 开源仓库

GitHub: https://github.com/classfang/ssh-mcp-server

NPM: https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server

🛠️ 工具列表

工具

名称

描述

execute-command

命令执行工具

在远程服务器上执行 SSH 命令并获取结果

upload

文件上传工具

将本地文件上传到远程服务器的指定位置

download

文件下载工具

将文件从远程服务器下载到本地指定位置

list-servers

服务器列表工具

列出所有可用的 SSH 服务器配置

📚 使用方法

🔧 MCP 配置示例

⚠️ 重要提示：在 MCP 配置文件中，每个命令行参数及其值必须是 args 数组中的独立元素。请勿使用空格将它们合并。例如，使用 "--host", "192.168.1.1" 而不是 "--host 192.168.1.1"。

⚙️ 命令行选项

Options:
  --config-file       JSON configuration file path (recommended for multiple servers)
  --ssh-config-file   SSH config file path (default: ~/.ssh/config)
  --ssh               SSH connection configuration (can be JSON string or legacy format)
  -h, --host          SSH server host address or alias from SSH config
  -p, --port          SSH server port
  -u, --username      SSH username
  -w, --password      SSH password
  -k, --privateKey    SSH private key file path
  -P, --passphrase    Private key passphrase (if any)
  -W, --whitelist     Command whitelist, comma-separated regular expressions
  -B, --blacklist     Command blacklist, comma-separated regular expressions
  -s, --socksProxy    SOCKS proxy server address (e.g., socks://user:password@host:port)
  --allowed-local-paths Additional allowed local paths for upload/download, comma-separated
  --pty               Allocate pseudo-tty for command execution (default: true)
  --pre-connect       Pre-connect to all configured SSH servers on startup

🔑 使用密码

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456"
      ]
    }
  }
}

🔐 使用私钥

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa"
      ]
    }
  }
}

🔏 使用带密码短语的私钥

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa",
        "--passphrase", "pwd123456"
      ]
    }
  }
}

📋 使用 ~/.ssh/config

你可以使用 ~/.ssh/config 文件中定义的主机别名。服务器将自动从 SSH 配置中读取连接参数：

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver"
      ]
    }
  }
}

假设你的 ~/.ssh/config 包含：

Host myserver
    HostName 192.168.1.1
    Port 22
    User root
    IdentityFile ~/.ssh/id_rsa

你也可以指定自定义的 SSH 配置文件路径：

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver",
        "--ssh-config-file", "/path/to/custom/ssh_config"
      ]
    }
  }
}

注意：命令行参数的优先级高于 SSH 配置文件中的值。例如，如果你指定了 --port 2222，它将覆盖 SSH 配置中的端口。

🌐 使用 SOCKS 代理

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--socksProxy", "socks://username:password@proxy-host:proxy-port"
      ]
    }
  }
}

📝 使用命令白名单和黑名单

使用 --whitelist 和 --blacklist 参数来限制可执行命令的范围。多个模式之间用逗号分隔。每个模式都是用于匹配命令的正则表达式。

示例：使用命令白名单

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--whitelist", "^ls( .*)?,^cat .*,^df.*"
      ]
    }
  }
}

示例：使用命令黑名单

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--blacklist", "^rm .*,^shutdown.*,^reboot.*"
      ]
    }
  }
}

注意：如果同时指定了白名单和黑名单，系统将首先检查命令是否在白名单中，然后再检查是否在黑名单中。命令必须通过这两项检查才能被执行。

🧩 多 SSH 连接示例

配置多个 SSH 连接有三种方式：

📄 方法 1：使用配置文件（推荐）

创建一个 JSON 配置文件（例如 ssh-config.json）：

数组格式：

[
  {
    "name": "dev",
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "{abc=P100s0}",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  {
    "name": "prod",
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "socksProxy": "socks://127.0.0.1:10808"
  }
]

对象格式：

{
  "dev": {
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "{abc=P100s0}",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  "prod": {
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "socksProxy": "socks://127.0.0.1:10808"
  }
}

然后使用 --config-file 参数：

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--config-file", "ssh-config.json"
      ]
    }
  }
}

🔧 方法 2：使用带 --ssh 参数的 JSON 格式

你可以直接传递 JSON 格式的配置字符串：

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--ssh", "{\"name\":\"dev\",\"host\":\"1.2.3.4\",\"port\":22,\"username\":\"alice\",\"password\":\"{abc=P100s0}\",\"socksProxy\":\"socks://127.0.0.1:10808\"}",
        "--ssh", "{\"name\":\"prod\",\"host\":\"5.6.7.8\",\"port\":22,\"username\":\"bob\",\"password\":\"yyy\",\"socksProxy\":\"socks://127.0.0.1:10808\"}"
      ]
    }
  }
}

📝 方法 3：传统的逗号分隔格式（向后兼容）

对于密码中不包含特殊字符的简单情况，你仍然可以使用传统格式：

npx @fangjunjie/ssh-mcp-server \
  --ssh "name=dev,host=1.2.3.4,port=22,user=alice,password=xxx" \
  --ssh "name=prod,host=5.6.7.8,port=22,user=bob,password=yyy"

⚠️ 注意：传统格式在密码包含 =, ,, {, } 等特殊字符时可能会出现问题。对于包含特殊字符的密码，请使用方法 1 或方法 2。

在 MCP 工具调用中，通过 connectionName 参数指定连接名称。如果省略，则使用默认连接。

示例（在 'prod' 连接上执行命令）：

{
  "tool": "execute-command",
  "params": {
    "cmdString": "ls -al",
    "connectionName": "prod"
  }
}

示例（带超时选项执行命令）：

{
  "tool": "execute-command",
  "params": {
    "cmdString": "ping -c 10 127.0.0.1",
    "connectionName": "prod",
    "timeout": 5000
  }
}

⏱️ 命令执行超时

execute-command 工具支持超时选项，以防止命令无限期挂起：

  • timeout：命令执行超时时间（毫秒，可选，默认为 30000ms）

  • 错误响应包含稳定的 code、message 和 retriable 字段，以便于代理端处理

这对于 ping、tail -f 或其他可能阻塞执行的长时间运行进程特别有用。

🗂️ 列出所有 SSH 服务器

你可以使用 MCP 工具 list-servers 获取所有可用的 SSH 服务器配置：

调用示例：

{
  "tool": "list-servers",
  "params": {}
}

响应示例：

[
  { "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" },
  { "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" }
]

🛡️ 安全注意事项

本服务器提供了在远程服务器上执行命令和传输文件的强大功能。为确保安全使用，请考虑以下几点：

  • 命令白名单：强烈建议使用 --whitelist 选项来限制可执行的命令集。如果没有白名单，任何命令都可以在远程服务器上执行，这可能带来重大的安全风险。

  • 私钥安全：服务器会将 SSH 私钥读取到内存中。请确保运行 ssh-mcp-server 的机器是安全的。不要将服务器暴露给不受信任的网络。

  • 拒绝服务 (DoS)：服务器没有内置速率限制。攻击者可能会通过向服务器发送大量连接请求或大文件传输来发起 DoS 攻击。建议在具有速率限制功能的防火墙或反向代理后运行服务器。

  • 路径遍历：服务器内置了针对本地文件系统路径遍历攻击的保护。但仍需注意在 upload 和 download 命令中使用的路径。

  • 本地传输范围：默认情况下，本地文件传输仅限于当前工作目录。仅对明确受信任的目录使用 --allowed-local-paths 或配置中的 allowedLocalPaths。

🌟 Star 历史

Star History Chart

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityActive
ResponsivenessSlow

Resources

Related MCP Connectors

Related MCP Servers

  • MCP SSH Server

    shaike1
    F
    license
    Not graded
    quality
    F
    maintenance
    A secure SSH server implementation for Model Context Protocol that enables remote command execution and file operations, supporting both password and key-based authentication.
    57
    -

  • SSH MCP Server

    tufantunc
    A
    license
    A
    quality
    A
    maintenance
    A Model Context Protocol server that allows LLMs to securely execute shell commands on remote Linux and Windows systems via SSH. It supports password and key-based authentication, command timeouts, and sudo elevation for administrative tasks.
    14
    6,535 npm
    747
    MIT

  • ssh-mcp-server

    ZachFlint
    A
    license
    A
    quality
    C
    maintenance
    Enables AI assistants to securely execute remote SSH commands, perform file transfers, and monitor system status through a standardized interface. It features robust security controls including command whitelisting, blacklisting, and credential isolation to prevent unauthorized operations.
    10
    8 npm
    MIT

  • mcpx

    rmednitzer
    A
    license
    B
    quality
    A
    maintenance
    A Model Context Protocol server for complete shell and SSH mastery, enabling command execution, interactive sessions, file transfer, and port forwarding with auditing and policy controls.
    18
    1
    Apache 2.0