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 Parameters

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

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):

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.