MCP SSH Tool

You set up and use a practical MCP server that runs SSH commands on named servers. It supports per-server and per-group configurations, hot-reloading of the servers.json file, policy-based command filtering, and flexible password handling without exposing secrets in clear text.

How to use

Start the local MCP server in stdio mode to manage SSH commands across your configured servers. Use the provided tools to explore the setup, validate configurations, test connections, and run commands across one server or a group. The workflow emphasizes security and ease of use, with policies controlling which commands are allowed and hot reload keeping changes immediate.

How to install

Prerequisites you need before running the MCP server include Python 3.10 or newer and OpenSSH available in your PATH. If you plan to use password authentication, install the optional Python packages.

# Ensure Python is available (>= 3.10)
python --version

# Optional dependencies for password auth
pip install paramiko
pip install keyring

Run the MCP server in stdio mode using the configuration file that defines your servers. You can pass the config path with --config or set MCP_SSH_CONFIG to point to it.

python mcp_ssh_server.py --config servers.json

If you prefer to set the config path via an environment variable, use MCP_SSH_CONFIG.

export MCP_SSH_CONFIG=servers.json
python mcp_ssh_server.py

Configuration basics

The server configuration supports per-server policies, hot reload, and secure authentication options. You can design default settings, add servers to groups, and specify allow/deny regex patterns to govern which commands are permitted.

{
  "version": 1,
  "defaults": {
    "user": "ubuntu",
    "port": 22,
    "identityFile": "~/.ssh/id_ed25519",
    "extraArgs": ["-o", "BatchMode=yes"]
  },
  "policy": {
    "allow": ["^uptime$"],
    "deny": ["(?i)\\brm\\s+-rf\\b"]
  },
  "servers": {
    "nome-do-servidor": {
      "host": "10.0.0.10",
      "port": 22,
      "user": "ubuntu",
      "identityFile": "~/.ssh/id_ed25519",
      "policy": {
        "allow": ["^(uptime|whoami)$"],
        "deny": ["(?i)\\bshutdown\\b"]
      }
    }
  }
}

Hot reload and audit logging

The MCP automatically reloads servers.json when the file changes, so you don’t need to restart the server for every update. You can also force a reload with the dedicated tool.

Audit logging is enabled by default and records executed commands with timestamps and server details in a JSON Lines file. You can disable it or configure the file path via environment variables.

{
  "logging": {
    "enabled": true,
    "file": "~/.mcp-ssh-toolkit/audit.jsonl",
    "includeCommand": true
  }
}

Security and authentication

Use SSH key-based authentication whenever possible. If you must use passwords, options include passwordEnv to read a password from an environment variable, passwordCommand to run a command that outputs the password, and passwordKeyring to read from the OS keyring.

Be mindful that remote commands are executed by a shell on the remote host, so metacharacters can affect what runs. Prefer an allowlist with anchored patterns and consider adding a deny rule for common shell metacharacters to harden your setup.

Tools available

You can list servers, test connections, and execute commands across one server or a group. The key tools are ssh_list, ssh_info, ssh_test, ssh_exec, ssh_exec_parallel, ssh_add_server, and ssh_reload.

Available tools

ssh_list

Lists configured servers, groups, defaults, and policy to help you understand what is available in your MCP setup.

ssh_info

Shows a sanitized view of a specific server’s configuration without revealing secrets.

ssh_test

Tests the connection and authentication for a server or group to verify readiness.

ssh_exec

Executes a command on a specified server or group, honoring the defined policy.

ssh_exec_parallel

Executes a command across a group in parallel, with optional parallelism limits.

ssh_add_server

Adds or updates a server configuration and optionally assigns it to groups.

ssh_reload

Forces the MCP to reload the configuration from disk immediately.