v1.2.0 — Plan-and-approve SSH for MCP

SSH into anything. Safely, from your AI.

adremote-mcp is an MCP server that gives Claude and other AI clients safe, audited SSH access to remote servers — with a plan-and-approve flow, credential management, file transfers, and a human-readable audit log.

Star on GitHub How to install

How this works

Connect once. Safe commands run instantly. Anything risky goes through a plan you review and approve before it touches your server.

claude — ssh-remote mcp
# Connect to a remote server
user: ssh 192.168.1.100:22 ubuntu mypass
Connected: ubuntu@192.168.1.100 — credential saved as "ubuntu-home"
# Safe commands run directly
user: run ls /home on the server
ubuntu backup logs
# Risky commands go through plan-and-approve
user: run systemctl restart nginx
Plan ID : plan-3a9f12c04e81
Kind : command
Risk : high — approve before execution
user: approve plan-3a9f12c04e81
Approved. Execute with ssh_execute_plan.
20+
MCP Tools
Exposed
24h
Plan TTL
with Audit Log
SFTP
File Upload
& Download
0
Unreviewed
Destructive Runs

Get started in seconds

Pick your OS — the command appears below.

Safe by design, not by convention

Every non-trivial command goes through a structured review gate. Your AI proposes, you approve, the server executes — with a full audit trail.

WITHOUT — Unguarded AI Shell Access
  • AI runs commands directly with no review gate.
  • No audit trail — impossible to know what ran and when.
  • Credentials stored insecurely or re-entered every session.
  • File edits overwrite with no backup and no hash check.
  • One hallucinated command can break production. There is no rollback.
WITH adremote-mcp
  • Safe commands (ls, pwd, whoami) run directly. Everything else needs a plan.
  • Every plan shows full details — risk level, rollback plan, and payload — before you approve.
  • Credentials saved locally with key-based auth — no passwords re-entered.
  • File edits create a timestamped backup and verify SHA256 after writing.
  • Human-readable audit log via ssh_read_audit_log.

Your AI proposes. You approve. The server executes. Always.

Tool Groups

20+ MCP tools organized across five capability areas.

Connection

  • ssh_connect
  • ssh_connect_saved
  • ssh_disconnect
  • ssh_list_connections
  • ssh_health_check

Plan & Approve

  • ssh_execute
  • ssh_plan_command
  • ssh_approve_plan
  • ssh_reject_plan
  • ssh_execute_plan
  • ssh_list_plans
  • ssh_get_plan

File Management

  • ssh_read_file
  • ssh_plan_edit
  • ssh_upload_file
  • ssh_download_file

Credentials

  • ssh_save_credentials
  • ssh_list_saved_credentials
  • ssh_delete_saved_credentials
  • ssh_setup_key_auth

Audit Log

  • ssh_read_audit_log

Supports limit and event_filter params. Events: created, approved, rejected, executed, expired.

Common questions

A small allowlist of read-only commands: date, hostname, id, ls, pwd, uname, uptime, whoami. Everything else — including shell composition, pipes, and high-risk prefixes like rm, systemctl, curl — is routed through a plan.
Plans expire after 24 hours. An expired plan is automatically marked as rejected and cannot be executed. You would need to recreate it. Plans are persisted locally so they survive MCP server restarts within that window.
Credentials are saved locally in ~/.ssh_mcp_credentials.json with 0600 permissions. The first password-based login automatically bootstraps key-based auth and saves the key credential — the password is never stored. Passphrase-protected private keys are also supported and stored alongside the credential.
Yes. Pass a jump_host object on ssh_connect or ssh_save_credentials. The server opens a native SSH tunnel through the bastion to the target. Jump host keys can also be passphrase-protected.
Use ssh_read_file to read the current content, then ssh_plan_edit to stage the new content. After approval and execution, the server creates a timestamped .ssh-mcp.bak.<ts> backup and verifies the written file's SHA256 hash before reporting success.
Any MCP-compatible client — Claude Desktop, Claude Code, and Codex are all supported. The server communicates over stdio and is launched as a subprocess by the client. Windows and WSL/Linux are both supported with OS-specific venvs and launcher scripts.
Every plan lifecycle event: created, approved, rejected, executed, and expired. Each entry includes timestamp, plan ID, kind, connection name, risk level, and a summary. Use ssh_read_audit_log to view it in a formatted, human-readable layout — no need to read raw JSONL.

One command to install.

The installer clones the repo, creates a venv, installs dependencies, and prints the exact config to paste into your MCP client.

WINDOWS — PowerShell
irm https://raw.githubusercontent.com/nqmn/adremote-mcp/main/install.ps1 | iex

Installs to %USERPROFILE%\adremote-mcp

WSL / LINUX — bash
curl -fsSL https://raw.githubusercontent.com/nqmn/adremote-mcp/main/install.sh | bash

Installs to ~/adremote-mcp

Already cloned? Run .\install.ps1 or ./install.sh from inside the repo — the installer detects it and installs in place.

Full Documentation