SSH MCP Server

A Model Context Protocol (MCP) server for executing commands on remote servers via SSH, built with TypeScript and Node.js. Provides comprehensive tools for SSH command execution, Kubernetes management, and connection pooling.

Features

• Dual Authentication - SSH key and password authentication support (resolved from hosts.json + env vars)
• 8 MCP Tools - Complete coverage of SSH operations
• Persistent Connections - Efficient connection pooling and reuse
• Host Aliases - Pre-configure named hosts with connection details
• Pattern Hosts - Use kubemaster-p13-us-east style aliases for dynamic hostname generation
• Opt-in Approval - Windows VBS popup approval via SSH_APPROVAL=true
• Kubernetes Support - Specialized kubectl command execution on kubemaster nodes
• Batch Execution - Run up to 5 commands in parallel
• TypeScript - Full type safety and modern ES modules

Installation

Using npm (Global)

npm install -g @hbarhate/ssh-mcp-server

Using npx (No Installation)

npx @hbarhate/ssh-mcp-server

Updating

Update Global Installation

npm update -g @hbarhate/ssh-mcp-server

Update to Latest with npx

npx @hbarhate/ssh-mcp-server@latest

Check Current Version

npm list -g @hbarhate/ssh-mcp-server

Configuration

Configure the server using environment variables or configuration files.

Environment Variables

export MCP_HOSTS_CONFIG_PATH="/path/to/hosts.json"
export SSH_DEFAULT_USER="myuser"
export SSH_PASSWORD_MYUSER="<encrypted-password>"
export SSH_APPROVAL="true"

| Variable | Description | Required | | ------------------------- | ---------------------------------------------------------------------------- | -------- | | MCP_HOSTS_CONFIG_PATH | Path to hosts.json (defaults to ./hosts.json in project root) | No | | SSH_DEFAULT_USER | Default SSH user when no user is configured per-host or via hosts.json | No | | SSH_PASSWORD_<USER> | Encrypted password for SSH authentication (e.g., SSH_PASSWORD_MYUSER) | No | | SSH_PASSWORD | Generic encrypted password fallback (used if per-user env var not found) | No | | SSH_APPROVAL | Set to true to enable VBS approval popup before executing commands | No |

Host Configuration File

Create hosts.json to define host aliases:

{
  "hosts": {
    "k8s-prod": {
      "host": "kubemaster01.p13.eng.us-east.example.com",
      "user": "myuser",
      "authType": "password",
      "description": "Kubernetes master (password from SSH_PASSWORD_MYUSER env var)"
    },
    "dev-server": {
      "host": "10.0.0.2",
      "user": "ubuntu",
      "authType": "password",
      "plainPassword": "ubuntu",
      "description": "Dev server with inline password (less secure)"
    },
    "jumpbox": {
      "host": "10.0.1.100",
      "user": "ubuntu",
      "authType": "key",
      "keyPath": "~/.ssh/jumpbox_rsa",
      "passphrase": "optional-passphrase",
      "description": "Jump server (key auth)"
    }
  }
}

MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop, Windsurf, Cursor):

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": ["@hbarhate/ssh-mcp-server"],
      "env": {
        "MCP_HOSTS_CONFIG_PATH": "/path/to/hosts.json",
        "SSH_DEFAULT_USER": "myuser",
        "SSH_PASSWORD_MYUSER": "<encrypted-password>",
        "SSH_APPROVAL": "false"
      }
    }
  }
}

Tools Reference

SSH Execution

| Tool | Description | Parameters | | --------------------------- | ---------------------------------------- | -------------------------------------------------------- | | ssh_execute | Execute command on remote server | host, command, dryRun? | | ssh_execute_batch | Execute up to 5 commands in parallel | executions (array of {host, command} objects) | | ssh_kubectl | Execute kubectl on kubemaster nodes | pod, region, command |

Connection Management

| Tool | Description | Parameters | | --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------- | | ssh_connection_status | Get status of persistent connections | - | | ssh_close_connection | Close a specific SSH connection | host, user? | | ssh_close_all_connections | Close all persistent connections | - |

