ssh — Claude Code MCP server: what it does, how to install
This MCP server connects an AI agent to a remote host over SSH for commands, directory browsing, and SFTP transfers. It can use an SSH agent.
claude mcp add --env SSH_HOST=<SSH_HOST> --env SSH_USERNAME=<SSH_USERNAME> --env SSH_PORT=<SSH_PORT> --env SSH_AUTH_SOCK=<SSH_AUTH_SOCK> --env SSH_PRIVATE_KEY_PATH=<SSH_PRIVATE_KEY_PATH> --transport stdio ssh -- npx -y ssh-agent-mcp-serverWhat ssh does
The server exposes an SSH connection to an AI agent. It can report connection details, list remote directories, download and upload files through SFTP, and run shell commands on the remote host. SSH_HOST and SSH_USERNAME are required for a connection.
Authentication uses the SSH agent through SSH_AUTH_SOCK first. If the agent is unavailable, the server can use SSH_PRIVATE_KEY_PATH instead. A startup health check tests the connection and reports common configuration problems. Set ENABLED_TOOLGROUPS to limit access: readonly permits browsing and downloads, write adds uploads, and admin includes command execution. The server runs with npx -y ssh-agent-mcp-server.
What it helps with
- connect an agent to a remote SSH host
- run a shell command on a remote machine
- browse a remote directory
- download a file through SFTP
- upload a file to the server
Example prompts for the agent
- Check the connection and report the result with
ssh_connection_info. - List the contents of the remote directory with
ssh_list_directory. - Run
git statuson the remote host withssh_execute.
How to install ssh
Platform CLI
claude mcp add --env SSH_HOST=<SSH_HOST> --env SSH_USERNAME=<SSH_USERNAME> --env SSH_PORT=<SSH_PORT> --env SSH_AUTH_SOCK=<SSH_AUTH_SOCK> --env SSH_PRIVATE_KEY_PATH=<SSH_PRIVATE_KEY_PATH> --transport stdio ssh -- npx -y ssh-agent-mcp-serverReplace <…> with your own values. 6 more environment variables are in the server README
Platform CLI
codex mcp add ssh --env SSH_HOST=<SSH_HOST> --env SSH_USERNAME=<SSH_USERNAME> --env SSH_PORT=<SSH_PORT> --env SSH_AUTH_SOCK=<SSH_AUTH_SOCK> --env SSH_PRIVATE_KEY_PATH=<SSH_PRIVATE_KEY_PATH> -- npx -y ssh-agent-mcp-serverReplace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": [
"-y",
"ssh-agent-mcp-server"
],
"env": {
"SSH_HOST": "<SSH_HOST>",
"SSH_USERNAME": "<SSH_USERNAME>",
"SSH_PORT": "<SSH_PORT>",
"SSH_AUTH_SOCK": "<SSH_AUTH_SOCK>",
"SSH_PRIVATE_KEY_PATH": "<SSH_PRIVATE_KEY_PATH>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"servers": {
"ssh": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"ssh-agent-mcp-server"
],
"env": {
"SSH_HOST": "<SSH_HOST>",
"SSH_USERNAME": "<SSH_USERNAME>",
"SSH_PORT": "<SSH_PORT>",
"SSH_AUTH_SOCK": "<SSH_AUTH_SOCK>",
"SSH_PRIVATE_KEY_PATH": "<SSH_PRIVATE_KEY_PATH>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
Platform CLI
gemini mcp add -e SSH_HOST=<SSH_HOST> -e SSH_USERNAME=<SSH_USERNAME> -e SSH_PORT=<SSH_PORT> -e SSH_AUTH_SOCK=<SSH_AUTH_SOCK> -e SSH_PRIVATE_KEY_PATH=<SSH_PRIVATE_KEY_PATH> ssh npx -y ssh-agent-mcp-serverReplace <…> with your own values. 6 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ssh
How do I install ssh in Claude Code?
Run claude mcp add ssh -e SSH_HOST=<SSH_HOST> -e SSH_USERNAME=<SSH_USERNAME> -e SSH_PASSPHRASE=<SSH_PASSPHRASE> -- npx -y ssh-agent-mcp-server. Provide the host, username, and authentication settings for the target server.
What does the ssh MCP server do?
It gives an AI agent SSH access to a remote host for directory listing, SFTP file transfers, connection details, and shell commands.
How can I restrict the ssh tools?
Set ENABLED_TOOLGROUPS. readonly allows safe browsing and downloads, readonly,write also permits uploads, and admin enables command execution.
