home / mcp / ssh mcp server

SSH MCP Server

Exposes SSH capabilities via MCP to execute remote shell commands securely on Linux and Windows hosts.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "tufantunc-ssh-mcp": {
      "command": "npx",
      "args": [
        "ssh-mcp",
        "-y",
        "--",
        "--host=1.2.3.4",
        "--port=22",
        "--user=root",
        "--password=pass",
        "--key=path/to/key",
        "--timeout=30000",
        "--maxChars=none"
      ]
    }
  }
}

SSH MCP Server exposes SSH control through a local MCP server, enabling LLMs and other MCP clients to securely execute shell commands on Linux and Windows hosts via SSH. This guide shows you how to use, install, and configure the server so you can run remote commands with confidence and controlled timeouts.

How to use

You connect your MCP-enabled client to the local SSH MCP Server and issue shell commands to remote hosts over SSH. Start with basic commands to verify connectivity, then use the available tools to run arbitrary commands or elevate privileges when needed. The server enforces timeouts and can abort long-running processes to protect your session. If you need persistent root access, consider enabling sudo or an equivalent elevation workflow. Always ensure you provide valid host, user, and authentication details before executing commands.

How to install

Prerequisites: you need Node.js and npm installed on the machine that will host the MCP server. Verify Node.js is installed by running node -v and npm by running npm -v.

Install dependencies and prepare the local MCP server files.

Clone the project repository and install dependencies.

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

Configure and run the server

Configure the MCP client to connect to this local server using the stdio transport. The server is started via a command that runs the SSH MCP package with your chosen host, port, user, and authentication details.

Example runtime configuration you can use as a starting point:

{
  "mcpServers": {
    "ssh_mcp": {
      "command": "npx",
      "args": [
        "ssh-mcp",
        "-y",
        "--",
        "--host=1.2.3.4",
        "--port=22",
        "--user=root",
        "--password=pass",
        "--key=path/to/key",
        "--timeout=30000",
        "--maxChars=none"
      ]
    }
  }
}

Additional sections

Security and timeout behavior: the server includes configurable timeout protection and will automatically abort long-running commands when a timeout occurs. It also provides graceful timeout handling by attempting to terminate hanging processes before closing the connection.

Testing

Test the MCP setup using a local MCP inspector or your client’s testing features. Validate that you can connect to the host, run a simple command like ls -la on a remote Linux host, or dir on Windows, and that the command results are returned to your client.

Disclaimer

SSH MCP Server is provided under the MIT License. Use it in accordance with license terms and security best practices.

Support

If you need help, consider sharing feedback, reporting issues, or contributing to improve the project. Community support channels are welcome.

Available tools

exec

Execute a shell command on the remote SSH server. Requires a command and can include an optional description.

sudo-exec

Execute a shell command with sudo elevation. Requires a password for sudo or can be configured with persistent root access using su. Timeout and maxChars options apply.