mcp-ssh

The MCP SSH Agent exposes a set of MCP tools that let you manage SSH hosts and run remote commands through Claude Desktop or any MCP-compatible client. It automatically discovers hosts from your local SSH configuration (~/.ssh/config) and known_hosts, enabling reliable, native SSH and SCP operations without implementing SSH logic in the app. You can list known hosts, run commands on remote machines, upload/download files, and batch multiple commands in sequence. Use it to manage your SSH workflow through natural language requests or scripted MCP messages.

To start, run the server via npx (recommended) or your preferred installation method. Once running, an MCP client can invoke functions like listKnownHosts, runRemoteCommand, getHostInfo, checkConnectivity, uploadFile, downloadFile, and runCommandBatch to perform common SSH tasks. The agent streams clean JSON over STDIO, so integrations can parse responses and errors consistently.

Prerequisites:

• Node.js 18 or higher
• npm or yarn
• Access to a system with SSH client (ssh, scp) installed
• SSH configuration files (~/.ssh/config and ~/.ssh/known_hosts) configured

Step-by-step installation:

1. Quick start with npx (recommended):

npx @aiondadotcom/mcp-ssh

2. Global installation (optional):

npm install -g @aiondadotcom/mcp-ssh
mcp-ssh

3. Local development workflow:

git clone https://github.com/aiondadotcom/mcp-ssh.git
cd mcp-ssh
npm install
npm start

4. Desktop integration (Claude Desktop):

• Install via the provided .dxt extension or configure Claude Desktop to point to the MCP server using the npx command shown above in your Claude Desktop config.
• Example Claude config snippet is provided in the README under "Claude Desktop Integration".

• The server relies on native ssh/scp commands for reliability; ensure these tools are available in your environment.
• The agent reads SSH hosts from ~/.ssh/config and ~/.ssh/known_hosts. It supports Include directives and warns about the SSH Include directive bug to place Include statements at the beginning of the config.
• Environment variable MCP_SILENT can be used to suppress debug output when running as an MCP server; by default, the server will emit standard debugging information.
• If you encounter connectivity issues, verify your SSH keys and agent availability (SSH_AUTH_SOCK) and that Host entries in your config are reachable from the running environment.
• For troubleshooting, enable development mode (npm start) to get verbose logs and stack traces.