# SSH MCP server

> Lets an AI client connect to a remote server over SSH to run commands, list directories, and upload or download files via SFTP.

- Repository: https://github.com/pulsemcp/mcp-servers
- Page: https://hostedmcp.org/servers/pulsemcp/ssh
- Official: yes
- Transport: stdio
- Stars: 81
- License: MIT
- Latest version: 0.1.5

## Install

### Claude Code

```sh
claude mcp add --env 'SSH_HOST=<SSH_HOST>' --env 'SSH_USERNAME=<SSH_USERNAME>' --env 'SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE>' ssh -- npx -y ssh-agent-mcp-server
```

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

```json
{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-agent-mcp-server"
      ],
      "env": {
        "SSH_HOST": "<SSH_HOST>",
        "SSH_USERNAME": "<SSH_USERNAME>",
        "SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "ssh": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "ssh-agent-mcp-server"
      ],
      "env": {
        "SSH_HOST": "<SSH_HOST>",
        "SSH_USERNAME": "<SSH_USERNAME>",
        "SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"ssh","type":"stdio","command":"npx","args":["-y","ssh-agent-mcp-server"],"env":{"SSH_HOST":"<SSH_HOST>","SSH_USERNAME":"<SSH_USERNAME>","SSH_PASSPHRASE":"<YOUR_SSH_PASSPHRASE>"}}'
```

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

```json
{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-agent-mcp-server"
      ],
      "env": {
        "SSH_HOST": "<SSH_HOST>",
        "SSH_USERNAME": "<SSH_USERNAME>",
        "SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add ssh --env 'SSH_HOST=<SSH_HOST>' --env 'SSH_USERNAME=<SSH_USERNAME>' --env 'SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE>' -- npx -y ssh-agent-mcp-server
```

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

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

[mcp_servers.ssh.env]
SSH_HOST = "<SSH_HOST>"
SSH_USERNAME = "<SSH_USERNAME>"
SSH_PASSPHRASE = "<YOUR_SSH_PASSPHRASE>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'SSH_HOST=<SSH_HOST>' -e 'SSH_USERNAME=<SSH_USERNAME>' -e 'SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE>' ssh npx -- -y ssh-agent-mcp-server
```

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

```json
{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-agent-mcp-server"
      ],
      "env": {
        "SSH_HOST": "<SSH_HOST>",
        "SSH_USERNAME": "<SSH_USERNAME>",
        "SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `SSH_HOST` | yes | no | Hostname or IP address of the SSH server. |
| `SSH_USERNAME` | yes | no | Username for SSH authentication. |
| `SSH_PASSPHRASE` | no | yes | Passphrase for encrypted private key. |
| `ENABLED_TOOLGROUPS` | no | no | Comma-separated list of tool groups to enable (readonly, write, admin). |
| `HEALTH_CHECK_TIMEOUT` | no | no | Health check timeout in milliseconds. |
| `SKIP_HEALTH_CHECKS` | no | no | Skip SSH connection health check on startup. |
| `SSH_AUTH_SOCK` | no | no | Path to SSH agent socket for agent-based authentication. |
| `SSH_COMMAND_TIMEOUT` | no | no | Default command activity timeout in milliseconds. |
| `SSH_PORT` | no | no | SSH port number. |
| `SSH_PRIVATE_KEY_PATH` | no | no | Path to private key file for direct key authentication. |
| `SSH_TIMEOUT` | no | no | Connection timeout in milliseconds. |

## Tools (14)

- `ssh_connection_info`
- `ssh_list_directory`
- `ssh_download`
- `ssh_upload`
- `ssh_execute`
- `readonly`
- `write`
- `admin`
- `command`
- `cwd`
- `timeout`
- `localPath`
- `remotePath`
- `path`

## FAQ

### How does the SSH MCP server handle passphrase-protected SSH keys?

It authenticates through your SSH agent, so your decrypted key stays in the agent and is never exposed to the server. You load your key with ssh-add and pass SSH_AUTH_SOCK to the server.

### What authentication methods does the SSH MCP server support and in what order?

It tries SSH agent first if SSH_AUTH_SOCK is set or auto-detected, then falls back to a private key file configured with SSH_PRIVATE_KEY_PATH.

### How do I restrict what the SSH MCP server can do?

Set the ENABLED_TOOLGROUPS environment variable to readonly, write, or admin, or a combination. Leaving it unset enables all tools.

### Does the SSH MCP server check the connection on startup?

Yes, it runs an SSH connection health check at startup and gives hints for auth failures, timeouts, refused connections, and DNS errors. You can skip it with SKIP_HEALTH_CHECKS=true.

### What does the ssh_execute tool do and how does its timeout work?

It runs a shell command on the remote server and returns stdout, stderr, and the exit code. The timeout is activity-based, resetting whenever output arrives, and defaults to 60000 ms or SSH_COMMAND_TIMEOUT.
