ssh-mcp

The recommended way to add this server to Claude Code is using the claude mcp add command. You can specify different scopes: local (default), project (via .mcp.json), or user (available across all projects).

Examples

With Password Authentication:

claude mcp add --transport stdio ssh-mcp -- npx -y ssh-mcp -- --host=192.168.1.100 --port=22 --user=admin --password=your_password

With SSH Key Authentication:

claude mcp add --transport stdio ssh-mcp -- npx -y ssh-mcp -- --host=example.com --user=root --key=/path/to/private/key

With Custom Timeout and No Character Limit:

claude mcp add --transport stdio ssh-mcp -- npx -y ssh-mcp -- --host=192.168.1.100 --user=admin --password=your_password --timeout=120000 --maxChars=none

With Sudo and Su Support:

claude mcp add --transport stdio ssh-mcp -- npx -y ssh-mcp -- --host=192.168.1.100 --user=admin --password=your_password --sudoPassword=sudo_pass --suPassword=root_pass

claude mcp add --transport stdio ssh-mcp -- npx -y ssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD

To use the SSH MCP Server with clients like Cursor, Windsurf, or Claude Desktop, you must provide connection parameters via command-line arguments.

Required Parameters

• host: Hostname or IP of the Linux or Windows server
• user: SSH username

Optional Parameters

• port: SSH port (default: 22)
• password: SSH password
• key: Path to private SSH key (use instead of password for key-based auth)
• sudoPassword: Password for sudo elevation
• suPassword: Password for su elevation (for persistent root shells)
• timeout: Command execution timeout in milliseconds (default: 60000)
• maxChars: Maximum allowed characters for the command input (default: 1000). Use none or 0 to disable.
• disableSudo: Flag to disable the sudo-exec tool completely.

{
    "mcpServers": {
        "ssh-mcp": {
            "command": "npx",
            "args": [
                "ssh-mcp",
                "-y",
                "--",
                "--host=1.2.3.4",
                "--port=22",
                "--user=root",
                "--password=pass",
                "--key=path/to/key",
                "--timeout=30000",
                "--maxChars=none"
            ]
        }
    }
}

The SSHConnectionManager class maintains a persistent SSH connection and can handle user elevation (via su).

Interface SSHConfig:

export interface SSHConfig {
  host: string;
  port: number;
  username: string;
  password?: string;
  privateKey?: string;
  suPassword?: string;
  sudoPassword?: string;
}

Key Methods:

• connect(): Establishes the SSH connection. If suPassword is provided, it attempts to elevate to a su shell automatically (unless in test mode).
• ensureConnected(): Ensures the connection is active, calling connect() if necessary.
• setSuPassword(pwd?: string): Updates the suPassword and attempts to re-elevate the shell if a password is provided.
• close(): Closes the SSH connection and any active su shells.
• isConnected(): Returns true if the connection is active and the socket is not destroyed.

const manager = new SSHConnectionManager({
  host: '1.2.3.4',
  port: 22,
  username: 'root',
  suPassword: 'my-password'
});
await manager.connect();

This function executes a command using an existing SSHConnectionManager. It is the primary way to run commands while leveraging persistent connections or an existing elevated su shell.

Behavior:

1. If the manager has an active su shell (elevated), the command is written directly to that shell. The function waits for the root prompt (#) to signal completion and extracts the output.
2. If no su shell is available, it uses standard conn.exec().
3. It supports an optional stdin string for providing input (like passwords) to the command.

Returns: A promise resolving to an object containing a content array with the command output as text.

Signature: async function execSshCommandWithConnection(manager: SSHConnectionManager, command: string, stdin?: string): Promise<{ content: { type: 'text', text: string }[] }>

const result = await execSshCommandWithConnection(connectionManager, "uptime");
console.log(result.content[0].text);