SSH MCP Server

Leer en Espa\u00f1ol

MCP (Model Context Protocol) server for remote server administration via SSH. Supports multiple profiles, remote command execution, interactive commands (PTY), persistent shell sessions, file transfer (SFTP), destructive command detection with audit logging, and operation history with undo capabilities.

Architecture

General Overview

graph TB
    Client["Claude Desktop<br/>(or any MCP client)"]
    Server["SSH MCP Server"]
    MCP["MCP SDK<br/>(stdio)"]
    Router["Tool Router<br/>(index.ts)"]
    Security["Security Module<br/>- Dangerous cmd detection<br/>- Audit logging"]
    SSH["SSH Client (ssh2)"]
    Exec["exec()<br/>- Commands<br/>- cat (read)"]
    Interactive["exec() + PTY<br/>- Interactive commands<br/>- Auto prompt response"]
    Shell["shell() + PTY<br/>- Persistent sessions<br/>- REPLs / multi-step"]
    SFTP["SFTP (lazy init)<br/>- upload / download<br/>- ls / write / readdir"]
    Remote["Remote Server<br/>(Linux/Unix)"]

    Client -->|"stdio (JSON-RPC)"| Server
    Server --- MCP
    MCP --> Router
    Router --> Security
    Router --> SSH
    SSH --- Exec
    SSH --- Interactive
    SSH --- Shell
    SSH --- SFTP
    SSH -->|"SSH (TCP :22)"| Remote

Connection and Execution Flow

flowchart TD
    Start([Start]) --> ListProfiles["ssh_list_profiles<br/>View available profiles"]
    ListProfiles --> Connect["ssh_connect<br/>(profile name)"]
    Connect -->|Password not found| Error["Error: env var<br/>SSH_PASSWORD_NAME missing"]
    Connect -->|OK| Active["Active Connection<br/>(1 profile at a time)"]

    Active --> ExecBranch["ssh_exec<br/>(command)"]
    Active --> InteractiveBranch["ssh_exec_interactive<br/>(command + auto-responses)"]
    Active --> ShellBranch["Shell Sessions<br/>start / send / read / close"]
    Active --> SFTPBranch["SFTP operations<br/>upload / download<br/>ls / read / write"]
    Active --> StatusBranch["ssh_status<br/>ssh_disconnect"]

    ExecBranch --> DangerCheck{"Dangerous<br/>command?<br/>(regex)"}
    InteractiveBranch --> DangerCheck
    DangerCheck -->|No| Execute["Execute command"]
    DangerCheck -->|Yes| ConfirmCheck{"confirm:<br/>true?"}
    ConfirmCheck -->|Yes| Execute
    ConfirmCheck -->|No| Warning["WARNING<br/>(not executed)"]

    ShellBranch -->|"send (raw:false)"| DangerCheck
    ShellBranch -->|"send (raw:true)"| Execute

    Execute --> Audit["audit.log"]
    SFTPBranch --> Audit
    Warning --> Audit

Security Flow (Dangerous Commands)

flowchart LR
    Input["Command received"] --> Check["isDangerousCommand()<br/>(16 regex patterns)"]
    Check -->|Safe| Exec["Execute command"]
    Check -->|Dangerous| Confirm{"confirm: true?"}
    Confirm -->|Yes| Exec
    Confirm -->|No| Warn["WARNING returned<br/>(command NOT executed)"]
    Exec --> Log["audit.log"]
    Warn --> Log

    subgraph Detected Patterns
        P1["rm -rf /"]
        P2["mkfs.*"]
        P3["dd if="]
        P4["reboot / shutdown / halt"]
        P5["chmod 777 / chown -R"]
        P6["fork bomb"]
        P7["systemctl stop/disable"]
        P8["killall / iptables -F"]
    end

Project Structure

s01_ssh_mcp/
├── src/
│   ├── index.ts       # SSHMCPServer class — tool router, SSH logic, interactive/shell handlers
│   ├── tools.ts       # MCP tool definitions (17 tools, JSON schemas)
│   ├── profiles.ts    # Profile loading + password injection from env
│   ├── security.ts    # Dangerous command detection + AuditLogger
│   └── types.ts       # Interfaces: SSHProfile, AuditEntry, PromptResponse, ShellSession, CommandRecord, ReverseInfo
├── dist/              # Compiled output (generated by tsc)
├── profiles.json      # SSH server configuration
├── .env               # Passwords (not versioned)
├── audit.log          # Audit log (generated at runtime)
├── package.json
└── tsconfig.json

Setup

1. Server Profiles

Edit profiles.json:

{
  "production": {
    "host": "192.168.1.100",
    "port": 22,
    "username": "deploy"
  },
  "staging": {
    "host": "192.168.1.101",
    "port": 22,
    "username": "deploy"
  }
}

2. Passwords

Create .env (copy from .env.example):

SSH_PASSWORD_PRODUCTION=your_password
SSH_PASSWORD_STAGING=your_password

Format: SSH_PASSWORD_<PROFILE_NAME_UPPERCASE>.

3. Build and Run

npm install
npm run build
npm start

4. MCP Configuration (Claude Desktop)

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/s01_ssh_mcp/dist/index.js"],
      "env": {
        "SSH_PASSWORD_PRODUCTION": "your_password",
        "SSH_PASSWORD_STAGING": "your_password"
      }
    }
  }
}

Note: You can optionally set SSH_PROFILES_PATH in env to point to a profiles.json in a different location.

Available Tools

