MCP SSH Server

Lets your AI assistant run commands on remote servers over SSH.

Instead of manually SSH-ing into your servers, you can just ask your AI things like "check the GPU usage on my server" or "upload this file to my cloud machine" — and it handles the connection for you, securely.

Built on the Model Context Protocol (MCP), so it works with any MCP-compatible client (Claude Code, Cursor, Windsurf, etc.).

What does this do?

This tool gives your AI assistant the ability to:

• Run commands on your remote servers (e.g. nvidia-smi, df -h, ls)
• Upload and download files between your computer and a remote server
• Monitor server health and connection status

All of this happens through a secure SSH connection, and you control exactly which servers the AI can access.

Prerequisites

Before you start, make sure you have:

• Python 3.10 or newer — Download here if you don't have it. To check, open a terminal and type python --version.
• An SSH key — This is how your computer proves its identity to a remote server without a password. If you've never set one up, see Creating an SSH key below.
• A remote server to connect to — This could be a cloud GPU (RunPod, Vast.ai, Lambda), a VPS (DigitalOcean, Linode), or any machine you can SSH into.

Quick Start

1. Install

Open a terminal and run:

cd mcp-ssh-server
pip install -e .

What does -e mean? It installs in "editable" mode — if you update the code later, you don't need to reinstall.

2. Configure your servers

Copy the example config file and rename it:

cp hosts.example.json hosts.json

Open hosts.json in any text editor and replace the example values with your real server details:

{
  "hosts": [
    {
      "name": "my-server",
      "hostname": "192.168.1.100",
      "username": "root",
      "identity_file": "~/.ssh/id_ed25519"
    }
  ]
}

Here's what each field means:

Field	What to put here
name	A short nickname for the server (you'll use this in prompts)
hostname	The server's IP address or domain name
username	The username you SSH in as (often root for cloud GPUs)
identity_file	Path to your SSH private key (usually ~/.ssh/id_ed25519 or ~/.ssh/id_rsa)

Where is my SSH key? On Mac/Linux, check ~/.ssh/. On Windows, check C:\Users\YourName\.ssh\. You're looking for a file like id_ed25519 or id_rsa (the one without .pub).

Security tip: If your config contains passwords instead of keys, restrict who can read the file: chmod 600 hosts.json

3. Add to your AI tool

This step tells your AI assistant where to find the SSH server. Where you add it depends on which tool you use:

For Claude Code — create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "ssh": {
      "command": "python",
      "args": ["-m", "mcp_ssh", "--config", "/full/path/to/hosts.json"]
    }
  }
}

For Cursor — go to Settings > MCP Servers and add a new server with the same command and args.

For other MCP clients — consult your client's docs for where to register MCP servers. The command is always python -m mcp_ssh --config /full/path/to/hosts.json.

Important: Use the full (absolute) path to your hosts.json. Relative paths like ./hosts.json may not work because the AI tool might launch the server from a different directory.

4. Start using it

Restart your AI tool to pick up the new server. Then just ask it things in plain language:

• "List my SSH hosts"
• "Run nvidia-smi on my-server"
• "Upload train.py to my-server at /workspace/train.py"
• "Check the disk space on my-server"
• "Download /workspace/results.csv from my-server"

The AI will handle connecting, running the command, and showing you the results.

Using with Cloud GPU Providers

If you're using a cloud GPU service like RunPod, Vast.ai, or Lambda, keep these things in mind:

IP addresses change. Most cloud GPU providers assign a new IP address every time you start or restart your machine. When that happens, update the hostname in your hosts.json with the new IP.

Ports may not be 22. Some providers use a non-standard SSH port (e.g. 22100, 2222). Check your provider's dashboard for the correct port and set it in your config:

{
  "name": "gpu-box",
  "hostname": "203.0.113.50",
  "port": 22100,
  "username": "root",
  "identity_file": "~/.ssh/id_ed25519",
  "auto_accept_host_key": true
}

Host key verification. Normally, SSH remembers a server's identity so it can warn you if something changes (which could mean someone is intercepting your connection). But cloud instances get a new identity every time they restart, which would cause connection failures. Setting auto_accept_host_key to true skips this check — this is expected and safe for ephemeral cloud instances, but should be false for permanent servers.

