shellguard

ShellGuard is an MCP server that exposes controlled, observation-focused bash access to remote hosts over SSH via an LLM. It provides six tools to the agent: connect to establish an SSH session, execute validated shell commands on the remote host, disconnect to close SSH sessions, sleep to pause between diagnostic checks, provision to deploy common diagnostics on the host (rg, jq, yq), and download_file to fetch files over SFTP with a 50 MB limit. Tools like provision, download_file, and sleep can be disabled through the config option disabled_tools or the environment variable SHELLGUARD_DISABLED_TOOLS. The server enforces a curated allowlist of commands and escapes or rejects potentially dangerous constructs to minimize risk, while still enabling useful diagnostics through a guided, non-destructive workflow. The connection flow mirrors manual use: the LLM connects, runs commands, and reads output to iteratively diagnose issues with the remote system, without context-switch overhead.

Prerequisites:

• A macOS or Linux system with a compatible shell environment
• Go (optional, for building from source)
• Access to install dependencies (brew on macOS, apt/yum on Linux)

Installation options:

1. Install via Homebrew (macOS):

brew install fawdyinc/tap/shellguard

2. Install the latest binary directly:

curl -fsSL https://raw.githubusercontent.com/fawdyinc/shellguard/main/install.sh | sh

3. Build from source (Go):

# Requires Go toolchain
go install github.com/fawdyinc/shellguard/cmd/shellguard@latest

Once installed, the ShellGuard binary provides a stdio MCP server that can be connected by MCP clients using the configuration below.

Notes and tips:

• ShellGuard exposes a fixed set of tools; you can disable some tools via config (disabled_tools) or the environment variable SHELLGUARD_DISABLED_TOOLS to minimize surface area.
• The Tools are designed for diagnostic workflows: avoid destructive operations. The system returns actionable suggestions when attempting restricted commands.
• To run locally, ensure the shellguard executable is in your PATH so MCP clients can invoke command "shellguard".
• If you need two SSH modes, you can configure ShellGuard to use native or system SSH; see the SSH configuration section in the README for details on mode selection and environment variable usage (SHELLGUARD_SSH_MODE).
• If you encounter host key warnings during first connection, work within the host verification settings described in the SSH configuration to manage known_hosts behavior.
• This MCP server is intended to be embedded in MCP ecosystems (Cursor, Claude Desktop, Claude Code, OpenCode, VS Code, Zed, Roo Code). Each integration expects the server name to be registered as shown in the Quick Start examples.