ssh-mcp-stdio

janbachmann/ssh-mcp-stdio

3.2

If you are the rightful owner of ssh-mcp-stdio and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The SSH MCP Server (stdio) is a Model Context Protocol server that facilitates SSH connections to multiple remote servers through Claude Desktop and other MCP clients.

Tools
3
Resources
0
Prompts
0

SSH MCP Server (stdio)

A Model Context Protocol (MCP) server that enables SSH connections to multiple remote servers through Claude Desktop and other MCP clients.

🚀 Features

  • Multiple SSH Server Management: Connect to and manage multiple SSH servers from a single MCP interface
  • Password & SSH Key Authentication: Support for both authentication methods
  • Persistent Connections: Maintains SSH connections for better performance
  • MCP Protocol Compliant: Works with Claude Desktop and any MCP-compatible client
  • Process Management: Uses PM2 for reliable server operation
  • Auto-start on Boot: Automatically starts with the system

📋 Available MCP Tools

  1. ssh_execute - Execute commands on remote SSH servers
  2. ssh_list_servers - List all configured SSH servers and their connection status
  3. ssh_disconnect - Disconnect from a specific SSH server

🔑 SSH Key Architecture

This project uses two sets of SSH keys:

1. Client → MCP Server Keys (Required for Claude Desktop)

Purpose: Authenticate from your local machine (Claude Desktop) to the MCP server

  • Location on LOCAL machine: ~/.ssh/jb_id_ed25519 (private key)
  • Location on MCP SERVER: /home/mcpuser/.ssh/authorized_keys (public key)
  • Usage: Claude Desktop uses this to connect to the MCP server
┌─────────────────────────────────┐
│ Your Computer (Claude Desktop)  │
│                                 │
│ Private: ~/.ssh/jb_id_ed25519   │ ─┐
│ Public:  ~/.ssh/jb_id_ed25519.pub│  │
└─────────────────────────────────┘  │
                                     │ SSH Connection
                                     ▼
┌─────────────────────────────────┐
│ MCP Server (199.247.22.91)      │
│                                 │
│ ~/.ssh/authorized_keys          │◄─┘
│   (contains jb_id_ed25519.pub)  │
└─────────────────────────────────┘

2. MCP Server → Target Servers Keys (Optional)

Purpose: Authenticate from MCP server to other remote servers

  • Location on MCP SERVER: /home/mcpuser/.ssh/id_ed25519 (private key)
  • Location on TARGET SERVERS: ~/.ssh/authorized_keys (public key)
  • Usage: MCP server uses this to connect to other servers you want to manage
┌─────────────────────────────────┐
│ MCP Server (199.247.22.91)      │
│                                 │
│ Private: ~/.ssh/id_ed25519      │ ─┐
│ Public:  ~/.ssh/id_ed25519.pub  │  │
└─────────────────────────────────┘  │
                                     │ SSH Connection
                                     ▼
┌─────────────────────────────────┐
│ Target Server (other.server.com)│
│                                 │
│ ~/.ssh/authorized_keys          │◄─┘
│   (contains id_ed25519.pub)     │
└─────────────────────────────────┘

⚡ Quick Install (One Command)

Prerequisites

  • Ubuntu 20.04 or higher (tested on Ubuntu 24.04 LTS)
  • Root access
  • Minimum 2GB RAM, 1 vCPU

Installation

curl -fsSL https://raw.githubusercontent.com/janbachmann/ssh-mcp-stdio/main/install.sh | sudo bash

This will:

  1. Install all dependencies (Node.js, Python, PM2)
  2. Create the mcpuser account
  3. Set up the MCP SSH server
  4. Configure firewall
  5. Set up PM2 auto-start
  6. Generate SSH keys

Manual Installation

# Clone the repository
git clone https://github.com/janbachmann/ssh-mcp-stdio.git
cd ssh-mcp-stdio

# Run installation script
sudo ./install.sh

# Follow the prompts

🔧 Configuration

