MCP SSH

Provides an MCP SSH server that executes commands remotely, transfers files, lists hosts, and tracks background processes with structured JSON output.

typescript

GitHub Stars

typescript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "sinjab-mcp_ssh": {
      "command": "uv",
      "args": [
        "run",
        "mcp_ssh"
      ],
      "env": {
        "MCP_SSH_CHUNK_SIZE": "YOUR_VALUE",
        "MCP_SSH_READ_TIMEOUT": "YOUR_VALUE",
        "MCP_SSH_SECURITY_MODE": "YOUR_VALUE",
        "MCP_SSH_CASE_SENSITIVE": "YOUR_VALUE",
        "MCP_SSH_COMMAND_TIMEOUT": "YOUR_VALUE",
        "MCP_SSH_CONNECT_TIMEOUT": "YOUR_VALUE",
        "MCP_SSH_MAX_OUTPUT_SIZE": "YOUR_VALUE",
        "MCP_SSH_QUICK_WAIT_TIME": "YOUR_VALUE",
        "MCP_SSH_CONNECTION_REUSE": "YOUR_VALUE",
        "MCP_SSH_TRANSFER_TIMEOUT": "YOUR_VALUE",
        "MCP_SSH_COMMAND_BLACKLIST": "YOUR_VALUE",
        "MCP_SSH_COMMAND_WHITELIST": "YOUR_VALUE",
        "MCP_SSH_CONNECTION_POOL_SIZE": "YOUR_VALUE"
      }
    }
  }
}

You have access to a production-ready MCP server with integrated SSH capabilities. It lets you run commands remotely, transfer files, inspect hosts, and manage sessions with structured, machine-friendly output. This guide shows practical steps to install, run, and use the MCP SSH server so you can automate remote tasks safely and efficiently.

How to use

You use an MCP client to connect to the MCP SSH server and perform common SSH-related tasks. Core capabilities include executing commands on remote hosts, transferring files via SCP, listing configured hosts, and getting interactive help. All operations are designed to run in the background with progress tracking and robust timeout handling, so you can build reliable automation around remote hosts.

How to install

Prerequisites you need before installation:

Python 3.11+ for development and tooling.
uv package manager for running MCP server processes.
An SSH client and a configured SSH key for remote access.

Step-by-step installation and startup flow:

# 1) Clone the MCP SSH project
git clone https://github.com/sinjab/mcp_ssh.git
cd mcp_ssh

# 2) Synchronize dependencies and build tooling
uv sync

# 3) Start the MCP SSH server in production mode
uv run mcp_ssh

# 4) Development mode with hot reload (optional)
uv run mcp dev src/mcp_ssh/server.py

Additional sections

Configuration covers how the SSH server behaves, including how commands are validated, timeouts, and performance optimizations. You can tune background execution, timeouts, connection reuse, and security rules to match your environment.

Environment variables you can set to control runtime behavior include a range of MCP_SSH_* settings. These affect output chunking, quick command waits, timeouts, connection reuse, and security filters.

Security considerations include choosing a validation mode (blacklist, whitelist, or disabled) and specifying patterns for blocked or allowed commands. This helps prevent unintended actions on remote hosts.

Troubleshooting tips cover common SSH connectivity issues, permission checks for SSH keys, and how to inspect logs for debugging. If you need more detail, you can re-run dependency synchronization and re-run tests to verify the setup.

Examples show typical workflows, including starting a long-running remote command, checking its status, and retrieving output in chunks. You can also use the MCP tool interface to perform operations programmatically.

Available tools

execute_command

Execute commands in background on remote SSH hosts with process tracking

get_command_output

Retrieve output from background commands with chunking support

get_command_status

Check status of background commands without retrieving output

kill_command

Kill running background processes with graceful termination and cleanup

transfer_file

Upload/download files via SCP with progress tracking

get_security_info

Get current security configuration and validation rules

ssh_hosts

List all configured SSH hosts with detailed info

ssh_help

Interactive guidance for SSH operations

Built by

VeilStrat

AI signals for GTM teams