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
- Environment Variables: Support for credentials via environment variables for secure CI/CD integration
- Batch Execution: Execute multiple commands in sequence with a single tool call
Tools List
| Tool | Description |
|---|---|
| execute-command | Execute SSH commands with optional cwd and sudo support |
| execute-batch | Execute multiple commands in sequence with a single call |
| read-file | Read file contents from remote server with line range support |
| write-file | Write content to files on remote server with append mode |
| upload | Upload local files to remote server via SFTP |
| download | Download files from remote server via SFTP |
| test-connection | Test SSH connectivity and return server info |
| get-status | Get comprehensive system status (CPU, memory, disk, OS, processes) |
| check-port | Check if ports are open/listening on remote server |
| list-servers | List all configured SSH connections |
Usage
MCP Configuration Examples
Important: In MCP configuration files, each command line argument and its value must be separate elements in the
argsarray. Do NOT combine them with spaces. For example, use"--host", "192.168.1.1"instead of"--host 192.168.1.1".
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)
-t, --timeout Default command timeout in milliseconds (default: 30000)
Environment Variables (alternative to CLI options):
SSH_HOST SSH server host address
SSH_PORT SSH server port (default: 22)
SSH_USERNAME SSH username
SSH_PASSWORD SSH password
SSH_PRIVATE_KEY SSH private key file path
SSH_PASSPHRASE Private key passphrase
SSH_WHITELIST Command whitelist
SSH_BLACKLIST Command blacklist
SSH_SOCKS_PROXY SOCKS proxy server address
SSH_TIMEOUT Default command timeout in milliseconds
Using Password
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": [
"-y",
"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",
"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",
"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",
"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",
"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",
"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 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" }
]
Test Connection
Use the test-connection tool to verify SSH connectivity before running commands:
{
"tool": "test-connection",
"params": {
"connectionName": "prod"
}
}
Example response:
{
"success": true,
"connectionTime": "245ms",
"server": {
"host": "192.168.1.1",
"port": 22,
"username": "root",
"hostname": "my-server"
}
}
Batch Command Execution
Use the execute-batch tool to run multiple commands in sequence:
{
"tool": "execute-batch",
"params": {
"commands": ["cd /var/log", "ls -la", "df -h"],
"connectionName": "prod",
"stopOnError": true
}
}
Example response:
{
"summary": {
"total": 3,
"executed": 3,
"succeeded": 3,
"failed": 0
},
"results": [
{ "command": "cd /var/log", "success": true, "output": "", "executionTime": "12ms" },
{ "command": "ls -la", "success": true, "output": "...", "executionTime": "15ms" },
{ "command": "df -h", "success": true, "output": "...", "executionTime": "18ms" }
]
}
Using Environment Variables
For CI/CD pipelines or secure deployments, you can use environment variables instead of CLI arguments:
{
"mcpServers": {
"ssh-mcp-server": {
"command": "npx",
"args": ["-y", "ssh-mcp-server"],
"env": {
"SSH_HOST": "192.168.1.1",
"SSH_PORT": "22",
"SSH_USERNAME": "root",
"SSH_PASSWORD": "pwd123456"
}
}
}
}
Working Directory and Sudo
The execute-command tool supports cwd and sudo parameters:
{
"tool": "execute-command",
"params": {
"cmdString": "ls -la",
"cwd": "/var/log",
"sudo": true
}
}
Read Remote File
Read file contents with optional line range:
{
"tool": "read-file",
"params": {
"path": "/etc/nginx/nginx.conf",
"maxLines": 50,
"startLine": 10
}
}
Write Remote File
Write content to remote files:
{
"tool": "write-file",
"params": {
"path": "/tmp/config.txt",
"content": "key=value\nother=setting",
"append": false,
"createDirs": true
}
}
Get Server Status
Get comprehensive system information:
{
"tool": "get-status",
"params": {}
}
Returns: hostname, OS, CPU, memory, disk, processes, services, uptime, and more.
Check Port
Check if a port is open:
{
"tool": "check-port",
"params": {
"port": 80,
"host": "localhost"
}
}
Example response:
{
"port": 80,
"host": "localhost",
"open": true,
"service": "nginx",
"pid": "1234"
}
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
--whitelistoption 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-serveris 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
uploadanddownloadcommands.