1. Configure MCP Server Settings

Edit the configuration file:

nano config.env

Set your variables:

# Server Configuration
SERVER_PORT=22
SERVER_USER=mcpuser
SERVER_PASSWORD=YourSecurePassword123!

# SSH Configuration
GENERATE_SSH_KEYS=true
SSH_KEY_TYPE=ed25519

# Installation Paths
INSTALL_DIR=/opt/mcp-ssh-server
VENV_DIR=/opt/mcp-env
BACKUP_DIR=/opt/backups

2. Configure SSH Servers

Edit /opt/mcp-ssh-server/ssh-config.json:

{
  "servers": [
    {
      "name": "local-server",
      "host": "199.247.22.91",
      "port": 22,
      "username": "mcpuser",
      "password": "YourPassword",
      "description": "Local MCP server"
    },
    {
      "name": "production-server",
      "host": "prod.example.com",
      "port": 22,
      "username": "admin",
      "privateKeyPath": "/home/mcpuser/.ssh/id_ed25519",
      "description": "Production server with SSH key"
    },
    {
      "name": "dev-server",
      "host": "192.168.1.100",
      "port": 22,
      "username": "developer",
      "password": "DevPassword",
      "description": "Development server"
    }
  ]
}

3. Configure Claude Desktop

Location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "ssh": {
      "command": "ssh",
      "args": [
        "-i",
        "~/.ssh/jb_id_ed25519",
        "mcpuser@199.247.22.91",
        "cd /opt/mcp-ssh-server && node index.js"
      ]
    }
  }
}

📝 Post-Installation Steps

1. Copy Your SSH Public Key to the Server

From your local machine (where Claude Desktop runs):

# Copy your public key to the MCP server
ssh-copy-id -i ~/.ssh/jb_id_ed25519.pub mcpuser@199.247.22.91

# Test connection (should not ask for password)
ssh -i ~/.ssh/jb_id_ed25519 mcpuser@199.247.22.91

2. Start the MCP Server

# SSH to the server
ssh mcpuser@199.247.22.91

# Start with PM2
pm2 start /opt/mcp-ssh-server/index.js --name mcp-ssh-server
pm2 save

# Check status
pm2 status

3. Setup Auto-Start on Boot

# Generate startup script
pm2 startup

# Run the command it outputs (as root)
exit
sudo [paste the command]

# Switch back to mcpuser and save
su - mcpuser
pm2 save

🎯 Usage Examples

In Claude Desktop

Once configured, you can ask Claude:

  1. List available servers:

    List all SSH servers

  2. Execute a command:

    Execute 'df -h' on production-server

  3. Check system information:

    Execute 'uname -a' on dev-server

  4. Get directory listing:

    Execute 'ls -la /var/www' on production-server

🔐 Security Best Practices

  1. Use SSH Keys: Always prefer SSH key authentication over passwords
  2. Restrict Permissions: 
    chmod 600 ~/.ssh/id_ed25519
chmod 600 /opt/mcp-ssh-server/ssh-config.json
chmod 700 ~/.ssh
  3. Secure Config File: The ssh-config.json contains credentials, keep it secure
  4. Firewall: Only open necessary ports 
    sudo ufw allow 22/tcp
sudo ufw enable
  5. Regular Updates: Keep the system and dependencies updated 
    sudo apt update && sudo apt upgrade -y
  6. Disable Root Login: 
    sudo nano /etc/ssh/sshd_config
# Set: PermitRootLogin no
sudo systemctl restart sshd

📂 Project Structure

ssh-mcp-stdio/
├── README.md                    # This file
├── install.sh                   # One-command installation script
├── config.env                   # Configuration file
├── server/
│   ├── package.json            # Node.js dependencies
│   ├── index.js                # Main MCP server
│   └── ssh-config.json.example # Example configuration
├── scripts/
│   ├── setup-venv.sh           # Python virtual environment setup
│   ├── setup-firewall.sh       # Firewall configuration
│   └── setup-pm2.sh            # PM2 setup
└── docs/
    ├── INSTALLATION.md         # Detailed installation guide
    ├── CONFIGURATION.md        # Configuration guide
    ├── TROUBLESHOOTING.md      # Common issues and solutions
    └── SSH_KEYS.md             # SSH key management guide

