MCP SSH Manager Skill

Original MCP Server: mcp-ssh-manager by @bvisible

This skill provides documentation, workflows, and best practices for using the MCP ssh-manager server.

Manage remote SSH servers using MCP ssh-manager tools. Emphasizes session reuse, workdir organization, and content persistence for sustainable operations.

Quick Reference

Connection Management

Session Management

File Operations

Monitoring

Tunneling

Backup

Usage Examples

Example 1: Single Command

# Simple command - no session needed
ssh_execute server="rock5t" command="df -h"

Example 2: Multi-step Deployment with Session

# Check existing sessions first
ssh_session_list

# Start a persistent session
ssh_session_start server="rock5t" name="deploy"

# Get session ID from previous response
ssh_session_send session="xxx" command="cd /home/imax/project"
ssh_session_send session="xxx" command="git pull origin main"
ssh_session_send session="xxx" command="npm install"
ssh_session_send session="xxx" command="npm run build"
ssh_session_send session="xxx" command="pm2 restart all"

# Close when done
ssh_session_close session="xxx"

Example 3: System Health Check

# Check overall health
ssh_health_check server="rock5t"

# Monitor specific resources
ssh_monitor server="rock5t" type="cpu" interval=5 duration=30

# Check specific services
ssh_service_status server="rock5t" services="nginx,docker,postgres"

Example 4: File Deployment

# Upload deployment package
ssh_upload server="rock5t" localPath="./dist/app.tar.gz" remotePath="/tmp/app.tar.gz"

# Extract and restart
ssh_execute server="rock5t" command="cd /tmp && tar -xzf app.tar.gz && cp -r app/* /var/www/ && pm2 restart app"

Example 5: Log Monitoring

# Tail real-time logs
ssh_tail server="rock5t" file="/var/log/nginx/access.log" lines=50 follow=true

# Filter with grep
ssh_tail server="rock5t" file="/var/log/syslog" grep="error" lines=100

Example 6: Create SSH Tunnel

# Local port forward (access remote service locally)
ssh_tunnel_create server="rock5t" type="local" localPort=5432 remoteHost="localhost" remotePort=5432

# Now connect to local:5432 to access remote database

Workdir Management

Store SSH operation results in ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/ for reuse and comparison.

Structure

~/.ssh-workdir/
└── {hostname}/
    └── {YYYY-MM-DD}-{topic}/
        ├── commands.md    # All executed commands
        ├── output/        # Command outputs
        │   ├── df-h.txt
        │   ├── cpu.txt
        │   └── memory.txt
        ├── status.json    # Host status snapshot
        └── summary.md     # Findings and notes

Create Workdir

# Create new workdir
mkdir -p ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/output

# Create commands log
touch ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/commands.md

Log Commands

# Add command to log
echo "## $(date)" >> ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/commands.md
echo 'df -h' >> ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/commands.md

Save Output

# Execute and save
ssh_execute server="{hostname}" command="df -h" > ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/output/df-h.txt

Write Summary

# Write findings
echo '## System Check Findings' >> ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/summary.md
echo '- Disk usage: 75% on /dev/sda1' >> ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/summary.md
echo '- Memory: 4GB/16GB used' >> ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/summary.md

Reuse Previous Context

# Check if recent work exists
ls ~/.ssh-workdir/{hostname}/

# Read previous summary
cat ~/.ssh-workdir/{hostname}/{previous-date}-{topic}/summary.md

# Compare outputs
diff ~/.ssh-workdir/{hostname}/{yesterday}-{topic}/output/df-h.txt \
     ~/.ssh-workdir/{hostname}/{today}-{topic}/output/df-h.txt

Session Management Guidelines

When to Use Sessions

Use session for:

• Multi-step deployments
• Tasks requiring state (cd, environment)
• Long-running workflows (more than 3 commands)
• Tasks where command order matters

Don't use session for:

• Single quick commands (df -h, pwd)
• Unrelated commands that don't need state
• Read-only monitoring tasks

Session Lifecycle

# 1. Check existing sessions first
ssh_session_list

# 2. Reuse existing session if available and still active
ssh_session_send session="existing-id" command="..."

# 3. Start new session only if necessary
ssh_session_start server="{hostname}" name="{task-name}"

# 4. ALWAYS close when done
ssh_session_close session="{session-id}"

Timeout Considerations

• SSH server may close idle sessions (typically 3-5 minutes by default)
• Configure ClientAliveInterval on server for longer keepalive
• For long-running tasks, consider periodic lightweight commands to keepalive
• If session becomes unresponsive, create a new one

Best Practices

Before SSH Operations

1. Check existing sessions

   ssh_session_list
   

2. Check recent workdir

   ls ~/.ssh-workdir/{hostname}/
   

3. Create new workdir if starting new task

   mkdir -p ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/output
   

During SSH Operations

1. Use appropriate tool for the task

   • Single command: ssh_execute
   • Multi-step: ssh_session_start → ssh_session_send → ssh_session_close
   • File transfer: ssh_upload/download/sync
   • Monitoring: ssh_monitor, ssh_tail, ssh_health_check

2. Log commands to workdir

   echo "command" >> ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/commands.md
   

3. Save important outputs

   ssh_execute server="{hostname}" command="df -h" > ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/output/df-h.txt
   

After SSH Operations

1. Close sessions

   ssh_session_close session="{session-id}"
   

2. Write summary

   echo '## Findings' >> ~/.ssh-workdir/{hostname}/{YYYY-MM-DD}-{topic}/summary.md
   

3. Clean up

   • Close tunnels: ssh_tunnel_close
   • Verify all sessions closed: ssh_session_list

Tips

• Use ssh_session_list before starting new tasks to reuse existing sessions
• Create workdir for each task to maintain organized history
• Write summaries to quickly recall previous work
• Use ssh_connection_status action="status" to check connection health
• For server comparison, store outputs with consistent naming across hosts
• Close sessions when done to free resources
• Configure server-side ClientAliveInterval for longer session timeouts if needed

Additional Resources

Reference Files

• references/sessions.md - Session management deep dive
• references/workspace.md - Workdir structure and usage
• references/comparison.md - How to compare historical data

Example Files

• examples/system-check.md - Complete system health check workflow
• examples/deployment.md - Multi-step deployment example
• examples/troubleshooting.md - Problem diagnosis workflow

Scripts

• scripts/create-workdir.sh - Create new workdir structure
• scripts/log-command.sh - Log command to workdir
• scripts/save-status.sh - Capture and save host status