Skip to main content
Glama

M8ven Score

English · Русский

dsh-ssh-mcp

Persistent SSH sessions for DeepSeek Harness, exposed as MCP tools. The agent opens one connection per host and keeps using it, instead of authenticating again for every command.

SSH automation usually fails in three places, and this plugin is built around them:

  • Re-authentication on every command. Opening a fresh ssh per command is slow and noisy. open starts one persistent session; exec reuses it, keeping the working directory and exported environment.

  • fail2ban. A retry loop against a protected host gets the address banned for hours. The plugin counts failed connection attempts per host:port and stops after one retry.

  • sudo under root. Many minimal images have no sudo at all, and for a root login it fails otherwise valid commands. The plugin detects uid 0 and refuses to use sudo in a root session.

Features

  • One persistent ssh -T session per host, with per-command exit codes and output framing.

  • Credential profiles in a JSON file: host, non-standard port, user, key file, fail2ban policy.

  • Agent-based or explicit key authentication; password authentication is deliberately unsupported (no TTY, no one to answer the prompt).

  • Root detection: is_root comes back from open, and sudo is rejected in a root session.

  • Confirmation gate for sudo and for destructive commands (rm -rf /, mkfs, dd of=/dev/..., reboot, package removal, DROP DATABASE, …).

  • Error classification with an actionable hint: auth_failed, connection_refused, network_unreachable, dns_failed, host_key_rejected, connect_halted, plus local_path_missing, path_missing, spawn_failed and transfer_timeout.

  • put / get for file transfer over scp, with local paths resolved against the workspace.

  • Server instructions carry the safety rules into the system prompt; an optional skill adds the full playbook.

Related MCP server: fast-mcp-ssh

Requirements

  • DeepSeek Harness with MCP client support (@deepseek-ai/dsh-mcp-client).

  • OpenSSH client (ssh, scp) available on PATH. Windows 10/11 ships it; Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0 enables it.

  • A remote host with a POSIX sh. Windows remotes are not supported.

  • No system Node.js install is needed: the MCP server runs on the same binary as the Harness, switched into Node mode.

Install

Plugin Manager (Desktop)

Settings → Plugins → install from a package spec, and enter:

github:extreme-russian-dsh-fandom/dsh-ssh-mcp

Command line

dsh plugin --profile <profile> add github:extreme-russian-dsh-fandom/dsh-ssh-mcp

Pin a revision when you need reproducibility:

dsh plugin --profile <profile> add github:extreme-russian-dsh-fandom/dsh-ssh-mcp#v1.1.0

github: is pnpm's GitHub shorthand, not a DSH-specific scheme: dsh plugin forwards the argument to pnpm, and the Plugin Manager checks the repository with git ls-remote before running pnpm add.

After activation the tools appear as mcp__ssh__<tool>.

Tools

Tool

What it does

mcp__ssh__profiles

Lists credential profiles with host, port, user, auth mode, fail2ban policy. Never returns secrets. Call this first.

mcp__ssh__open

Opens one persistent session. Returns session_id, is_root, OS and shell.

mcp__ssh__exec

Runs a command in the session; returns exit code, stdout and stderr. Optional sudo and confirmed.

mcp__ssh__sessions

Lists open sessions with profile, user, root status and age.

mcp__ssh__close

Closes a session and releases the connection.

mcp__ssh__put

Copies a local file or directory to the host with scp.

mcp__ssh__get

Copies a remote file or directory into the workspace with scp.

put and get resolve a relative local_path against the server's working directory (the workspace at launch), not against the remote session's working directory. The parent directory of the destination must already exist, and scp expands neither ~ nor shell variables; pass absolute paths when in doubt. Both tools overwrite an existing destination file, so check the destination path before copying.

Tool annotations

Every tool declares a human-readable title and all four MCP annotations with explicit boolean values:

Tool

readOnlyHint

destructiveHint

idempotentHint

openWorldHint

profiles

true

false

true

false

open

false

false

false

true

exec

false

true

false

true

sessions

true

false

true

false

close

false

false

true

false

put

false

true

true

true

get

false

true

true

true

exec is destructive because it runs an arbitrary command, not because every command it runs is destructive. put and get are destructive because scp overwrites the destination without a prompt. The hints let hosts warn the user before a call; the safety model still enforces confirmations on its own.

Credentials

The server reads ~/.dsh/ssh-credentials.json (override with --credentials, SSH_MCP_CREDENTIALS, or a ssh-credentials.json in the working directory). The file is created by the user; the plugin never writes it.

