How do I use SSH MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SSH MCP Server List the files in /var/www/html on the staging profile" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

SSH MCP Server

Node.js TypeScript MCP SDK SSH2 License Version

Leer en Espa\u00f1ol

MCP (Model Context Protocol) server for remote server administration via SSH. Supports multiple profiles, remote command execution, file transfer (SFTP), and destructive command detection with audit logging.

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)"]
    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 --- 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 --> SFTPBranch["SFTP operations<br/>upload / download<br/>ls / read / write"]
    Active --> StatusBranch["ssh_status<br/>ssh_disconnect"]

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

    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 and SSH logic
│   ├── tools.ts       # MCP tool definitions (10 tools, JSON schemas)
│   ├── profiles.ts    # Profile loading + password injection from env
│   ├── security.ts    # Dangerous command detection + AuditLogger
│   └── types.ts       # Interfaces: SSHProfile, AuditEntry
├── 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	Yes
`ssh_status`	Connection status (profile, host, uptime)	Yes
`ssh_exec`	Execute a remote command	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

Tool Parameters

Tool	Parameters	Required
`ssh_connect`	`profile` (string)	Yes
`ssh_exec`	`command` (string), `confirm` (boolean)	`command`
`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

Security

Destructive Command Detection

The following patterns are intercepted and require confirm: true to execute:

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.
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.
Profile Cache: profiles.json is read once and cached in memory.

License

This project is licensed under the MIT License.

SSH MCP Server

SSH MCP Server

Architecture

General Overview

Connection and Execution Flow

Security Flow (Dangerous Commands)

Project Structure

Setup

1. Server Profiles

2. Passwords

3. Build and Run

4. MCP Configuration (Claude Desktop)

Available Tools

Tool Parameters

Security

Destructive Command Detection

Audit Log

Technical Details

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API