Available Tools

These are the actions your AI assistant can perform:

Tool	What it does
list_hosts	Shows all your configured servers and whether they're connected
ssh_execute	Runs a single command on a server
ssh_execute_batch	Runs multiple commands in sequence (stops if one fails)
ssh_upload	Sends a file from your computer to a server
ssh_download	Gets a file from a server to your computer (cleans up if the transfer fails)
ssh_status	Checks if a server is reachable (connects if needed)
ssh_disconnect	Closes the connection to a server

Configuration Reference

Host Options

Field	Type	Default	Description
name	string	required	Nickname for the server
hostname	string	required	IP address or domain name
username	string	required	SSH username
port	int	22	SSH port number
identity_file	string	null	Path to your SSH private key
password	string	null	SSH password (less secure than a key)
auto_accept_host_key	bool	false	Skip host key verification (only for cloud instances with changing IPs)
command_timeout	int	30	Seconds to wait for output before timing out
transfer_timeout	int	120	Seconds to wait during file transfers before timing out
allowed_commands	list	null	Only allow these specific commands (see Security)

How timeouts work: These are inactivity timeouts — they trigger if the server stops sending data for that many seconds. A long-running command that continuously produces output will not time out.

Server Options

Field	Type	Default	Description
log_level	string	"INFO"	How much detail to log: DEBUG, INFO, WARNING, ERROR, or CRITICAL
audit_log_file	string	null	File path to record all actions (grows over time — set up log rotation if needed)

Security Model

This server is designed to give your AI assistant controlled access to your servers, not unlimited access.

1. Only servers you configure — the AI cannot connect to any server that isn't in your hosts.json
2. SSH key auth by default — passwords are supported but keys are more secure
3. Host key verification — by default, connections are rejected if the server isn't in your known_hosts file (prevents man-in-the-middle attacks)
4. Command restrictions — you can optionally limit which commands the AI can run per server using allowed_commands
5. Shell injection protection — for servers with allowed_commands, dangerous characters (;, &, |, `, $, quotes, etc.) are blocked to prevent the AI from chaining commands. Note: commands that accept subcommands (like docker, kubectl, or systemctl) can still execute arbitrary code through their own mechanisms — the allowlist only checks the first word
6. Audit trail — every action is logged with timestamps
7. No credential leakage — passwords and keys are never shown to the AI
8. Failed transfer cleanup — if a download fails partway through, the partial file is automatically deleted

Creating an SSH Key

If you don't have an SSH key yet, here's how to create one:

Mac/Linux:

ssh-keygen -t ed25519

Windows (PowerShell):

ssh-keygen -t ed25519

Press Enter to accept the default file location. You can optionally set a passphrase for extra security.

This creates two files:

• ~/.ssh/id_ed25519 — your private key (keep this secret, this goes in identity_file)
• ~/.ssh/id_ed25519.pub — your public key (this goes on the remote server)

To add the public key to your server, copy the contents of id_ed25519.pub and add it to ~/.ssh/authorized_keys on the server. Most cloud GPU providers have a dashboard where you can paste your public key instead.

Architecture

Your AI Tool  <--STDIO-->  MCP SSH Server  <--SSH-->  Your Remote Servers
                                |
                          hosts.json (server list)

Built on:

• FastMCP — Python MCP framework
• Paramiko — SSH library for Python

<!-- mcp-name: io.github.Fabber-bot/ssh -->

Troubleshooting

"Config file not found" — Make sure you're using the full path to hosts.json in your MCP settings, not a relative path.

"Host key verification failed" — The server isn't in your known_hosts file. Either SSH into the server manually once first (ssh user@hostname) to add it, or set auto_accept_host_key: true in your config (only for cloud instances).

"Identity file not found" — Double-check the identity_file path in your config. On Windows, use forward slashes: C:/Users/YourName/.ssh/id_ed25519.

"Connection refused" — The server might be down, the IP might have changed (common with cloud GPUs), or the port might be wrong. Check your provider's dashboard.

AI says the tool isn't available — Restart your AI tool after adding the MCP config. Some tools need a full restart to detect new MCP servers.