Ssh Mcp Server

What is Ssh Mcp Server about?

Ssh Mcp Server enables AI assistants and other MCP‑compatible applications to run commands on remote servers via SSH, retrieve outputs, and move files without exposing SSH credentials.

How to use Ssh Mcp Server?

1. Install/run the server with npx:

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

2. Provide connection details using command‑line options (host, port, username, password or privateKey, optional passphrase, socksProxy, whitelist/blacklist).
3. In MCP calls, specify the tool (execute-command, upload, download, list-servers) and parameters such as cmdString, connectionName, timeout, etc.
4. For multiple connections, pass repeated --ssh parameters with a unique name and refer to that name in tool calls.

Key features of Ssh Mcp Server

• Secure Connections: Password and private‑key authentication (with passphrase support).
• Command Security Control: Blacklist and whitelist regex filters to restrict executable commands.
• Standard MCP Interface: Compatible with any MCP‑aware AI assistant or tool.
• Bidirectional File Transfer: upload and download tools for moving files.
• Credential Isolation: Credentials stay on the server side, never exposed to the AI model.
• Zero‑Installation Run: Execute directly via npx without global install.
• Multi‑SSH Support: Manage several named connections simultaneously.
• Execution Timeout: Prevent hanging commands with configurable timeout.

Use cases of Ssh Mcp Server

• Allowing AI assistants to manage cloud or on‑premise servers (e.g., log inspection, service restarts) safely.
• Automating routine DevOps tasks such as deployments, configuration checks, or backups through an MCP‑driven workflow.
• Providing controlled remote file access for AI‑generated code snippets that need to read or write configuration files.
• Integrating secure command execution into custom chatbot interfaces for infrastructure troubleshooting.

FAQ from the Ssh Mcp Server

Q: Do I need to install the package globally? A: No. Use npx -y @fangjunjie/ssh-mcp-server to run it instantly.

Q: How can I restrict which commands are allowed? A: Use the --whitelist option with regex patterns; optionally add --blacklist for extra safety.

Q: Can I run commands on multiple servers at once? A: Define multiple connections with --ssh "name=...,host=...,port=...,user=...,password=..." and specify connectionName in each tool call.

Q: Is the private key stored on disk safe? A: The server reads the key into memory only; ensure the host machine is trusted and protect the key file.

Q: What about DoS protection? A: The server itself does not implement rate limiting; deploy behind a firewall or reverse proxy that provides such controls.

Q: How are file paths validated? A: The server includes checks against path traversal attacks, but you should still use absolute or vetted paths for upload/download.

🔐 ssh-mcp-server

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

English Document | 中文文档

📝 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

📦 Open Source Repository

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

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

🛠️ 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

📚 Usage

🔧 MCP Configuration Examples

⚙️ 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)

🔑 Using Password

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

🔐 Using Private Key

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

🔏 Using Private Key with Passphrase

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

🌐 Using SOCKS Proxy

{
  "mcpServers": {
    "ssh-mpc-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"
      ]
    }
  }
}

📝 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-mpc-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host 192.168.1.1",
        "--port 22",
        "--username root",
        "--password pwd123456",
        "--whitelist ^ls( .*)?,^cat .*,^df.*"
      ]
    }
  }
}

Example: Using Command Blacklist

{
  "mcpServers": {
    "ssh-mpc-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/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.

🧩 Multi-SSH Connection Example

You can specify multiple SSH connections by passing multiple --ssh parameters, each with a unique name:

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"

In MCP tool calls, specify the connection name via the connectionName parameter. If omitted, the default connection is used.

Example (execute command on 'prod' connection):

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

Example (execute command with timeout options):

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

⏱️ Command Execution Timeout

The execute-command tool supports timeout options to prevent commands from hanging indefinitely:

• timeout: Command execution timeout in milliseconds (optional, default is 30000ms)

This is particularly useful for commands like ping, tail -f, or other long-running processes that might block execution.

🗂️ List All SSH Servers

You can use the MCP tool list-servers to get all available SSH server configurations:

Example call:

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

Example response:

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

🛡️ Security Considerations

This server provides powerful capabilities to execute commands and transfer files on remote servers. To ensure it is used securely, please consider the following:

• Command Whitelisting: It is strongly recommended to use the --whitelist option to restrict the set of commands that can be executed. Without a whitelist, any command can be executed on the remote server, which can be a significant security risk.
• Private Key Security: The server reads the SSH private key into memory. Ensure that the machine running the ssh-mcp-server is secure. Do not expose the server to untrusted networks.
• Denial of Service (DoS): The server does not have built-in rate limiting. An attacker could potentially launch a DoS attack by flooding the server with connection requests or large file transfers. It is recommended to run the server behind a firewall or reverse proxy with rate-limiting capabilities.
• Path Traversal: The server has built-in protection against path traversal attacks on the local filesystem. However, it is still important to be mindful of the paths used in upload and download commands.