Python SSH MCP

Installation

Python SSH MCP is a standard PEP 621 Python package (hatchling build backend). Use whichever installer you prefer — uv is the recommended path:

```bash uv sync # create .venv + install runtime deps + dev extras uv run ssh-mcp # start the server on stdio

Or without syncing a venv first — build + run in an ephemeral environment:

uvx --from . ssh-mcp

Plain pip also works (PEP 517):

pip install -e ".[dev]" ssh-mcp

FastMCP shortcuts (once the package is installed):

fastmcp dev inspector # dev UI: MCP Inspector + hot reload; auto-finds fastmcp.json fastmcp run # run the server; auto-finds fastmcp.json fastmcp run -t http -p 8000 # HTTP transport instead of stdio ```

Optional dependency groups:

• .[tasks] — adds the Redis client (redis>=5.0.0) for a production task backend. The FastMCP tasks runtime itself (docket, in-memory by default) is a hard dep via fastmcp[tasks] and ships regardless — install this extra only when pointing FASTMCP_DOCKET_URL at a real Redis (task-loss on restart matters in prod with ALLOW_DANGEROUS_TOOLS=true; see _warn_task_backend).
• .[telemetry] — OpenTelemetry distro + OTLP exporter.
• .[dev] — pytest, ruff, mypy.

MCP clients (Claude Desktop, Claude Code, Cursor) discover the server via fastmcp.json.

Client Setup

Every major MCP client accepts a JSON snippet that tells it how to spawn the server. The shape is standardized around an mcpServers object — only the file path differs per client. Pick your client, paste the snippet into the right file, restart the client so the subprocess is respawned.

Heads-up: fastmcp.json's deployment.env block (if you keep one in the project) overrides the client env unconditionally — keep tier flags out of that block and let them come from the client config or your .env. If the client appears to hold a stale subprocess after code changes, see Troubleshooting — most clients spawn and own the server subprocess, so a terminal-side restart is not enough.

The base snippet (used by Claude Desktop, Cursor, Windsurf, Kilocode — most clients speak this dialect):

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Nightreaver/python-ssh-mcp", "ssh-mcp"],
      "env": {
        "LOG_LEVEL": "INFO",
        "ALLOW_LOW_ACCESS_TOOLS": "false",
        "ALLOW_DANGEROUS_TOOLS": "false",
        "ALLOW_SUDO": "false"
      }
    }
  }
}

uvx --from <path> ssh-mcp builds and runs the server in an ephemeral uv-managed environment; no persistent venv needed on the client side. Alternative: replace with "command": "fastmcp", `"args": ["run", "<path-to-clone>/fastmcp.json"]` if you already have a venv with fastmcp on PATH.

Flip the ALLOW_* flags as you grant capability to the assistant. Keep read-only as the default and open the exec/sudo tiers only where you need them.

Quick Start

• Install python-ssh-mcp
• Write your first hosts.toml entry (Walkthrough §3)
• Set up your MCP Client (Claude Desktop, Claude Code, Cursor, ...)
• Ask the LLM to run ssh_host_ping against your target — verifies agent + known_hosts + pool end-to-end
• Flip the tier flags you need (ALLOW_LOW_ACCESS_TOOLS, ALLOW_DANGEROUS_TOOLS, ALLOW_SUDO) and the LLM unlocks file ops, exec, sudo — see CONFIGURATION.md → Access tiers

CONFIGURATION.md — configuring more hosts, access tiers, allowlist/blocklist, tool groups, Docker/Podman, per-host SSH identity, known_hosts management, sudo. ADVANCED.md — runbooks (FastMCP Skills), hooks, observability, testing, key rotation, architecture, contributing.

→ 256 SHA256:abc123... web01.example.com (ED25519)

Compare that `SHA256:...` against a source you trust that is not the network you just scanned over: the host's provisioner output, a console session, a terraform output, the sysadmin's Signal message. **If they don't match, stop.** A typo or MITM would pin a hostile key as trusted.

4. Write `.env`

```bash

Optional safety rail

SSH_HOSTS_BLOCKLIST= ```

VS Code (GitHub Copilot Chat / Agent Mode)

VS Code's MCP support (1.102+) uses a slightly different key. Config file:

• Per-workspace: <workspace>/.vscode/mcp.json
• Global user settings: settings.json → "mcp.servers"

Workspace .vscode/mcp.json:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Nightreaver/python-ssh-mcp", "ssh-mcp"],
      "env": {
        "LOG_LEVEL": "INFO",
        "ALLOW_LOW_ACCESS_TOOLS": "false",
        "ALLOW_DANGEROUS_TOOLS": "false",
        "ALLOW_SUDO": "false"
      }
    }
  }
}

Note the top-level key is servers (not mcpServers) and each entry carries a "type": "stdio" discriminator. Reload the VS Code window (Developer: Reload Window) to respawn.

2b. Print the fingerprint and compare OUT-OF-BAND.

ssh-keygen -lf /tmp/web01.hostkey

Troubleshooting