🛠️ Management Commands

PM2 Commands

# Start server
pm2 start mcp-ssh-server

# Stop server
pm2 stop mcp-ssh-server

# Restart server
pm2 restart mcp-ssh-server

# View logs
pm2 logs mcp-ssh-server

# Monitor resources
pm2 monit

# Show process info
pm2 show mcp-ssh-server

# Delete from PM2
pm2 delete mcp-ssh-server

Server Commands

# Check status
pm2 status

# View real-time logs
pm2 logs mcp-ssh-server --lines 100

# Test SSH connection
ssh -i ~/.ssh/jb_id_ed25519 mcpuser@199.247.22.91

# Test MCP server manually
ssh -i ~/.ssh/jb_id_ed25519 mcpuser@199.247.22.91 "cd /opt/mcp-ssh-server && node index.js"

🐛 Troubleshooting

MCP Server Won't Start

# Check PM2 logs
pm2 logs mcp-ssh-server

# Check if Node.js is installed
node --version

# Reinstall dependencies
cd /opt/mcp-ssh-server
npm install

SSH Connection Issues

# Test SSH connection with verbose output
ssh -v -i ~/.ssh/jb_id_ed25519 mcpuser@199.247.22.91

# Check SSH key permissions
ls -la ~/.ssh/jb_id_ed25519
chmod 600 ~/.ssh/jb_id_ed25519

# Check authorized_keys on server
ssh mcpuser@199.247.22.91 "cat ~/.ssh/authorized_keys"

Claude Desktop Not Connecting

  1. Check Claude Desktop logs:

    • macOS: ~/Library/Logs/Claude/
    • Windows: %APPDATA%\Claude\logs\

  2. Validate JSON configuration at https://jsonlint.com/

  3. Test the command manually:

    ssh -i ~/.ssh/jb_id_ed25519 mcpuser@199.247.22.91 "cd /opt/mcp-ssh-server && node index.js"

Permission Denied Errors

# Fix ownership
sudo chown -R mcpuser:mcpuser /opt/mcp-ssh-server
sudo chown -R mcpuser:mcpuser /opt/mcp-env

# Fix permissions
chmod 600 /opt/mcp-ssh-server/ssh-config.json
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

📊 System Requirements

Minimum

  • OS: Ubuntu 20.04 LTS or higher
  • RAM: 2GB
  • CPU: 1 vCPU
  • Storage: 10GB
  • Network: Public IP address

Recommended

  • OS: Ubuntu 24.04 LTS
  • RAM: 4GB
  • CPU: 2 vCPU
  • Storage: 20GB SSD
  • Network: Public IP with firewall

🔄 Updates

Update MCP Server

# Pull latest changes
cd /opt/mcp-ssh-server
git pull origin main

# Install dependencies
npm install

# Restart server
pm2 restart mcp-ssh-server

Update System

# Update packages
sudo apt update && sudo apt upgrade -y

# Update Node.js (if needed)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Update PM2
sudo npm install -g pm2@latest

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

💬 Support

🙏 Acknowledgments

📝 Changelog

v1.0.0 (2025-10-25)

  • Initial release
  • Support for multiple SSH servers
  • Password and SSH key authentication
  • PM2 process management
  • Auto-start on boot
  • Claude Desktop integration

🗺️ Roadmap

  • Web-based configuration interface
  • Support for SSH tunneling
  • SFTP file transfer capabilities
  • Session recording and playback
  • Multi-user support
  • Docker container deployment
  • Kubernetes deployment manifests
  • Ansible playbooks for deployment

Made with ❤️ for the MCP community

Server: 199.247.22.91 | User: mcpuser | Password: McpServer2025!