io.github.danielecr/realssh-mcp
MCP server for SSH remote command execution
Open source Open in the app JSON README (API)
About
MCP server for SSH remote command execution
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- danielecr
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.6
- Last push
- 2026-04-24T12:33:32Z
- Repository state
- ativo
- Language
- JavaScript
- Added
- 2026-08-29 03:02:40
- Updated
- 2026-08-29 03:02:40
- Origin id
io.github.danielecr/realssh-mcp
README
# SSH Real MCP Server
A Model Context Protocol (MCP) server that enables SSH remote command execution by delegating entirely to the **system `ssh` binary**. This means `ssh-agent`, `ProxyCommand`, `~/.ssh/config`, jump hosts, and every other OS-level SSH feature work out of the box — no Node.js crypto, no native addons.
## How it works
Instead of implementing the SSH protocol in Node.js, this server spawns `ssh` as a child process and pipes the output back to the MCP client. Authentication, key discovery, and connection routing are handled by your OS, exactly as if you ran `ssh` yourself in a terminal.
**Requirements:** `ssh` must be installed and available in `PATH` (standard on macOS and Linux).
## Features
- **Zero auth config** — uses your existing `ssh-agent`, `~/.ssh/config`, and key files automatically
- **ProxyCommand / jump hosts** — works natively, no special parameters needed
- **Connectivity test** — `ssh_test` tool to verify reachability before running commands
- **Argument injection protection** — host and username are validated before being passed to `ssh`
- **Configurable timeout** — commands are killed and an error is returned if they exceed the timeout
- Detailed results: stdout, stderr, and exit code
## Installation
### From npm
```bash
npm install -g @danielecr/realssh-mcp
```
### From source
```bash
git clone https://github.com/danielecr/realssh-mcp.git
cd realssh-mcp
npm install
npm run build
```
## VS Code / Copilot configuration
After installing the package globally, add the server to your MCP configuration. In VS Code, open the MCP config file via **Command Palette → MCP: Open User Configuration** and add:
```json
{
"servers": {
"realssh": {
"type": "stdio",
"command": "realssh-mcp"
}
}
}
```
Then run **MCP: List Servers** to verify the server is active.
## Tools
### `ssh_execute`
Execute a command on a remote server via SSH.
**Parameters:**
- `host` (string, **required**): SSH server hostname or IP address
- `command` (string, **required**): Command to execute on the remote server
- `username` (string, optional): SSH username. Defaults to the current OS user
- `port` (number, optional): SSH server port (default: 22)
- `timeout` (number, optional): Command timeout in milliseconds (default: 30000)
- `agentForward` (boolean, optional): Enable SSH agent forwarding `-A` (default: false)
- `extraArgs` (string[], optional): Extra SSH arguments (e.g., `["-o", "StrictHostKeyChecking=no"]`)
**Example:**
```json
{
"host": "prod-web-01",
"command": "df -h"
}
```
```json
{
"host": "192.168.1.100",
"username": "deploy",
"command": "systemctl status nginx"
}
```
### `ssh_test`
Test SSH connectivity to a remote host (runs `echo ok` and checks the response).
**Parameters:**
- `host` (string, **required**): SSH server hostname or IP address
- `username` (string, optional): SSH username
- `port` (number, optional): SSH server port (default: 22)
- `extraArgs` (string[], optional): Extra SSH arguments
## Host configuration
Hosts, aliases, jump hosts, and identity files are configured in `~/.ssh/config` — not in the MCP server. This is intentional: the OS `ssh` binary reads that file natively.
Example `~/.ssh/config`:
```sshconfig
Host prod
HostName prod.example.com
User deploy
ProxyJump bastion
Host bastion
HostName bastion.example.com
User admin
IdentityFile ~/.ssh/bastion_ed25519
```
With the above config, `"host": "prod"` works with no extra parameters.
## Security considerations
- Commands are executed on remote systems with the privileges of the SSH user — ensure proper access controls on the remote side.
- `BatchMode=yes` is set by default, preventing the `ssh` process from hanging on interactive prompts.
- Host and username inputs are validated to prevent SSH option injection.
- Command output may contain sensitive data; treat it accordingly.
## License
MIT