SSH MCP Server

🔐 A secure remote server management tool based on MCP protocol, supporting SSH connections, command execution, and SFTP file transfers.

⭐ If you find this project helpful, please give it a star on GitHub! Your support helps us improve!

English | 中文

🚀 Features

• 🔗 SSH Connection Management - Password/key authentication with connection pooling
• ⚡ Command Execution - Regular commands, sudo commands, batch execution
• 📁 SFTP Operations - Upload, download, list directories, create/delete files
• 💾 Server Management - Save/list/remove server configurations
• 🔒 Credential Security - System Keychain encrypted storage (macOS/Windows/Linux)
• 📝 Audit Logging - Records all operations with sensitive data masking

🆕 What's New

v0.4.0 (Latest)

• 🔗 Shell Mode Execution - New exec_shell tool for bastion hosts that don't support exec mode
  • Uses interactive PTY shell to execute commands
  • Perfect for jump server / bastion host scenarios
  • Supports custom prompt pattern for different shell environments

v0.3.1

• 💡 Enhanced Error Messages - All SSH errors now include bilingual (Chinese/English) solutions
• 📖 npm Documentation - Added GitHub repository links for easier contribution

v0.3.0

• 🔄 Improved Reconnection Mechanism - Fixed "configuration not found" error after disconnection
• 💾 Configuration & State Separation - Connection configs persist after disconnection, enabling seamless reconnection
• 📦 New Configuration APIs - getCachedConfig(), listCachedConfigs(), clearConfigCache(), etc.
• ⚡ No Password Re-entry - Reconnect anytime without re-entering credentials

v0.2.2

• ⏱️ Long Timeout Support - Added longCommandTimeout (30 min) for docker build, etc.
• 💓 Connection Health Check - Heartbeat detection every 30 seconds
• 🔄 Auto Reconnection - Exponential backoff retry strategy (max 3 attempts)

View Full Changelog | All Releases

📦 Quick Start

Option 1: Run with npx (Recommended)

npx @erliban/ssh-mcp-server

Option 2: Global Installation

npm install -g @erliban/ssh-mcp-server
ssh-mcp-server

Option 3: Build from Source

git clone https://github.com/jiahuidegit/ssh-mcp-server.git
cd ssh-mcp-server
npm install
npm run build

🔄 Update to Latest Version

If using npx (Recommended)

npx automatically uses the latest version, just restart your MCP client:

# No manual update needed, npx always fetches latest
npx @erliban/ssh-mcp-server

If globally installed

# Update to latest version
npm update -g @erliban/ssh-mcp-server

# Or reinstall
npm install -g @erliban/ssh-mcp-server@latest

Check current version

npm list -g @erliban/ssh-mcp-server

🎮 MCP Client Configuration

This server supports all MCP-compatible clients. Here's an example with Claude Desktop:

Edit the configuration file:

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

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@erliban/ssh-mcp-server"],
      "env": {
        "SSH_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

For other MCP clients, please refer to their respective documentation for configuration methods.

⚙️ Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SSH_MCP_LOG_LEVEL | Log level (debug/info/warn/error) | info | | SSH_MCP_LOG_FILE | Log file path | stderr | | SSH_MCP_CONN_TIMEOUT | Connection timeout (ms) | 30000 | | SSH_MCP_CMD_TIMEOUT | Command timeout (ms) | 60000 | | SSH_MCP_IDLE_TIMEOUT | Idle connection timeout (ms) | 300000 | | SSH_MCP_MAX_CONNECTIONS | Maximum connections | 10 | | SSH_MCP_DATA_DIR | Data directory | ~/.ssh-mcp | | SSH_MCP_MASTER_PASSWORD | Master password for file storage | - |

🛠️ MCP Tools

Connection Management

| Tool | Description | |------|-------------| | connect | Establish SSH connection (password/key auth) | | disconnect | Disconnect specific or all connections |

Server Management

| Tool | Description | |------|-------------| | save_server | Save server configuration locally | | list_servers | List saved servers (supports group filtering) | | remove_server | Remove server configuration |

Command Execution

| Tool | Description | |------|-------------| | exec | Execute remote command | | exec_sudo | Execute with sudo privileges | | exec_batch | Batch execute on multiple servers | | exec_shell | Execute via interactive shell (for bastion hosts) |

SFTP Operations

| Tool | Description | |------|-------------| | sftp_ls | List directory contents | | sftp_upload | Upload file | | sftp_download | Download file | | sftp_mkdir | Create directory | | sftp_rm | Delete file or directory |

System Tools

| Tool | Description | |------|-------------| | health_check | Check connection status | | get_logs | Get audit logs |

💡 Usage Examples

Connect and Execute Command

User: Connect to 192.168.1.100 with username root and password 123456

Claude: [calls connect tool]
Connected to [email protected]:22

User: Check system load

Claude: [calls exec tool]
10:30:01 up 45 days, 2:15, 1 user, load average: 0.15, 0.10, 0.05

Upload Deployment File

User: Upload local /tmp/app.jar to server's /opt/app/

Claude: [calls sftp_upload tool]
Uploaded /tmp/app.jar -> /opt/app/app.jar

Batch Check Server Status

User: Check disk usage on all production servers

Claude: [calls list_servers, then exec_batch]
Server 10.0.0.1: 45% used
Server 10.0.0.2: 62% used
Server 10.0.0.3: 78% used ⚠️

🔒 Security Notes

1. Credential Storage - Prefers system Keychain (macOS Keychain, Windows Credential Manager). Falls back to AES-256-GCM encrypted file storage when no desktop environment is available.
2. Log Masking - Passwords, private keys, and other sensitive information are automatically masked.
3. Dangerous Commands - Operations like deleting system root directory are prohibited.
4. Connection Pool - Automatically cleans up idle connections to prevent resource leaks.

📊 Star History

🤝 Contributing

Issues and Pull Requests are welcome!

📄 License

This project is licensed under the MIT License.

⭐ If you find this project helpful, please give it a star!

🤝 Feel free to open issues for questions or submit PRs for improvements!