Host Management

| Tool | Description | Parameters | | --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------- | | ssh_list_hosts | List all configured host aliases | - | | generate_hosts | Generate hostnames based on patterns | nodeType, pod, region, count? |

Usage Examples

Execute Remote Command

{
  "tool": "ssh_execute",
  "arguments": {
    "host": "k8s-prod",
    "command": "uptime"
  }
}

Dry Run Preview

{
  "tool": "ssh_execute",
  "arguments": {
    "host": "k8s-prod",
    "command": "rm -rf /tmp/logs",
    "dryRun": true
  }
}

Kubernetes Command

{
  "tool": "ssh_kubectl",
  "arguments": {
    "pod": "p13",
    "region": "us-east",
    "command": "get pods --all-namespaces"
  }
}

Batch Parallel Execution

{
  "tool": "ssh_execute_batch",
  "arguments": {
    "executions": [
      {
        "host": "kubemaster-p01-us-east",
        "command": "uptime"
      },
      {
        "host": "kubemaster-p02-us-east",
        "command": "uptime"
      },
      {
        "host": "kubemaster-p03-us-east",
        "command": "uptime"
      }
    ]
  }
}

Generate Hostnames

{
  "tool": "generate_hosts",
  "arguments": {
    "nodeType": "kubenode",
    "pod": "p13",
    "region": "us-east",
    "count": 5
  }
}

Connection Management

{
  "tool": "ssh_connection_status",
  "arguments": {}
}

{
  "tool": "ssh_close_connection",
  "arguments": {
    "host": "kubemaster-p13-us-east"
  }
}

Security Features

Password Encryption

Encrypt passwords before storing them in environment variables. Uses AES-256-GCM with a machine-specific key derived from hostname + username + fixed salt.

Encrypt a password:

If you cloned the repository:

npm run encrypt-password

If you installed via npm/npx, the standalone script is included:

node node_modules/@hbarhate/ssh-mcp-server/scripts/encrypt-password-standalone.js

The standalone script uses the exact same algorithm as the MCP server, so encrypted passwords are fully compatible. They only work on the same machine for the same OS user.

Authentication Methods

• SSH Key Authentication: Supports standard SSH keys with optional passphrase
• Password Authentication: Uses encrypted passwords from environment variables
  • Resolution order: SSH_PASSWORD_<UPPERCASE_USER> → SSH_PASSWORD (generic fallback) → plainPassword in hosts.json
• Connection Timeouts: Prevents hanging connections

Command Confirmation

Approval is disabled by default. Set SSH_APPROVAL=true in your MCP config to enable a Windows VBS popup that asks for confirmation before executing each command. The popup auto-denies after 10 seconds if no response.

Hostname Patterns

The server supports dynamic hostname generation for infrastructure following this pattern:

{nodeType}01.{pod}.eng.{region}.example.com

Use the generate_hosts tool or pass pattern-style aliases directly to ssh_execute:

{
  "tool": "ssh_execute",
  "arguments": {
    "host": "kubemaster-p13-us-east",
    "command": "ls /"
  }
}

Pattern format: {nodeType}-{pod}-{region}

Examples:

• kubemaster-p13-us-east → kubemaster01.p13.eng.us-east.example.com
• kubenode-p01-us-west → kubenode01.p01.eng.us-west.example.com
• ctrl-p28-eu-central → ctrl01.p28.eng.eu-central.example.com

Valid Node Types: kubemaster, kubenode, ctrl, camspm, camsrepo

Valid Regions: us-east, us-west, eu-central (or any 3–6 character region code)

Valid Pods: p01 through p45

Requirements

• Node.js >= 18.0.0
• SSH access to target servers
• SSH key or password authentication credentials

Error Handling

The server provides detailed error information:

• Connection failures with diagnostic messages
• Authentication errors with suggestions
• Command execution failures with exit codes
• Invalid parameter validation
• Network timeout issues

License

MIT © hbarhate