Permet à un client IA de se connecter à un serveur distant via SSH pour exécuter des commandes, lister des répertoires et transférer des fichiers par SFTP.
Aussi connu sous pulsemcp/mcp-servers, ssh-agent-mcp-server
- Étoiles
- 81
- Outils
- 14
- Téléchargements, 30 jours
- —
- Dernière version
- 0.1.5
- Dernier commit
- 9 oct. 2026
- Licence
- MIT
Qu'est-ce que SSH MCP ?
SSH est un serveur MCP. Permet à un client IA de se connecter à un serveur distant via SSH pour exécuter des commandes, lister des répertoires et transférer des fichiers par SFTP. Il expose 14 outils, comme ssh_connection_info, ssh_list_directory, ssh_download.
Résumé généré à partir du README du projet
À propos du MCP server SSH
La gestion de serveurs distants via une interface IA est possible grâce à ce MCP server, qui permet à un client IA d'interagir avec des machines distantes via SSH. Il est conçu pour les développeurs et les administrateurs système qui doivent effectuer des tâches à distance sans quitter leur interface de chat. Le serveur prend en charge l'authentification via un agent SSH, ce qui est idéal pour utiliser des clés protégées par une passphrase en toute sécurité, ou via le chemin direct d'un fichier de clé privée.
Les utilisateurs peuvent effectuer une variété de tâches, notamment l'exécution de commandes shell avec ssh_execute, la navigation dans les systèmes de fichiers distants avec ssh_list_directory, et le transfert de fichiers via ssh_upload et ssh_download par SFTP. Pour maintenir la sécurité, le serveur inclut des groupes d'outils (tool groups) qui vous permettent de restreindre l'accès aux niveaux readonly, write ou admin. Il dispose également d'un contrôle de santé au démarrage pour vérifier la connectivité et les identifiants dès le lancement, garantissant que l'accessibilité de l'hôte et l'authentification sont valides avant de commencer un flux de travail.
Ce que vous pouvez faire avec
- 1Exécuter des commandes shell à distanceUne IA peut exécuter des commandes shell spécifiques sur un hôte distant pour effectuer des tâches système.
- 2Transférer des fichiers via SFTPVous pouvez ordonner à une IA de déplacer des fichiers entre votre machine locale et un serveur distant.
- 3Parcourir des répertoires distantsUne IA peut inspecter le contenu d'un système de fichiers distant pour localiser des fichiers spécifiques.
- 4Restreindre les permissions de l'IALes développeurs peuvent limiter l'IA à la simple consultation de fichiers en n'activant que le groupe d'outils readonly.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer SSH MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller SSH MCP dans 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-serverInstaller SSH MCP dans 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>"
}
}
}
}Installer SSH MCP dans 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>"
}
}
}
}Installer SSH MCP dans 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>"}}'Installer SSH MCP dans 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>"
}
}
}
}Installer SSH MCP dans 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-serverInstaller SSH MCP dans 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>"
Installer SSH MCP dans 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-serverInstaller SSH MCP dans 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>"
}
}
}
}Outils MCP SSH 14
Détectés depuis le 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 | — |
Afficher les 14 outilsAfficher moins d'outils
remotePathpath
| remotePath | — | |
| path | — |
Configuration
SSH_HOSTRequisHostname or IP address of the SSH server.
SSH_USERNAMERequisUsername for SSH authentication.
SSH_PASSPHRASESecretPassphrase 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.
| Nom | Description | Type |
|---|---|---|
| SSH_HOST | Hostname or IP address of the SSH server. | Requis |
| SSH_USERNAME | Username for SSH authentication. | Requis |
| SSH_PASSPHRASE | Passphrase for encrypted private key. | Secret |
| 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. |
Vérifications automatisées
Exécuté le 12 nov. 2026Rapport complet →A passé nos vérifications automatisées. Il ne s'agit pas d'un audit de sécurité : lisez le code et donnez au serveur l'accès le plus restreint dont il a besoin. Fonctionnement des vérifications
- Dépôt source lié et accessibleRéussi
- Licence open source (OSI)Réussi
- Commit ou version publiée au cours de l'année écouléeRéussi
- Nom du package non proche d'un package populaireRéussi
- L'endpoint distant utilise HTTPSNon vérifié
- Les outils destructifs sont étiquetésRéussi
- Aucune instruction cachée destinée au modèleRéussi
- Aucun avis critique dans le package ou ses dépendancesRéussi
README
Voir sur 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
Questions sur SSH MCP
Comment ajouter SSH MCP à Claude Code ?
Exécutez 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 dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter SSH MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Quels outils SSH MCP fournit-il ?
Il expose 14 outils, dont ssh_connection_info, ssh_list_directory, ssh_download, ssh_upload, ssh_execute.
Comment le MCP server SSH gère-t-il les clés SSH protégées par une passphrase ?
Il s'authentifie via votre agent SSH, ce qui signifie que votre clé déchiffrée reste dans l'agent et n'est jamais exposée au serveur. Vous chargez votre clé avec ssh-add et transmettez SSH_AUTH_SOCK au serveur.
Quelles méthodes d'authentification le MCP server SSH prend-il en charge et dans quel ordre ?
Il tente d'abord d'utiliser l'agent SSH si SSH_AUTH_SOCK est défini ou détecté automatiquement, puis utilise en dernier recours un fichier de clé privée configuré via SSH_PRIVATE_KEY_PATH.
Comment puis-je restreindre les actions du MCP server SSH ?
Définissez la variable d'environnement ENABLED_TOOLGROUPS sur readonly, write, ou admin, ou une combinaison de ces valeurs. Si elle n'est pas définie, tous les outils sont activés.
Le MCP server SSH vérifie-t-il la connexion au démarrage ?
Oui, il effectue un contrôle de l'état de la connexion SSH au démarrage et fournit des indications en cas d'échec d'authentification, de timeout, de connexion refusée ou d'erreurs DNS. Vous pouvez ignorer cette étape avec SKIP_HEALTH_CHECKS=true.
Que fait l'outil ssh_execute et comment fonctionne son timeout ?
Il exécute une commande shell sur le serveur distant et renvoie stdout, stderr et le code de sortie. Le timeout est basé sur l'activité : il se réinitialise à chaque réception de sortie et est fixé par défaut à 60000 ms ou via SSH_COMMAND_TIMEOUT.