# SSH MCP server

> Enables AI agents to run commands, move files, and audit remote machines via SSH using structured tools and existing OpenSSH configurations.

- Repository: https://github.com/hypnosis/ssh-mcp-server
- Page: https://hostedmcp.org/servers/hypnosis/ssh-mcp-server
- Transport: stdio
- Stars: 11
- License: MIT
- Latest version: 2.3.3

## Install

### Claude Code

```sh
claude mcp add --env 'SSH_PROFILES_FILE=<SSH_PROFILES_FILE>' ssh-mcp-server -- npx -y @hypnosis/ssh-mcp-server
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@hypnosis/ssh-mcp-server"
      ],
      "env": {
        "SSH_PROFILES_FILE": "<SSH_PROFILES_FILE>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "ssh-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@hypnosis/ssh-mcp-server"
      ],
      "env": {
        "SSH_PROFILES_FILE": "<SSH_PROFILES_FILE>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"ssh-mcp-server","type":"stdio","command":"npx","args":["-y","@hypnosis/ssh-mcp-server"],"env":{"SSH_PROFILES_FILE":"<SSH_PROFILES_FILE>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@hypnosis/ssh-mcp-server"
      ],
      "env": {
        "SSH_PROFILES_FILE": "<SSH_PROFILES_FILE>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add ssh-mcp-server --env 'SSH_PROFILES_FILE=<SSH_PROFILES_FILE>' -- npx -y @hypnosis/ssh-mcp-server
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.ssh-mcp-server]
command = "npx"
args = ["-y", "@hypnosis/ssh-mcp-server"]

[mcp_servers.ssh-mcp-server.env]
SSH_PROFILES_FILE = "<SSH_PROFILES_FILE>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'SSH_PROFILES_FILE=<SSH_PROFILES_FILE>' ssh-mcp-server npx -- -y @hypnosis/ssh-mcp-server
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@hypnosis/ssh-mcp-server"
      ],
      "env": {
        "SSH_PROFILES_FILE": "<SSH_PROFILES_FILE>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `SSH_PROFILES_FILE` | yes | no | Absolute path to the JSON file describing the servers this agent may reach. |
| `SSH_MCP_LOG_LEVEL` | no | no | Log verbosity: error, warn, info or debug. Defaults to info. |

## Tools (18)

- `ssh_exec`
- `ssh_file_read`
- `ssh_file_write`
- `ssh_file_list`
- `ssh_upload`
- `ssh_download`
- `ssh_job_status`
- `ssh_job_output`
- `ssh_job_list`
- `ssh_job_kill`
- `ssh_log_tail`
- `ssh_log_search`
- `ssh_snapshot`
- `ssh_monitor`
- `ssh_audit_baseline`
- `ssh_tls_check`
- `ssh_disk_breakdown`
- `ssh_service_status`

## FAQ

### Does it require a separate SSH installation?

No, it uses the OpenSSH client already on your machine, including your existing keys, config, and jump hosts.

### Can it work with older hardware like routers or NAS devices?

Yes, the server includes fallbacks for legacy gear, such as automatically using older protocols if modern features like new scp protocols are unsupported.

### How does it handle missing tools on a remote machine?

Instead of returning a zero which might be misinterpreted, it explicitly states that the measurement was unavailable.

### What are the system requirements?

You need Node.js 18+ and a system ssh client available on your PATH.
