Memungkinkan AI client terhubung ke remote server melalui SSH untuk menjalankan command, melihat daftar direktori, serta mengunggah atau mengunduh file via SFTP.
Juga dikenal sebagai pulsemcp/mcp-servers, ssh-agent-mcp-server
- Stars
- 81
- Tools
- 14
- Unduhan, 30 hari
- —
- Versi terbaru
- 0.1.5
- Commit terakhir
- 9 Okt 2026
- Lisensi
- MIT
Apa itu SSH MCP?
SSH adalah MCP server. Memungkinkan AI client terhubung ke remote server melalui SSH untuk menjalankan command, melihat daftar direktori, serta mengunggah atau mengunduh file via SFTP. Server ini menyediakan 14 tool, seperti ssh_connection_info, ssh_list_directory, ssh_download.
Ringkasan dibuat dari README proyek
Tentang SSH MCP server
Mengelola remote server melalui interface AI kini dimungkinkan dengan MCP server ini, yang memungkinkan AI client berinteraksi dengan mesin remote via SSH. Tool ini dirancang untuk developer dan system administrator yang perlu melakukan tugas remote tanpa harus meninggalkan chat interface mereka. Server ini mendukung autentikasi melalui SSH agent, yang sangat ideal untuk menggunakan key yang dilindungi passphrase secara aman, atau melalui path file private key secara langsung.
User dapat melakukan berbagai tugas termasuk menjalankan shell command dengan ssh_execute, menjelajahi remote file system dengan ssh_list_directory, dan mentransfer file menggunakan ssh_upload serta ssh_download via SFTP. Untuk menjaga keamanan, server ini menyertakan tool groups yang memungkinkan Anda membatasi akses ke level readonly, write, atau admin. Server ini juga dilengkapi dengan startup health check untuk memverifikasi konektivitas dan kredensial segera setelah dijalankan, memastikan host dapat dijangkau dan autentikasi valid sebelum Anda memulai workflow.
Apa yang bisa Anda lakukan dengannya
- 1Execute remote shell commandsAI dapat menjalankan shell command tertentu pada host remote untuk melakukan tugas sistem.
- 2Transfer files via SFTPAnda dapat menginstruksikan AI untuk memindahkan file antara mesin lokal dan remote server.
- 3Browse remote directoriesAI dapat memeriksa isi dari remote file system untuk menemukan file tertentu.
- 4Restrict AI permissionsDeveloper dapat membatasi AI agar hanya bisa melihat file dengan mengaktifkan tool group readonly saja.
Ditulis berdasarkan README proyek. Setiap use case diperiksa terhadap kutipan dari README tersebut.
Cara menginstal SSH MCP
Format diverifikasi 10 Nov 2026Tambahkan ke CursorTambahkan ke GooseInstal SSH MCP di Claude Code
$ claude mcp add --env 'SSH_HOST=<SSH_HOST>' --env 'SSH_USERNAME=<SSH_USERNAME>' --env 'SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE>' ssh -- npx -y ssh-agent-mcp-serverInstal SSH MCP di Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": [
"-y",
"ssh-agent-mcp-server"
],
"env": {
"SSH_HOST": "<SSH_HOST>",
"SSH_USERNAME": "<SSH_USERNAME>",
"SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
}
}
}
}Instal SSH MCP di VS Code
.vscode/mcp.json
{
"servers": {
"ssh": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"ssh-agent-mcp-server"
],
"env": {
"SSH_HOST": "<SSH_HOST>",
"SSH_USERNAME": "<SSH_USERNAME>",
"SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
}
}
}
}Instal SSH MCP di VS Code CLI
$ code --add-mcp '{"name":"ssh","type":"stdio","command":"npx","args":["-y","ssh-agent-mcp-server"],"env":{"SSH_HOST":"<SSH_HOST>","SSH_USERNAME":"<SSH_USERNAME>","SSH_PASSPHRASE":"<YOUR_SSH_PASSPHRASE>"}}'Instal SSH MCP di Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": [
"-y",
"ssh-agent-mcp-server"
],
"env": {
"SSH_HOST": "<SSH_HOST>",
"SSH_USERNAME": "<SSH_USERNAME>",
"SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
}
}
}
}Instal SSH MCP di Codex
$ codex mcp add ssh --env 'SSH_HOST=<SSH_HOST>' --env 'SSH_USERNAME=<SSH_USERNAME>' --env 'SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE>' -- npx -y ssh-agent-mcp-serverInstal SSH MCP di Codex config.toml
~/.codex/config.toml
[mcp_servers.ssh] command = "npx" args = ["-y", "ssh-agent-mcp-server"] [mcp_servers.ssh.env] SSH_HOST = "<SSH_HOST>" SSH_USERNAME = "<SSH_USERNAME>" SSH_PASSPHRASE = "<YOUR_SSH_PASSPHRASE>"
Instal SSH MCP di Gemini CLI
$ gemini mcp add -s user -e 'SSH_HOST=<SSH_HOST>' -e 'SSH_USERNAME=<SSH_USERNAME>' -e 'SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE>' ssh npx -- -y ssh-agent-mcp-serverInstal SSH MCP di Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": [
"-y",
"ssh-agent-mcp-server"
],
"env": {
"SSH_HOST": "<SSH_HOST>",
"SSH_USERNAME": "<SSH_USERNAME>",
"SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
}
}
}
}Tool SSH MCP 14
Terdeteksi dari READMEssh_connection_infossh_list_directoryssh_downloadssh_uploadssh_executereadonlywriteadmincommandcwdtimeoutlocalPath
| ssh_connection_info | — | |
| ssh_list_directory | — | |
| ssh_download | — | |
| ssh_upload | — | |
| ssh_execute | — | |
| readonly | — | |
| write | — | |
| admin | — | |
| command | — | |
| cwd | — | |
| timeout | — | |
| localPath | — |
Tampilkan semua 14 toolTampilkan lebih sedikit tool
remotePathpath
| remotePath | — | |
| path | — |
Konfigurasi
SSH_HOSTWajibHostname or IP address of the SSH server.
SSH_USERNAMEWajibUsername for SSH authentication.
SSH_PASSPHRASERahasiaPassphrase for encrypted private key.
ENABLED_TOOLGROUPSComma-separated list of tool groups to enable (readonly, write, admin).
HEALTH_CHECK_TIMEOUTHealth check timeout in milliseconds.
SKIP_HEALTH_CHECKSSkip SSH connection health check on startup.
SSH_AUTH_SOCKPath to SSH agent socket for agent-based authentication.
SSH_COMMAND_TIMEOUTDefault command activity timeout in milliseconds.
SSH_PORTSSH port number.
SSH_PRIVATE_KEY_PATHPath to private key file for direct key authentication.
SSH_TIMEOUTConnection timeout in milliseconds.
| Nama | Deskripsi | Tipe |
|---|---|---|
| SSH_HOST | Hostname or IP address of the SSH server. | Wajib |
| SSH_USERNAME | Username for SSH authentication. | Wajib |
| SSH_PASSPHRASE | Passphrase for encrypted private key. | Rahasia |
| ENABLED_TOOLGROUPS | Comma-separated list of tool groups to enable (readonly, write, admin). | |
| HEALTH_CHECK_TIMEOUT | Health check timeout in milliseconds. | |
| SKIP_HEALTH_CHECKS | Skip SSH connection health check on startup. | |
| SSH_AUTH_SOCK | Path to SSH agent socket for agent-based authentication. | |
| SSH_COMMAND_TIMEOUT | Default command activity timeout in milliseconds. | |
| SSH_PORT | SSH port number. | |
| SSH_PRIVATE_KEY_PATH | Path to private key file for direct key authentication. | |
| SSH_TIMEOUT | Connection timeout in milliseconds. |
Pengecekan otomatis
Berjalan 12 Nov 2026Laporan lengkap →Lolos checks otomatis kami. Ini bukan audit keamanan: baca kodenya dan berikan server akses paling terbatas yang dibutuhkannya. Cara kerja checks
- Source repository terhubung dan dapat dijangkauLolos
- Lisensi open source (OSI)Lolos
- Ada commit atau release dalam satu tahun terakhirLolos
- Nama package tidak mirip dengan package populerLolos
- Remote endpoint menggunakan HTTPSTidak diperiksa
- Tools yang bersifat destruktif telah diberi labelLolos
- Tidak ada instruksi tersembunyi untuk modelLolos
- Tidak ada advisory kritis pada paket atau dependensinyaLolos
README
Lihat di GitHubSSH MCP Server
An MCP (Model Context Protocol) server for SSH remote server management with SSH agent authentication support.
This server solves a common problem with SSH MCP servers: support for passphrase-protected SSH keys. By using SSH agent authentication, you can securely connect to remote servers without exposing your key passphrase.
Highlights
- SSH Agent Authentication - Seamlessly works with passphrase-protected SSH keys via SSH agent
- Private Key File Support - Alternative authentication via direct private key file
- Startup Health Check - Verifies SSH connectivity on startup with clear error messages
- Command Execution - Run shell commands on remote servers
- File Transfer - Upload and download files via SFTP
- Directory Listing - Browse remote file systems
- Tool Groups - Control which tools are available (readonly, write, admin)
Authentication Priority
The server supports multiple authentication methods and will use them in this order:
- SSH Agent (recommended) - If
SSH_AUTH_SOCKis set or auto-detected - Private Key File - If
SSH_PRIVATE_KEY_PATHis set
Both methods can be configured simultaneously. If SSH agent authentication is available, it takes priority. The private key file method is used as a fallback or when the agent is not available.
Capabilities
Tools
| Tool | Group | Description |
|---|---|---|
ssh_connection_info |
readonly, write, admin | Get configured SSH connection information |
ssh_list_directory |
readonly, write, admin | List directory contents on remote server |
ssh_download |
readonly, write, admin | Download file from remote server via SFTP |
ssh_upload |
write, admin | Upload file to remote server via SFTP |
ssh_execute |
admin | Execute shell command on remote server |
Resources
| Resource | Description |
|---|---|
ssh://config |
SSH connection configuration and status (for debugging) |
Tool Groups
Control which tools are available via the ENABLED_TOOLGROUPS environment variable:
| Group | Description |
|---|---|
readonly |
Safe operations (connection info, list, download) |
write |
File modifications (upload) |
admin |
Full access including command execution |
Examples:
ENABLED_TOOLGROUPS="readonly"- Only allow browsing and downloadsENABLED_TOOLGROUPS="readonly,write"- Allow file transfers but no command execution- Not set - All tools enabled (default)
Startup Health Check
The server performs an SSH connection health check on startup to verify that the configured credentials and host are valid. This provides immediate feedback if there are configuration issues, rather than discovering them during workflow.
Benefits:
- Faster feedback: Configuration errors surface at startup rather than mid-workflow
- Clearer error messages: Startup failures include hints for common issues
- Improved user experience: Eliminates ambiguity about server operational status
Configuration:
SKIP_HEALTH_CHECKS=true- Skip the health check (useful for lazy connection scenarios)HEALTH_CHECK_TIMEOUT=10000- Customize the health check timeout (default: 10 seconds)
Error hints provided for:
- Authentication failures (SSH key not loaded, wrong key)
- Connection timeouts (host unreachable)
- Connection refused (SSH server not running)
- DNS resolution errors (invalid hostname)
Quick Start
Installation
npx ssh-agent-mcp-server
Or install globally:
npm install -g ssh-agent-mcp-server
Configuration
Environment Variables
| Variable | Required | Description | Default |
|---|---|---|---|
SSH_HOST |
Yes | Hostname or IP address of the SSH server | - |
SSH_USERNAME |
Yes | Username for SSH authentication | - |
SSH_PORT |
No | SSH port number | 22 |
SSH_AUTH_SOCK |
No | Path to SSH agent socket | Auto-detected |
SSH_PRIVATE_KEY_PATH |
No | Path to private key file | - |
SSH_PASSPHRASE |
No | Passphrase for encrypted private key | - |
SSH_TIMEOUT |
No | Connection timeout in milliseconds | 30000 |
SSH_COMMAND_TIMEOUT |
No | Default command activity timeout in milliseconds | 60000 |
ENABLED_TOOLGROUPS |
No | Comma-separated tool groups | All enabled |
SKIP_HEALTH_CHECKS |
No | Skip SSH connection health check on startup | false |
HEALTH_CHECK_TIMEOUT |
No | Health check timeout in milliseconds | 10000 |
Claude Desktop Configuration
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": ["-y", "ssh-agent-mcp-server"],
"env": {
"SSH_HOST": "192.168.1.100",
"SSH_USERNAME": "deploy",
"SSH_AUTH_SOCK": "${SSH_AUTH_SOCK}"
}
}
}
}
Restart Claude Desktop and you should be ready to go!
SSH Agent Authentication (Recommended)
SSH agent authentication is the recommended method for passphrase-protected keys:
-
Ensure your SSH agent is running with your key loaded:
# Check if agent is running ssh-add -l # If not, add your key ssh-add ~/.ssh/id_ed25519 -
Pass the
SSH_AUTH_SOCKenvironment variable to the MCP server
The server will automatically use the agent for authentication, and your passphrase-protected key stays secure in the agent.
How It Works
- Your passphrase-protected key is loaded into the SSH agent via
ssh-add - The agent exposes a Unix socket at
$SSH_AUTH_SOCK - This MCP server connects to that socket via the
ssh2library - The agent signs authentication challenges using your decrypted key
- Your private key never leaves the agent - the MCP server never sees it
This is more secure than:
- Storing your passphrase in environment variables
- Using unprotected private keys
- Manually entering passphrases
Tool Details
ssh_execute
Execute a command on the remote server.
Parameters:
command(required): Shell command to executecwd(optional): Working directorytimeout(optional): Activity timeout in milliseconds (default: 60000 orSSH_COMMAND_TIMEOUT)
Activity-based Timeout:
The timeout is activity-based rather than absolute. It resets whenever stdout or stderr output is received from the command. This allows long-running commands that produce periodic output (like builds, deployments, or claude -p commands) to complete successfully, while still timing out commands that hang with no activity.
For commands with delayed initial output (10-30+ seconds before any output), you can:
- Increase the default timeout via
SSH_COMMAND_TIMEOUTenvironment variable - Pass a higher
timeoutparameter for specific commands
Example:
{
"command": "ls -la /var/log",
"cwd": "/home/user"
}
Example with extended timeout for long-running commands:
{
"command": "npm run build",
"timeout": 300000
}
Returns: JSON with stdout, stderr, and exit code
ssh_upload
Upload a file to the remote server via SFTP.
Parameters:
localPath(required): Absolute path to local fileremotePath(required): Destination path on server
ssh_download
Download a file from the remote server via SFTP.
Parameters:
remotePath(required): Path on remote serverlocalPath(required): Local destination path
ssh_list_directory
List directory contents on the remote server.
Parameters:
path(required): Directory path to list
Returns: JSON array with filename, type, size, permissions, modified time
ssh_connection_info
Get information about the configured SSH connection.
Returns: JSON with host, port, username, and authentication details
Development
# Install dependencies
npm run install-all
# Build
npm run build
# Run in development mode
npm run dev
# Run tests
npm test
npm run test:integration
License
MIT
Pertanyaan tentang SSH MCP
Bagaimana cara menambahkan SSH MCP ke Claude Code?
Jalankan claude mcp add --env 'SSH_HOST=<SSH_HOST>' --env 'SSH_USERNAME=<SSH_USERNAME>' --env 'SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE>' ssh -- npx -y ssh-agent-mcp-server di terminal Anda. Tambahkan --scope user agar tersedia di semua proyek.
Bagaimana cara menambahkan SSH MCP ke Cursor?
Buka ~/.cursor/mcp.json dan tambahkan server di bawah mcpServers, menggunakan config Cursor yang ditunjukkan di bagian instalasi di atas.
Tool apa yang disediakan SSH MCP?
Server ini menyediakan 14 tool, termasuk ssh_connection_info, ssh_list_directory, ssh_download, ssh_upload, ssh_execute.
Bagaimana SSH MCP server menangani SSH key yang dilindungi passphrase?
Server melakukan autentikasi melalui SSH agent Anda, sehingga key yang sudah didekripsi tetap berada di dalam agent dan tidak pernah terekspos ke server. Anda cukup memuat key menggunakan ssh-add dan meneruskan SSH_AUTH_SOCK ke server.
Metode autentikasi apa saja yang didukung oleh SSH MCP server dan dalam urutan seperti apa?
Server akan mencoba menggunakan SSH agent terlebih dahulu jika SSH_AUTH_SOCK terdeteksi atau diatur, kemudian beralih ke file private key yang dikonfigurasi melalui SSH_PRIVATE_KEY_PATH.
Bagaimana cara membatasi apa yang bisa dilakukan oleh SSH MCP server?
Atur environment variable ENABLED_TOOLGROUPS ke readonly, write, atau admin, atau kombinasi dari ketiganya. Jika tidak diatur, semua tool akan aktif.
Apakah SSH MCP server memeriksa koneksi saat startup?
Ya, server menjalankan health check koneksi SSH saat startup dan memberikan petunjuk jika terjadi kegagalan autentikasi, timeout, koneksi ditolak, atau error DNS. Anda bisa melewati proses ini dengan menggunakan SKIP_HEALTH_CHECKS=true.
Apa fungsi dari tool ssh_execute dan bagaimana cara kerja timeout-nya?
Tool ini menjalankan shell command pada remote server dan mengembalikan stdout, stderr, serta exit code. Timeout berbasis pada aktivitas, yang akan direset setiap kali ada output yang masuk, dengan nilai default 60000 ms atau sesuai SSH_COMMAND_TIMEOUT.