🔐 ssh-mcp-server

SSH-based MCP (Model Context Protocol) server that allows remote execution of SSH commands via the MCP protocol.

📝 Project Overview

ssh-mcp-server is a bridging tool that enables AI assistants and other applications supporting the MCP protocol to execute remote SSH commands through a standardized interface. This allows AI assistants to safely operate remote servers, execute commands, and retrieve results without directly exposing SSH credentials to AI models.

✨ Key Features

• 🔒 Secure Connections: Supports multiple secure SSH connection methods, including password authentication and private key authentication (with passphrase support)
• 🛡️ Command Security Control: Precisely control the range of allowed commands through flexible blacklist and whitelist mechanisms to prevent dangerous operations
• 🔄 Standardized Interface: Complies with MCP protocol specifications for seamless integration with AI assistants supporting the protocol
• 📂 File Transfer: Supports bidirectional file transfers, uploading local files to servers or downloading files from servers
• 🔑 Credential Isolation: SSH credentials are managed entirely locally and never exposed to AI models, enhancing security
• 🚀 Ready to Use: Can be run directly using NPX without global installation, making it convenient and quick to deploy

🛠️ Tools List

| Tool | Name | Description | |---------|-----------|----------| | execute-command | Command Execution Tool | Execute SSH commands on remote servers and get results | | upload | File Upload Tool | Upload local files to specified locations on remote servers | | download | File Download Tool | Download files from remote servers to local specified locations | | list-servers | List Servers Tool | List all available SSH server configurations | | upload-async | Async File Upload Tool | Upload files asynchronously and get a task ID for monitoring | | check-upload-status | Check Upload Status Tool | Check the status of an asynchronous file upload |

📚 Usage

🔧 MCP Configuration Examples

⚠️ Important: In MCP configuration files, each command line argument and its value must be separate elements in the args array. Do NOT combine them with spaces. For example, use "--host", "192.168.1.1" instead of "--host 192.168.1.1".

ℹ️ MCP Protocol Integration: This server integrates with AI assistants and other tools that support the Model Context Protocol (MCP). Once configured, these tools can securely execute commands and transfer files on remote SSH servers through standardized MCP tool calls.

⚙️ Command Line Options

Options:
  -h, --host              SSH server host address
  -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)
  --default-local-path    Default local path for file uploads and downloads
  --default-remote-path   Default remote path for file uploads and downloads

#### 🔑 Using Password

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

🔐 Using Private Key

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

🔏 Using Private Key with Passphrase

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

🌐 Using SOCKS Proxy

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

📝 Using Command Whitelist and Blacklist

Use the --whitelist and --blacklist parameters to restrict the range of executable commands. Multiple patterns are separated by commas. Each pattern is a regular expression used to match commands.

Example: Using Command Whitelist

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

Example: Using Command Blacklist

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

Note: If both whitelist and blacklist are specified, the system will first check whether the command is in the whitelist, and then check whether it is in the blacklist. The command must pass both checks to be executed.

📁 Using Default Upload and Download Directories

您可以为文件上传和下载指定默认目录。在上传/下载操作中使用相对路径时，将使用这些默认目录作为基础路径：

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@zenglp/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--default-local-path", "/target/",
        "--default-remote-path", "/data/"
      ]
    }
  }
}

使用此配置时，当您在上传工具中未指定本地路径时，将使用 /home/user/local 作为默认路径。同样，在下载工具中未指定远程路径时，将使用 /home/user/remote 作为默认路径。

🔄 异步文件上传

对于大文件上传，可以使用异步上传功能，避免超时问题。上传工具会自动检测文件大小，当文件大于20MB时，会自动使用异步上传方法：

{
  "tool": "upload",
  "arguments": {
    "localPath": "/path/to/large/file.zip",
    "remotePath": "/remote/path/file.zip",
    "connectionName": "default"
  }
}

如果文件大于20MB，系统会自动返回任务ID，而不是等待上传完成：

{
  "content": [
    {
      "type": "text",
      "text": "File is 25.50MB (larger than 20MB), using async upload. Task ID: upload_1623456789012_abc123def. Use check-upload-status tool to monitor progress."
    }
  ]
}

然后可以使用 check-upload-status 工具检查上传状态：

{
  "tool": "check-upload-status",
  "arguments": {
    "taskId": "upload_1623456789012_abc123def",
    "connectionName": "default"
  }
}

对于小于20MB的文件，上传工具会使用传统的同步方法，直接返回上传结果。

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

使用 upload-async 工具启动异步上传：

{
  "tool": "upload-async",
  "arguments": {
    "localPath": "/path/to/large/file.zip",
    "remotePath": "/remote/path/file.zip",
    "connectionName": "default"
  }
}

返回示例：

{
  "content": [
    {
      "type": "text",
      "text": "Upload started successfully. Task ID: upload_1623456789012_abc123def. Use check-upload-status tool to monitor progress."
    }
  ]
}

使用 check-upload-status 工具检查上传状态：

{
  "tool": "check-upload-status",
  "arguments": {
    "taskId": "upload_1623456789012_abc123def",
    "connectionName": "default"
  }
}

返回示例：

{
  "taskId": "upload_1623456789012_abc123def",
  "status": "in-progress",
  "progress": 45,
  "totalSize": 104857600,
  "uploadedSize": 47185920,
  "remoteFileSize": 47185920,
  "startTime": "2023-06-12T10:30:00.000Z",
  "localPath": "/path/to/large/file.zip",
  "remotePath": "/remote/path/file.zip",
  "error": null
}

🧩 多SSH连接用法示例

可以通过多次 --ssh 参数指定多个SSH连接，每个连接需有唯一name。您也可以为每个连接指定默认的上传和下载目录：

npx @zenglp/ssh-mcp-server \
  --ssh "name=dev,host=1.2.3.4,port=22,user=alice,password=xxx,defaultLocalPath=/home/alice/files,defaultRemotePath=/home/alice/remote" \
  --ssh "name=prod,host=5.6.7.8,port=22,user=bob,password=yyy,defaultLocalPath=/home/bob/files,defaultRemotePath=/home/bob/remote"

在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）

这对于像 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" }
]