Permite que un cliente de IA se conecte a un servidor remoto mediante SSH para ejecutar comandos, listar directorios y subir o descargar archivos vía SFTP.
También conocido como pulsemcp/mcp-servers, ssh-agent-mcp-server
- Stars
- 81
- Herramientas
- 14
- Descargas, 30 días
- —
- Última versión
- 0.1.5
- Último commit
- 9 oct 2026
- Licencia
- MIT
¿Qué es SSH MCP?
SSH es un MCP server. Permite que un cliente de IA se conecte a un servidor remoto mediante SSH para ejecutar comandos, listar directorios y subir o descargar archivos vía SFTP. Expone 14 herramientas, como ssh_connection_info, ssh_list_directory, ssh_download.
Resumen generado a partir del README del proyecto
Acerca del MCP server de SSH
Gestionar servidores remotos mediante una interfaz de IA es posible con este MCP server, que permite a un cliente de IA interactuar con máquinas remotas vía SSH. Está diseñado para desarrolladores y administradores de sistemas que necesitan realizar tareas remotas sin salir de su interfaz de chat. El servidor admite la autenticación a través de un agente SSH, lo cual es ideal para usar llaves protegidas con frase de paso de forma segura, o mediante la ruta directa a un archivo de llave privada.
Los usuarios pueden realizar una gran variedad de tareas, incluyendo la ejecución de comandos de shell con ssh_execute, la exploración de sistemas de archivos remotos con ssh_list_directory y la transferencia de archivos mediante ssh_upload y ssh_download vía SFTP. Para mantener la seguridad, el servidor incluye grupos de herramientas que te permiten restringir el acceso a niveles de solo lectura (readonly), escritura (write) o administración (admin). También cuenta con un control de salud al inicio para verificar la conectividad y las credenciales inmediatamente después del lanzamiento, asegurando que la alcanzabilidad del host y la autenticación sean válidas antes de comenzar un flujo de trabajo.
Qué puedes hacer con él
- 1Ejecutar comandos de shell remotosUna IA puede ejecutar comandos de shell específicos en un host remoto para realizar tareas del sistema.
- 2Transferir archivos vía SFTPPuedes instruir a una IA para mover archivos entre tu máquina local y un servidor remoto.
- 3Explorar directorios remotosUna IA puede inspeccionar el contenido de un sistema de archivos remoto para localizar archivos específicos.
- 4Restringir permisos de la IALos desarrolladores pueden limitar a la IA para que solo pueda ver archivos habilitando únicamente el grupo de herramientas readonly.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Cómo instalar SSH MCP
Formatos verificados el 10 nov 2026Añadir a CursorAñadir a GooseInstalar SSH MCP en 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-serverInstalar SSH MCP en 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>"
}
}
}
}Instalar SSH MCP en 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>"
}
}
}
}Instalar SSH MCP en 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>"}}'Instalar SSH MCP en 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>"
}
}
}
}Instalar SSH MCP en 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-serverInstalar SSH MCP en 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>"
Instalar SSH MCP en 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-serverInstalar SSH MCP en 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>"
}
}
}
}Herramientas de SSH MCP 14
Detectado desde el 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 | — |
Mostrar las 14 herramientasMostrar menos herramientas
remotePathpath
| remotePath | — | |
| path | — |
Configuración
SSH_HOSTObligatorioHostname or IP address of the SSH server.
SSH_USERNAMEObligatorioUsername for SSH authentication.
SSH_PASSPHRASESecretoPassphrase 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.
| Nombre | Descripción | Tipo |
|---|---|---|
| SSH_HOST | Hostname or IP address of the SSH server. | Obligatorio |
| SSH_USERNAME | Username for SSH authentication. | Obligatorio |
| SSH_PASSPHRASE | Passphrase for encrypted private key. | Secreto |
| 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. |
Verificaciones automáticas
Ejecutado 12 nov 2026Informe completo →Pasó nuestras verificaciones automáticas. Esto no es una auditoría de seguridad: lee el código y dale al servidor el acceso más limitado que necesite. Cómo funcionan las verificaciones
- Repositorio de origen vinculado y accesibleAprobado
- Licencia de código abierto (OSI)Aprobado
- Commit o lanzamiento en el último añoAprobado
- El nombre del paquete no es similar a un paquete popularAprobado
- El endpoint remoto usa HTTPSNo verificado
- Las herramientas destructivas están etiquetadasAprobado
- Sin instrucciones ocultas para el modeloAprobado
- No hay avisos críticos en el paquete ni en sus dependenciasAprobado
README
Ver en 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
Preguntas sobre SSH MCP
¿Cómo agrego SSH MCP a Claude Code?
Ejecuta 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 en tu terminal. Añade --scope user para que esté disponible en todos los proyectos.
¿Cómo agrego SSH MCP a Cursor?
Abre ~/.cursor/mcp.json y añade el servidor en mcpServers, usando la configuración de Cursor que se muestra en la sección de instalación de arriba.
¿Qué herramientas proporciona SSH MCP?
Expone 14 herramientas, incluidas ssh_connection_info, ssh_list_directory, ssh_download, ssh_upload, ssh_execute.
¿Cómo gestiona el MCP server de SSH las llaves SSH protegidas con frase de paso?
Se autentica a través de tu agente SSH, por lo que tu llave desencriptada permanece en el agente y nunca se expone al servidor. Debes cargar tu llave con ssh-add y pasar SSH_AUTH_SOCK al servidor.
¿Qué métodos de autenticación soporta el MCP server de SSH y en qué orden?
Primero intenta usar el agente SSH si SSH_AUTH_SOCK está configurado o se detecta automáticamente; luego, recurre a un archivo de llave privada configurado con SSH_PRIVATE_KEY_PATH.
¿Cómo puedo restringir lo que el MCP server de SSH puede hacer?
Configura la variable de entorno ENABLED_TOOLGROUPS en readonly, write, admin, o una combinación de estas. Si no se establece, se habilitan todas las herramientas.
¿El MCP server de SSH verifica la conexión al iniciar?
Sí, realiza un control de salud de la conexión SSH al arrancar y proporciona pistas en caso de fallos de autenticación, tiempos de espera agotados, conexiones rechazadas o errores de DNS. Puedes omitirlo usando SKIP_HEALTH_CHECKS=true.
¿Qué hace la herramienta ssh_execute y cómo funciona su timeout?
Ejecuta un comando de shell en el servidor remoto y devuelve stdout, stderr y el código de salida. El timeout se basa en la actividad, reiniciándose cada vez que llega una salida, y tiene un valor predeterminado de 60000 ms o lo que indique SSH_COMMAND_TIMEOUT.