SSH Remote MCP Guide

SSH Remote is an MCP server that provides SSH access to remote Ubuntu servers directly from Claude Code. It enables connecting to servers, executing commands, transferring files via SFTP, and managing multiple concurrent connections.

Quick Start

# Connect to a remote server (password auth)
mcp__ssh-remote__ssh_connect(hostname, username, password)

# Connect with SSH key
mcp__ssh-remote__ssh_connect(hostname, username, private_key_path="~/.ssh/id_rsa")

# Execute a command on the remote server
mcp__ssh-remote__ssh_execute(connection_name, command="uname -a")

# List active connections
mcp__ssh-remote__ssh_list_connections()

# Disconnect
mcp__ssh-remote__ssh_disconnect(connection_name)

Available MCP Tools

Tool	Description
ssh_connect	Establish SSH connection (password or key-based auth)
ssh_execute	Run a command on a remote server
ssh_upload_file	Upload a local file to remote server via SFTP
ssh_download_file	Download a remote file to local machine via SFTP
ssh_disconnect	Close an SSH connection
ssh_list_connections	List all active SSH connections
ssh_health_check	Verify connection health and server status

Common Workflows

Workflow 1: Connect and Explore a Server

# 1. Connect to the server
ssh_connect(hostname="192.168.1.100", username="deploy", password="secret")

# 2. Check server info
ssh_execute(connection_name="192.168.1.100", command="uname -a")
ssh_execute(connection_name="192.168.1.100", command="df -h")
ssh_execute(connection_name="192.168.1.100", command="free -h")

# 3. Check running services
ssh_execute(connection_name="192.168.1.100", command="systemctl list-units --type=service --state=running")

# 4. Disconnect when done
ssh_disconnect(connection_name="192.168.1.100")

Workflow 2: Deploy Application Files

# 1. Connect to production server
ssh_connect(hostname="prod.example.com", username="deploy", private_key_path="~/.ssh/deploy_key", connection_name="prod")

# 2. Create deployment directory
ssh_execute(connection_name="prod", command="mkdir -p /opt/myapp/releases/v1.2.0")

# 3. Upload application files
ssh_upload_file(connection_name="prod", local_path="./dist/app.js", remote_path="/opt/myapp/releases/v1.2.0/app.js")
ssh_upload_file(connection_name="prod", local_path="./dist/package.json", remote_path="/opt/myapp/releases/v1.2.0/package.json")

# 4. Install dependencies and restart
ssh_execute(connection_name="prod", command="cd /opt/myapp/releases/v1.2.0 && npm install --production")
ssh_execute(connection_name="prod", command="ln -sfn /opt/myapp/releases/v1.2.0 /opt/myapp/current")
ssh_execute(connection_name="prod", command="sudo systemctl restart myapp")

# 5. Verify deployment
ssh_execute(connection_name="prod", command="systemctl status myapp")
ssh_execute(connection_name="prod", command="curl -s http://localhost:3000/health")

Workflow 3: Multi-Server Management

# 1. Connect to multiple servers
ssh_connect(hostname="web1.example.com", username="admin", private_key_path="~/.ssh/id_rsa", connection_name="web1")
ssh_connect(hostname="web2.example.com", username="admin", private_key_path="~/.ssh/id_rsa", connection_name="web2")
ssh_connect(hostname="db1.example.com", username="admin", private_key_path="~/.ssh/id_rsa", connection_name="db1")

# 2. Check health of all connections
ssh_health_check()

# 3. Execute commands across servers
ssh_execute(connection_name="web1", command="uptime")
ssh_execute(connection_name="web2", command="uptime")
ssh_execute(connection_name="db1", command="uptime")

# 4. List all connections
ssh_list_connections()

# 5. Disconnect all
ssh_disconnect(connection_name="web1")
ssh_disconnect(connection_name="web2")
ssh_disconnect(connection_name="db1")

Workflow 4: Log Analysis and Debugging

# 1. Connect to the server
ssh_connect(hostname="server.example.com", username="ops", private_key_path="~/.ssh/id_rsa", connection_name="debug")

# 2. Check recent application logs
ssh_execute(connection_name="debug", command="journalctl -u myapp --since '1 hour ago' --no-pager")

# 3. Search for errors
ssh_execute(connection_name="debug", command="grep -i 'error\\|exception\\|fatal' /var/log/myapp/app.log | tail -50")

# 4. Check system resources
ssh_execute(connection_name="debug", command="top -bn1 | head -20")
ssh_execute(connection_name="debug", command="iostat -x 1 3")

# 5. Download log file for local analysis
ssh_download_file(connection_name="debug", remote_path="/var/log/myapp/app.log", local_path="/tmp/app.log")

Workflow 5: Database Backup and Transfer

# 1. Connect to database server
ssh_connect(hostname="db.example.com", username="backup", private_key_path="~/.ssh/id_rsa", connection_name="db")

# 2. Create database dump
ssh_execute(connection_name="db", command="pg_dump -U postgres mydb | gzip > /tmp/mydb_backup.sql.gz", timeout=120)