{
  "defaults": {
    "port": 22,
    "user": "root",
    "fail2ban": "unknown",
    "strictHostKey": "accept-new",
    "connectTimeoutMs": 15000
  },
  "hosts": {
    "prod-web": {
      "host": "203.0.113.10",
      "port": 22222,
      "user": "deploy",
      "auth": "agent",
      "fail2ban": "present",
      "description": "sshd on a non-standard port; the agent holds the key"
    },
    "prod-db": {
      "host": "db.internal.example",
      "port": 4242,
      "user": "root",
      "auth": "key",
      "identityFile": "C:\\Users\\me\\.ssh\\id_ed25519",
      "fail2ban": "present",
      "sudo": "none"
    }
  }
}

A complete example lives in examples/ssh-credentials.example.json.

Field

Values

Meaning

host

string

Address or DNS name. Required.

port

1–65535

sshd port; high ports are normal for hardened hosts.

user

string

Login user. Defaults to the defaults block.

auth

auto, agent, key

auto uses identityFile when present, otherwise the agent/default keys.

identityFile

path

Private key for auth: key.

fail2ban

unknown, present, absent

Attempt budget: 2 by default, 3 only when explicitly absent.

sudo

nopasswd, none

Whether passwordless sudo is expected on this host.

strictHostKey

accept-new, yes, no

accept-new trusts a host on first contact; yes requires known_hosts.

connectTimeoutMs

1000–120000

TCP/auth timeout for one attempt.

Keep the file private (chmod 600 on POSIX). It must never be committed; the repository .gitignore already excludes it.

Password authentication is not supported: the MCP server has no terminal, so ssh cannot answer a password prompt. Install the public key on the remote host or use an ssh-agent. A profile that declares passwordFile fails with password_auth_unsupported on purpose.

Safety model

Rule

Behaviour

fail2ban awareness

Failed connections are counted per host:port. After the budget is spent, the host is halted for the life of the process and the tool tells the agent to stop and ask the user. Purely local failures (a missing local path, a missing OpenSSH client) are not counted, because they never reach the host.

Root sessions

open reports is_root. exec with sudo: true in a root session returns sudo_not_applicable; the command must be repeated without sudo.

Confirmations

sudo and destructive commands require confirmed: true, which the agent may set only after the user explicitly agrees.

Secrets

The credentials file path is the only thing the model sees; it never receives key material or passwords.

Server instructions embed these rules in the system prompt, so they apply even without the skill.

Optional skill

The plugin ships a ready playbook at skill/remote-ssh/SKILL.md. Copy it to your skills directory for the full troubleshooting guide:

mkdir -p ~/.dsh/skills/remote-ssh
cp skill/remote-ssh/SKILL.md ~/.dsh/skills/remote-ssh/

Configuration

Variable

Purpose

DSH_SSH_MCP_SERVER

Absolute path to server/index.mjs, if the package is not under <cwd>/node_modules/dsh-ssh-mcp.

DSH_SSH_MCP_NODE

Binary used to run the server. Defaults to the running Harness binary.

DSH_SSH_MCP_TIMEOUT_MS

Per-call timeout for MCP tools. Defaults to 600000.

SSH_MCP_CREDENTIALS

Alternative credentials file path.

Troubleshooting

Symptom

Cause and fix

No mcp__ssh__* tools

The MCP server failed to start. Check that ssh.exe/ssh is on PATH and that the hostname is correct.

credential_missing

Create ~/.dsh/ssh-credentials.json; mcp__ssh__profiles returns a template.

auth_failed

The remote host does not accept the key. Add the public key to authorized_keys; the plugin allows one retry only.

connect_halted

The attempt budget for this host is spent. Fix connectivity, then restart the harness process. The hint names the failure code that consumed it.

local_path_missing, path_missing

One side of a put/get has no such path; nothing was copied and no attempt was charged. Check both paths (relative local paths resolve against the workspace).

spawn_failed

ssh or scp could not be started. Install the OpenSSH client or add it to PATH; this local failure does not consume the attempt budget.

sudo_requires_password

Passwordless sudo is not configured. Add a NOPASSWD rule or run the command manually.

host_key_rejected

The host key changed. Verify the host and update known_hosts; the plugin never weakens host key checking.

Uninstall

dsh plugin --profile <profile> remove dsh-ssh-mcp

Development

The package has no runtime or development dependencies. The suite uses --test-isolation=none, so it needs Node.js 22.8 or newer:

npm test

server/test/tools.test.mjs covers each of the seven tools, tools.metadata.test.mjs guards the annotations, rpc.test.mjs covers the JSON-RPC envelope, and index.test.mjs performs a real stdio handshake when the environment allows spawning a child process. CI runs the suite on Node.js 22 and 24.

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to securely execute commands on remote hosts via SSH and SFTP, with persistent shells, file transfers, screenshots, and an audit log.
      5
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to establish and manage persistent SSH sessions, supporting smart command execution, async tasks, multi-host, sudo, and file operations through SFTP.
      15
      65 PyPI
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables executing shell commands and transferring files on remote machines over SSH/SFTP, including persistent interactive sessions that can handle prompts such as sudo and package manager confirmations.
      -