mcp-ssh-persistent

MCP server for persistent SSH connections with streaming support for Claude Code.

Features

• Persistent Connections - Connect once, run multiple commands
• Dual Channel Support
  • ssh_exec - Stateless commands with exit codes
  • ssh_stream_* - Stateful interactive sessions
• Auto-Read Output - ssh_stream_write returns output immediately
• SFTP Support - Upload/download files directly
• Prompt Detection - Auto-detects command completion

Requirements

• Node.js >= 18
• Claude Code CLI or Claude Desktop

Installation

Option 1: npx (Recommended)

No installation needed - just configure and use.

Option 2: Global Install

npm install -g mcp-ssh-persistent

Configuration

Claude Code CLI

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-persistent"]
    }
  }
}

Claude Desktop (macOS)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-persistent"]
    }
  }
}

Claude Desktop (Windows)

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-persistent"]
    }
  }
}

VS Code with Claude Extension

Add to VS Code settings (Ctrl+, → search "claude mcp"):

{
  "claude.mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-persistent"]
    }
  }
}

After configuration, restart Claude Code/Desktop to load the MCP server.

Tools

Tool	Description
ssh_connect	Connect to SSH server
ssh_exec	Execute command (returns exit code)
ssh_stream_start	Start interactive shell
ssh_stream_write	Write + auto-read output
ssh_stream_read	Read stream buffer
ssh_stream_stop	Stop stream
ssh_upload	Upload file via SFTP
ssh_download	Download file via SFTP
ssh_write_remote_file	Write to remote file
ssh_read_remote_file	Read remote file
ssh_status	Connection status
ssh_disconnect	Disconnect
ssh_reset_shell	Reset shell state

Usage

Connect

// With private key
ssh_connect({
  host: "192.168.1.100",
  username: "user",
  privateKeyPath: "/path/to/private-key"
})

// With password
ssh_connect({
  host: "192.168.1.100",
  username: "user",
  password: "your-password"
})

Quick Commands (ssh_exec)

Best for one-off commands that need exit code:

ssh_exec({ command: "ls -la" })
// Returns: output + [exit code: 0]

ssh_exec({ command: "npm test" })
// Returns: output + [exit code: 0 or 1]

Interactive Session (ssh_stream_*)

Best for stateful operations (cd, sudo, environment variables):

// Start shell
ssh_stream_start({ stream_id: "main", command: "bash" })

// Run commands - output returned immediately!
ssh_stream_write({ data: "cd /var/www\n" })
ssh_stream_write({ data: "ls -la\n" })

// Sudo with password prompt
ssh_stream_write({ data: "sudo apt update\n" })
// Returns: "[sudo] password for user:" with [complete: true]
ssh_stream_write({ data: "your-password\n" })
// Returns: command output

// Cleanup when done
ssh_stream_stop({ stream_id: "main" })

File Operations (SFTP)

// Upload local file to remote
ssh_upload({ local_path: "./app.zip", remote_path: "/home/user/" })

// Download remote file to local
ssh_download({ remote_path: "/var/log/app.log", local_path: "./app.log" })

// Write content directly to remote file
ssh_write_remote_file({ remote_path: "/tmp/config.json", content: '{"key": "value"}' })

// Read remote file content
ssh_read_remote_file({ remote_path: "/etc/nginx/nginx.conf" })

Auto-Read Feature

ssh_stream_write automatically polls for output (every 100ms) and returns when:

• Shell prompt detected ($, #, >)
• Password prompt detected (e.g., [sudo] password for user:)
• Timeout reached (default 5 seconds)

// Auto-read enabled (default)
ssh_stream_write({ data: "ls -la\n" })
// → Returns output immediately with [complete: true]

// Disable auto-read for long-running commands
ssh_stream_write({ data: "tail -f /var/log/app.log\n", wait_ms: 0 })
// → Returns immediately, use ssh_stream_read to get output later

When to Use Which?

Scenario	Tool
One-off commands	ssh_exec
Need exit code	ssh_exec
Sudo commands	ssh_stream_*
Change directory	ssh_stream_*
Set environment variables	ssh_stream_*
Long-running commands	ssh_stream_*
File transfer	ssh_upload / ssh_download

License

MIT