Ssh

Frequently asked questions

What does the Ssh MCP server do?

MCP SSH Agent A Model Context Protocol (MCP) server for managing and controlling SSH connections. This server integrates seamlessly with Claude Desktop and other MCP-compatible clients to provide AI-powered SSH operations. Overview This MCP server provides SSH operations through a clean, standardized interface that can be used by MCP-compatible language models like Claude Desktop. The server automatically discovers SSH hosts from your /.ssh/config and /.ssh/known hosts files and executes commands using native SSH tools for maximum reliability. Quick Start MCP Bundle Installation (Recommended) The easiest way to install MCP SSH Agent is as an MCP Bundle: Download the latest mcp-ssh- .mcpb file from the GitHub releases page Double-click the .mcpb file to install it in Claude Desktop > The bundle format was previously called a Desktop Extension and used the .dxt > extension. v1.3.9 shipped both files during the transition; later releases carry > .mcpb only. If your Claude Desktop is old enough to reject a .mcpb file, > update it or use one of the installation methods below. The SSH tools will be automatically available in your conversations with Claude Alternative Installation Methods Installation via npx Manual Claude Desktop Configuration To use this MCP server with Claude Desktop using manual configuration, add the following to your MCP settings file: On macOS : /Library/Application Support/Claude/claude desktop config.json On Windows : %APPDATA%/Claude/claude desktop config.json After adding this configuration, restart Claude Desktop. The SSH tools will be available for use in your conversations with Claude. Global Installation Local Development The server is TypeScript under src/ ; npm install builds it. After editing sources run npm run build (or npm test , which reads src/ directly). Example Usage The screenshot above shows the MCP SSH Agent in action, demonstrating how it integrates with MCP-compatible clients to provide seamless SSH operations. Integration with Claude This screenshot demonstrates the MCP SSH Agent integrated with Claude, showing how the AI assistant can directly manage SSH connections and execute remote commands through the MCP protocol. Key Features Reliable SSH : Uses native ssh / scp commands instead of JavaScript SSH libraries Automatic Discovery : Finds hosts from SSH config and known hosts files Full SSH Support : Works with SSH agents, keys, and all authentication methods Password Authentication : Supports password-based SSH login and key passphrases via @password annotation — passwords never leave your machine File Operations : Upload and download files using scp Batch Commands : Execute multiple commands in sequence Error Handling : Comprehensive error reporting with timeouts Functions The agent provides the following MCP tools: listKnownHosts() - Lists all known SSH hosts, prioritizing entries from /.ssh/config first, then additional hosts from /.ssh/known hosts runRemoteCommand(hostAlias, command) - Executes a command on a remote host using ssh getHostInfo(hostAlias) - Returns detailed configuration for a specific host checkConnectivity(hostAlias) - Tests SSH connectivity to a host uploadFile(hostAlias, localPath, remotePath) - Uploads a file to the remote host using scp downloadFile(hostAlias, remotePath, localPath) - Downloads a file from the remote host using scp runCommandBatch(hostAlias, commands) - Executes multiple commands sequentially Configuration Examples Claude Desktop Integration Here's how your Claude Desktop configuration should look: Manual Server Configuration If you prefer to run the server manually or integrate it with other MCP clients: Requirements Node.js 20 or higher SSH client installed ( ssh and scp commands available) SSH configuration files ( /.ssh/config and /.ssh/known hosts ) Usage with Claude Desktop Once configured, you can ask Claude to help you with SSH operations like: "List all my SSH hosts" "Check connectivity to my production server" "Run a command on my web server" "Upload this file to my remote server" "Download logs from my application server" Claude will use the MCP SSH tools to perform these operations safely and efficiently. Usage The agent runs as a Model Context Protocol server over STDIO. When installed via npm, you can use it directly: The server communicates via clean JSON over STDIO, making it perfect for MCP clients like Claude Desktop. Advanced Configuration Environment Variables MCP SILENT=true - Disable debug output (automatically set when used as MCP server) SSH Configuration The agent reads from standard SSH configuration files: /.ssh/config - SSH client configuration (supports Include directives) /.ssh/known hosts - Known host keys Make sure your SSH keys are properly configured and accessible via SSH agent or key files. Password Authentication For hosts that require password-based authentication (common with network infrastructure like switches and routers), you can store the password directly in your /.ssh/config using a special comment annotation: How it works: The @password: annotation is read locally by the MCP server — the password never reaches the AI model or any cloud provider Works for both login passwords and SSH key passphrases The password is split at the first : , so passwords containing : are supported When listing hosts, only passwordAuth: true is shown — the actual password is never exposed Security requirements: Your SSH config file must have 600 permissions when using @password annotations The MCP server will refuse to start if the file permissions are too open Fix with: chmod 600 /.ssh/config Include Directive Support The MCP SSH Agent fully supports SSH Include directives to organize your configuration across multiple files. However, there's an important SSH bug to be aware of: ⚠️ SSH Include Directive Bug Warning SSH has a configuration parsing bug where Include statements must be placed at the beginning of your /.ssh/config file to work correctly. If placed at the end, SSH will read them but won't properly apply the included configurations. ✅ Correct placement (at the beginning): ❌ Incorrect placement (at the end) - won't work: The MCP SSH Agent correctly processes Include directives regardless of their placement in the file, so you'll get full host discovery even if SSH itself has issues with your configuration. Example /.ssh/config Here's an example SSH configuration file that demonstrates various connection scenarios including Include directives and @password annotations for password-based authentication: This configuration demonstrates: Global settings : ServerAliveInterval to keep connections alive Custom ports : Non-standard SSH ports for security Multiple users : Different user accounts for the same host (e.g., prod and root@prod ) Multiple aliases : One host declared under several names (e.g., docker-lxc hlab ) — reachable under each Jump hosts : Using ProxyJump to access servers through bastion hosts IPv6 addresses : Modern networking support Identity files : Specific SSH keys for different servers Security options : IdentitiesOnly yes to use only specified keys Password authentication : @password: annotations for devices without SSH key support (e.g., routers, switches) or for passphrase-protected keys Which Hosts Are Discovered listKnownHosts() reports every connectable host it finds in /.ssh/config (including everything pulled in through Include ), followed by any additional hostnames from /.ssh/known hosts . Three rules decide what counts as connectable: Multi-alias blocks work under every alias. Host takes a list of patterns, not a single name, so a block can declare several aliases at once: Both docker-lxc and hlab reach this host. The response carries the full list in an aliases field, while alias holds the first one. Defaults blocks are skipped. A block whose patterns are only wildcards and negations sets defaults for other hosts — it is not something you can connect to, so it is left out of the host list: (OpenSSH lets you negate a pattern with ! . A negated match vetoes the whole line, which is why negation only makes sense as an exception to a wildcard.) Hosts without a Hostname are skipped , since there is nothing to connect to. Plain top-level directives such as a bare ServerAliveInterval 55 are configuration for ssh itself and are ignored by host discovery — ssh still applies them, because every operation runs through your system's ssh binary. How MCP SSH Agent Uses Your Configuration The MCP SSH agent automatically discovers and uses your SSH configuration: Host Discovery : Every connectable host from /.ssh/config is available — see the rules above Native SSH : Uses your system's ssh command, so all config options work Authentication : Respects your SSH agent, key files, and authentication settings Jump Hosts : Supports complex proxy chains and bastion host setups Port Forwarding : Can work with custom ports and connection options Example Usage with Claude Desktop: "List my SSH hosts" → Shows all configured hosts including prod , archive , web1.example.com , etc. "Connect to archive server" → Uses the ProxyJump configuration automatically "Run 'df -h' on web1.example.com" → Connects with the correct user, port, and key "Upload file to database server" → Uses the specific identity file and port configuration Troubleshooting Common Issues Command not found : Ensure ssh and scp are installed and in your PATH Permission denied : Check SSH key permissions and SSH agent Host not found : Verify the host exists in /.ssh/config or /.ssh/known hosts , and that its block has a Hostname — blocks without one, and pure defaults blocks such as Host , are not connectable hosts. See Which Hosts Are Discovered Connection timeout : Check network connectivity and firewall settings Windows: every command fails with exit 255 and empty output : Fixed after 1.3.8. Earlier versions inherit a stripped environment from the MCP host that omits %ProgramData% , which Win32-OpenSSH needs at startup. Upgrade, or add "ProgramData": "C:\\ProgramData" to the env block of your client configuration Debug Mode Run with debug output to see detailed operation logs: SSH Key Setup Guide For the MCP SSH Agent to work properly, you need to set up SSH key authentication. Here's a complete guide: Creating SSH Keys Generate a new SSH key pair (use Ed25519 for better security): Important : When prompted for a passphrase, leave it empty (press Enter). The MCP SSH Agent cannot handle password-protected keys as it runs non-interactively. This creates two files: /.ssh/id ed25519 (private key) - Keep this secret! /.ssh/id ed25519.pub (public key) - This gets copied to servers Installing Public Key on Remote Servers Copy your public key to the remote server's authorized keys file: Server-Side SSH Configuration To enable secure key-only authentication on your SSH servers, edit /etc/ssh/sshd config : Add or modify these settings: After editing, restart the SSH service: Setting Correct Permissions SSH is very strict about file permissions. Set them correctly: On your local machine: On the remote server: Testing SSH Key Authentication Test your connection before using with MCP SSH Agent: Multiple Keys for Different Servers You can create different keys for different servers: Then configure them in /.ssh/config : Threat Model and Trust Boundaries MCP SSH Agent gives an LLM the ability to drive ssh and scp on your behalf. Before using it, it is important to understand what an attacker who controls the LLM's instructions (for example via prompt injection through web pages, e‑mails, repository files, or another MCP server's output) can do: runRemoteCommand is full remote code execution on every host you have configured. If your /.ssh/config contains an entry for production , the LLM can run arbitrary commands as that user on that host. This is the tool's purpose, not a bug — but it means you should only configure hosts that you are willing to let the LLM touch, and prefer least-privilege accounts. uploadFile and downloadFile give the LLM access to the local filesystem with the privileges of the user running the MCP server. The LLM can read any file the process can read (including /.ssh/id , browser data, source trees, .env files) and write to any path it can write to (including /.ssh/authorized keys ). The path arguments are not sandboxed because the tool's contract is "transfer arbitrary files". The MCP server runs locally over STDIO, but the LLM is not trusted. STDIO only describes the transport — the content of tool arguments is chosen by the model, which can be steered by any untrusted text it ingests during the conversation. @password: annotations are

How do I install Ssh?

Run the install command shown above, then paste the config for your client (Claude Desktop, Claude Code, Cursor, VS Code or Windsurf) into its MCP settings and restart the client.

Is Ssh free to use?

The MCP server itself is free to install. The source is public on https://github.com/AiondaDotCom/mcp-ssh. Any third-party service it calls may require its own API key and account.

Which clients support Ssh?

Any MCP-compatible client can use it, including Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and custom agents.