# 3. Download backup locally
ssh_download_file(connection_name="db", remote_path="/tmp/mydb_backup.sql.gz", local_path="./backups/mydb_backup.sql.gz")

# 4. Clean up remote temp file
ssh_execute(connection_name="db", command="rm /tmp/mydb_backup.sql.gz")

# 5. Disconnect
ssh_disconnect(connection_name="db")

Decision Tree

When to use which tool:

• To establish a new connection: Use ssh_connect with hostname, username, and auth method
• To run a command remotely: Use ssh_execute with connection name and command
• To upload a file: Use ssh_upload_file with local and remote paths
• To download a file: Use ssh_download_file with remote and local paths
• To check connection status: Use ssh_list_connections or ssh_health_check
• To close a connection: Use ssh_disconnect with connection name
• For detailed tool parameters: See Commands Reference
• For complex scenarios: See Common Patterns
• For troubleshooting: See Troubleshooting Guide

Common Patterns

Connection with Named Aliases

# Use descriptive names instead of hostnames
ssh_connect(hostname="192.168.1.100", username="deploy", password="secret", connection_name="staging")
ssh_connect(hostname="10.0.0.50", username="deploy", password="secret", connection_name="production")

# Reference by alias in all subsequent calls
ssh_execute(connection_name="staging", command="uptime")
ssh_execute(connection_name="production", command="uptime")

File Transfer Patterns

# Upload configuration file
ssh_upload_file(connection_name="prod", local_path="./config/nginx.conf", remote_path="/etc/nginx/sites-available/myapp.conf")

# Download remote logs
ssh_download_file(connection_name="prod", remote_path="/var/log/nginx/error.log", local_path="/tmp/nginx-error.log")

# Bulk upload via tar (create locally, upload, extract remotely)
# Step 1: Create tar locally (via Bash tool)
# Step 2: Upload tar
ssh_upload_file(connection_name="prod", local_path="/tmp/deploy.tar.gz", remote_path="/tmp/deploy.tar.gz")
# Step 3: Extract remotely
ssh_execute(connection_name="prod", command="cd /opt/myapp && tar xzf /tmp/deploy.tar.gz")

Long-Running Commands

# Use timeout parameter for commands that take time
ssh_execute(connection_name="prod", command="npm install --production", timeout=120)
ssh_execute(connection_name="db", command="pg_dump -U postgres largedb > /tmp/dump.sql", timeout=300)

# Run commands in background on the server
ssh_execute(connection_name="prod", command="nohup ./long-script.sh > /var/log/script.log 2>&1 &")

Troubleshooting

Common Issues:

1. Authentication failed

   • Solution: Verify username, password, or key path
   • See: Authentication Issues

2. Connection timeout

   • Quick fix: Check hostname/IP, port, and network reachability
   • See: Connection Timeout

3. Command execution fails

   • Quick fix: Check if connection is still active with ssh_health_check
   • See: Command Execution Issues

4. SFTP file transfer errors

   • Quick fix: Verify paths exist and permissions are correct
   • See: File Transfer Issues

5. Connection drops unexpectedly

   • Quick fix: Reconnect with ssh_connect using same parameters
   • See: Connection Stability

For detailed troubleshooting steps, see the Troubleshooting Guide.

Reference Files

Load as needed for detailed information:

• Commands Reference - Complete MCP tool documentation with all parameters, types, defaults, and return values. Use when you need exact parameter details for any SSH Remote tool.

• Common Patterns - Real-world patterns and workflows for server management, deployment, multi-server operations, database administration, and CI/CD integration. Use for implementing specific workflows or automation.

• Troubleshooting Guide - Detailed error messages, diagnosis steps, and resolution strategies for connection, authentication, command execution, file transfer, and performance issues. Use when encountering errors or unexpected behavior.

When to use each reference:

• Use Commands Reference when you need exact parameter names, types, or default values for MCP tool calls
• Use Common Patterns for implementing deployment workflows, multi-server management, or backup strategies
• Use Troubleshooting when connections fail, commands error out, or file transfers don't work

Installation

Step 1: Setup MCP server

cd ~/.claude/plugins/marketplaces/topographic-plugins-official/plugins/infra/servers/ssh-remote
bash setup.sh

This runs bun install and bun run build to compile the TypeScript server.

Step 2: Configure MCP in claude.json

Add or verify the ssh-remote entry in ~/.claude.json:

{
  "mcpServers": {
    "ssh-remote": {
      "command": "bun",
      "args": [
        "~/.claude/plugins/marketplaces/topographic-plugins-official/plugins/infra/servers/ssh-remote/dist/index.js"
      ]
    }
  }
}

Step 3: Verify

Restart Claude Code. The SSH Remote MCP tools should be available.

Resources

• MCP Server Source: servers/ssh-remote/src/index.ts (co-located in this plugin)
• Original Repository: https://github.com/nqmn/adremote-mcp
• MCP Configuration: ~/.claude.json (ssh-remote section)
• ssh2 Documentation: https://github.com/mscdex/ssh2