Bir AI istemcisinin komut çalıştırması, dizinleri listelemesi ve SFTP üzerinden dosya yükleyip indirmesi için SSH aracılığıyla uzak bir sunucuya bağlanmasını sağlar.
Ayrıca bilinen adı pulsemcp/mcp-servers, ssh-agent-mcp-server
- Yıldızlar
- 81
- Araçlar
- 14
- İndirmeler, 30 gün
- —
- En son sürüm
- 0.1.5
- Son commit
- 9 Eki 2026
- Lisans
- MIT
SSH MCP nedir?
SSH bir MCP sunucusudur. Bir AI istemcisinin komut çalıştırması, dizinleri listelemesi ve SFTP üzerinden dosya yükleyip indirmesi için SSH aracılığıyla uzak bir sunucuya bağlanmasını sağlar. 14 araç sunar; örneğin ssh_connection_info, ssh_list_directory, ssh_download.
Özet, projenin README dosyasından oluşturuldu
SSH MCP sunucusu hakkında
Bir AI istemcisinin SSH üzerinden uzak makinelerle etkileşime girmesine olanak tanıyan bu MCP server ile uzak sunucuları bir AI arayüzü üzerinden yönetmek mümkündür. Sohbet arayüzünden ayrılmadan uzak görevleri yerine getirmesi gereken geliştiriciler ve sistem yöneticileri için tasarlanmıştır. Sunucu, parola korumalı anahtarların güvenli kullanımı için ideal olan SSH agent üzerinden kimlik doğrulamayı veya doğrudan bir özel anahtar dosyası yolu üzerinden kimlik doğrulamayı destekler.
Kullanıcılar; ssh_execute ile shell komutları çalıştırma, ssh_list_directory ile uzak dosya sistemlerinde gezinme ve SFTP aracılığıyla ssh_upload ve ssh_download kullanarak dosya transferi yapma gibi çeşitli görevleri gerçekleştirebilirler. Güvenliği sağlamak amacıyla sunucu, erişimi readonly, write veya admin seviyeleriyle kısıtlamanıza olanak tanıyan araç grupları içerir. Ayrıca, bir iş akışına başlamadan önce ana makine erişilebilirliğinin ve kimlik doğrulamanın geçerli olduğundan emin olmak için başlatma sırasında bağlantıyı ve kimlik bilgilerini doğrulayan bir sağlık kontrolü özelliğine sahiptir.
Neler yapabilirsiniz
- 1Uzak shell komutlarını yürütmeBir AI, sistem görevlerini yerine getirmek için uzak bir ana makinede belirli shell komutlarını çalıştırabilir.
- 2SFTP üzerinden dosya transferiBir AI'ya yerel makineniz ile uzak bir sunucu arasında dosya taşıması talimatını verebilirsiniz.
- 3Uzak dizinlerde gezinmeBir AI, belirli dosyaları bulmak için uzak bir dosya sisteminin içeriğini inceleyebilir.
- 4AI izinlerini kısıtlamaGeliştiriciler, yalnızca readonly araç grubunu etkinleştirerek AI'nın sadece dosyaları görüntülemesini sağlayabilirler.
Projenin README dosyasından alınmıştır. Her kullanım durumu, oradaki bir alıntı ile kontrol edilir.
SSH MCP nasıl yüklenir
Biçimler 10 Kas 2026 tarihinde doğrulandıCursor'a ekleGoose'a ekleSSH MCP'yi Claude Code içine yükleyin
$ 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-serverSSH MCP'yi Cursor içine yükleyin
~/.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>"
}
}
}
}SSH MCP'yi VS Code içine yükleyin
.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>"
}
}
}
}SSH MCP'yi VS Code CLI içine yükleyin
$ 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>"}}'SSH MCP'yi Claude Desktop içine yükleyin
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>"
}
}
}
}SSH MCP'yi Codex içine yükleyin
$ 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-serverSSH MCP'yi Codex config.toml içine yükleyin
~/.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>"
SSH MCP'yi Gemini CLI içine yükleyin
$ 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-serverSSH MCP'yi Gemini settings.json içine yükleyin
~/.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>"
}
}
}
}SSH MCP araçları 14
README dosyasından algılandıssh_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 | — |
14 aracın tümünü gösterDaha az araç göster
remotePathpath
| remotePath | — | |
| path | — |
Yapılandırma
SSH_HOSTGerekliHostname or IP address of the SSH server.
SSH_USERNAMEGerekliUsername for SSH authentication.
SSH_PASSPHRASEGizliPassphrase 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.
| Ad | Açıklama | Sunucu |
|---|---|---|
| SSH_HOST | Hostname or IP address of the SSH server. | Gerekli |
| SSH_USERNAME | Username for SSH authentication. | Gerekli |
| SSH_PASSPHRASE | Passphrase for encrypted private key. | Gizli |
| 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. |
Otomatik kontroller
Çalıştırıldı 12 Kas 2026Tam rapor →Otomatik kontrollerimizden geçti. Bu bir güvenlik denetimi değildir: kodu okuyun ve sunucuya ihtiyaç duyduğu en dar erişimi verin. Kontroller nasıl çalışır
- Kaynak deposu bağlantılı ve erişilebilirGeçti
- Açık kaynak lisansı (OSI)Geçti
- Son bir yıl içinde commit veya sürüm mevcutGeçti
- Paket adı popüler bir pakete yakın değilGeçti
- Uzak uç nokta HTTPS kullanıyorKontrol edilmedi
- Yıkıcı araçlar etiketlenmişGeçti
- Modele yönelik gizli talimat yokGeçti
- Pakette veya bağımlılıklarında kritik uyarı yokGeçti
SSH 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
SSH MCP soruları
SSH MCP'yi Claude Code'a nasıl eklerim?
Terminalinizde 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 komutunu çalıştırın. Her projede kullanılabilir olması için --scope user ekleyin.
SSH MCP'yi Cursor'a nasıl eklerim?
~/.cursor/mcp.json dosyasını açın ve yukarıdaki yükleme bölümünde gösterilen Cursor yapılandırmasını kullanarak sunucuyu mcpServers altına ekleyin.
SSH MCP hangi araçları sunar?
14 araç sunar; bunlar arasında ssh_connection_info, ssh_list_directory, ssh_download, ssh_upload, ssh_execute yer alır.
SSH MCP server, parola korumalı SSH anahtarlarını nasıl yönetir?
Kimlik doğrulama işlemini SSH agent üzerinden gerçekleştirir; böylece çözülmüş anahtarınız agent içinde kalır ve sunucuya asla açığa çıkmaz. Anahtarınızı ssh-add ile yükleyebilir ve SSH_AUTH_SOCK değişkenini sunucuya iletebilirsiniz.
SSH MCP server hangi kimlik doğrulama yöntemlerini hangi sırayla destekler?
Eğer SSH_AUTH_SOCK ayarlanmışsa veya otomatik olarak algılanırsa önce SSH agent yöntemini dener, ardından SSH_PRIVATE_KEY_PATH ile yapılandırılmış bir özel anahtar dosyasına geçer.
SSH MCP server'ın yetkilerini nasıl kısıtlayabilirim?
ENABLED_TOOLGROUPS ortam değişkenini readonly, write, admin veya bunların kombinasyonlarından biri olarak ayarlayabilirsiniz. Ayarlanmadığı takdirde tüm araçlar etkinleştirilir.
SSH MCP server başlatıldığında bağlantıyı kontrol eder mi?
Evet, başlatma sırasında bir SSH bağlantı sağlık kontrolü çalıştırır; kimlik doğrulama hataları, zaman aşımı, reddedilen bağlantılar ve DNS hataları için ipuçları sunar. SKIP_HEALTH_CHECKS=true ile bu adımı atlayabilirsiniz.
ssh_execute aracı ne işe yarar ve zaman aşımı nasıl çalışır?
Uzak sunucuda bir shell komutu çalıştırır; stdout, stderr ve çıkış kodunu döndürür. Zaman aşımı aktivite tabanlıdır, her çıktı geldiğinde sıfırlanır ve varsayılan olarak 60000 ms veya SSH_COMMAND_TIMEOUT değeridir.