| Tool | Description | Requires Connection | | ---- | ----------- | :-----------------: | | ssh_list_profiles | List configured profiles (without passwords) | No | | ssh_connect | Connect to an SSH profile | No | | ssh_disconnect | Close the active SSH connection (closes all shell sessions) | Yes | | ssh_status | Connection status (profile, host, uptime) | Yes | | ssh_exec | Execute a remote command | Yes | | ssh_exec_interactive | Execute interactive command with PTY and auto-response to prompts | Yes | | ssh_shell_start | Start a persistent interactive shell session with PTY | Yes | | ssh_shell_send | Send input to an active shell session | Yes | | ssh_shell_read | Read accumulated output from a shell session buffer | Yes | | ssh_shell_close | Close a shell session and release resources | Yes | | ssh_upload | Upload a local file to the server (SFTP) | Yes | | ssh_download | Download a file from the server (SFTP) | Yes | | ssh_ls | List a remote directory (SFTP) | Yes | | ssh_read_file | Read remote file contents | Yes | | ssh_write_file | Write content to a remote file (SFTP) | Yes | | ssh_history | View operation history for the active connection | Yes | | ssh_undo | Revert a specific operation by record ID | Yes |

Tool Parameters

| Tool | Parameters | Required | | ---- | ---------- | :------: | | ssh_connect | profile (string) | Yes | | ssh_exec | command (string), confirm (boolean) | command | | ssh_exec_interactive | command (string), responses[] ({prompt, answer, sensitive}), timeout (number), confirm (boolean) | command | | ssh_shell_start | cols (number, default: 80), rows (number, default: 24) | No | | ssh_shell_send | sessionId (string), input (string), raw (boolean), timeout (number), confirm (boolean) | sessionId, input | | ssh_shell_read | sessionId (string), timeout (number) | sessionId | | ssh_shell_close | sessionId (string) | sessionId | | ssh_upload | localPath (string), remotePath (string) | Both | | ssh_download | remotePath (string), localPath (string) | Both | | ssh_ls | path (string, default: home) | No | | ssh_read_file | path (string) | Yes | | ssh_write_file | path (string), content (string) | Both | | ssh_history | filter ("all" | "reversible" | "reversed"), limit (number) | No | | ssh_undo | recordId (number), confirm (boolean) | recordId |

Operation History & Undo

Every operation executed during an active connection is recorded in memory. This allows reviewing what was done and reverting specific operations.

Reversibility by Operation

| Operation | Reversible | Undo Strategy | |-----------|:----------:|---------------| | ssh_write_file | Yes | Restores previous content. If file didn't exist, deletes it | | ssh_upload | Yes | Restores previous remote content. If file didn't exist, deletes it | | ssh_download | Yes | Deletes the downloaded local file | | ssh_exec | No | Recorded but not auto-reversible | | ssh_exec_interactive | No | Recorded but not auto-reversible | | ssh_read_file | N/A | Read-only, nothing to revert | | ssh_ls | N/A | Read-only, nothing to revert | | ssh_shell_send | N/A | Cannot revert input sent to an interactive shell |

The history is cleared on ssh_connect and ssh_disconnect.

Security

Destructive Command Detection

The following patterns are intercepted and require confirm: true to execute. This applies to ssh_exec, ssh_exec_interactive, and ssh_shell_send (when raw: false):

| Pattern | Reason | | ------- | ------ | | rm -rf / | Recursive rm on system root | | rm -r, rm -rf | Mass file deletion | | mkfs.* | Filesystem formatting | | dd if= | Direct disk write | | reboot, shutdown, halt, poweroff | Server state control | | init 0, init 6 | Runlevel change | | chmod 777 / | Insecure permissions on root | | chown -R | Mass ownership change | | > /dev/* | Direct device write | | :(){ :\|:& };: | Fork bomb | | systemctl stop\|disable\|mask | System service shutdown | | killall | Mass process termination | | iptables -F | Firewall rules flush |

Audit Log

All operations are logged to audit.log with the format:

[timestamp] [profile] [tool] [parameters] [RESULT: ok|error]

Example:

[2026-03-04T10:30:00.000Z] [production] [ssh_exec] [ls -la /var/log] [RESULT: ok]
[2026-03-04T10:31:00.000Z] [production] [ssh_upload] [./app.tar.gz -> /tmp/app.tar.gz] [RESULT: ok]

Technical Details

• MCP Transport: stdio (JSON-RPC over stdin/stdout)
• SSH Connection: One active connection at a time. Attempting to connect to another profile without disconnecting raises an error.
• SFTP: Lazy initialization — created on first file operation use and reused thereafter.
• Interactive Exec: Uses exec() with pty: true for commands requiring interactive input. Supports auto-response to prompts via regex matching. Settle timeout (2s) detects command completion; global timeout (default 30s) prevents hangs.
• Shell Sessions: Uses shell() with PTY for persistent interactive terminals. Up to 5 concurrent sessions stored in a Map<string, ShellSession>. Auto-close after 5 minutes of inactivity. Buffer capped at 1MB. All sessions are closed on ssh_disconnect. ANSI escape codes are stripped from output.
• File Reading: Uses ssh exec cat (not SFTP) for text files.
• File Writing: Uses SFTP createWriteStream for large file support.
• Argument Escaping: Shell escaping with single quotes to prevent command injection.
• Audit Logging: Non-blocking — log write failures are silently ignored to avoid disrupting operations. Responses marked sensitive: true are logged as [REDACTED].
• Profile Cache: profiles.json is read once and cached in memory.
• Operation History: All operations are recorded in memory during the active connection. File operations (ssh_write_file, ssh_upload) capture previous content before modifying, enabling undo. History is cleared on connect/disconnect.

License

This project is licensed under the MIT License.