convez.ai
MCP ServerDevOps & InfraestruturaAvançado
rmednitzer

Relay Shell

rmednitzer/relay-shell

MCP server para shell e SSH com auditoria, autorização em camadas e limites de recurso

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP para operação completa de shell local e frotas SSH com auditoria, controle de autoridade em camadas e limites de recursos. Oferece execução de comandos, sessões PTY interativas, transferência SFTP, port forwarding e inventário de hosts, tudo com trilha de auditoria imutável e políticas de segurança.

Instalação

$npx convez-ai rmednitzer/relay-shell

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 3 dias
Versão
v0.5.3
Issues abertas
1
Contribuidores
6

Casos de uso

  • Automação e operação de infraestrutura com rastreamento completo de ações
  • Execução segura de comandos remotos via SSH em frotas de servidores
  • Sessões PTY interativas persistentes para REPLs e ferramentas administrativas
  • Transferência de arquivos e port forwarding para operações DevOps
  • Governança operacional com auditoria, redação de segredos e limites de recurso

Veredito

Ferramenta madura e robusta para operadores que precisam de shell e SSH automatizados com garantias de segurança e auditoria em produção. Arquitetura sólida, bem documentada, ideal para infraestrutura administrada; não serve para sandbox ou acesso sem confiança.

README

A tradução para o português deste README ainda está na fila.

Relay Shell

Ask DeepWiki

Status: v0.1.0 · Python 3.12 / 3.13 / 3.14 · transports: stdio and streamable-http · MCP SDK mcp==1.27.1 · last validated against upstream surfaces on 2026-06-01 (ADR 0005).

A highly reliable, maximally capable Model Context Protocol server for complete shell and SSH mastery.

relay-shell gives an MCP client (Claude, or any MCP-compatible agent) a robust, auditable interface to operate a Linux host and a fleet of remote hosts over SSH: one-shot command execution, long-lived interactive PTY sessions, scripted runs, SFTP transfer, port forwarding, and host-inventory aware connectivity.

It is designed as operator infrastructure tooling for hosts you own and administer. The default operating posture is native, full access (no sandbox), matching the way real administration is performed, paired with the defensive controls a production operator actually needs: an append-only, output-hashed audit trail; a tiered-authority policy layer; secret redaction; strict resource and timeout bounds; and an optional OAuth 2.1 edge.

The architecture, security model, and deployment patterns are modeled on a mature production MCP gateway and on established operational best practices.

Why

Engineers SSH into hosts and run commands from memory, with no structured reasoning trail and no pre-execution review. A well-built MCP relay improves on that baseline: every action is captured with arguments, an output hash, an exit code, and a tier classification; limits and timeouts are enforced centrally; failure paths never crash the transport. The reasoning layer sits inside the loop and can assess blast radius before acting.

Capabilities

Local shell

ToolPurpose
shell_execRun a command. Timeout/output clamps, cwd, env overlay, stdin, exit code.
shell_scriptRun a multi-line script (bash/sh/python), optional set -euo pipefail.
shell_spawnStart a persistent PTY session (REPLs, TUIs, prompts, long jobs).

SSH

ToolPurpose
ssh_execRun a command on a remote host (jump host, key/agent, known-hosts policy).
ssh_spawnInteractive remote PTY session.
ssh_upload / ssh_downloadSFTP transfer (recursive supported).
ssh_forwardLocal (L), remote (R), or dynamic SOCKS (D) forwarding.
ssh_forward_list / ssh_forward_closeManage active forwards.
ssh_checkConnectivity probe across the inventory or a host list.
ssh_fanoutRun a command in parallel across hosts; per-host exit codes in one JSON.
ssh_keyscanFetch host public keys via ssh-keyscan (pre-populate known_hosts for strict).
ssh_hostsResolved host inventory (~/.ssh/config + inventory file).

Sessions (local PTY and SSH PTY, unified)

ToolPurpose
session_sendSend input (optionally with Enter) to a session.
session_recvRead buffered/new output, with a short wait.
session_resizeResize the PTY (cols x rows).
session_killSignal / terminate a session.
session_listList active sessions with metadata.

Diagnostics

ToolPurpose
server_infoServer version, effective limits, policy mode, audit path.
audit_tailReturn the last N audit records (read-only, Tier 0).

The HTTP transport also exposes GET /metrics (Prometheus text format): relay_shell_tool_calls_total{tool,tier,mode,outcome}, relay_shell_seccomp_notify_events_total{syscall}, and relay_shell_seccomp_notify_overflow_total (counters), plus relay_shell_active_sessions, relay_shell_active_forwards, and relay_shell_audit_degraded (gauges). See docs/deployment.md §9a.

Resources

Three MCP resources let clients read inventory and ssh_config views the protocol-native way (no tool call needed):

URImeaning
relay-shell://inventoryFlat list of all known hosts (JSON).
relay-shell://inventory/{host}One host's resolved spec (JSON).
relay-shell://ssh-configssh_config path + aliases (JSON).

Resource reads are audited (tier 0). See docs/tools.md for the full reference.

Prompts

One MCP prompt, operating_guide, carries the detailed "when to use which tool" guidance (one-shot command vs persistent PTY session, the spawn+session workflow, fleet and transfer entry points) — the protocol-native counterpart to the concise instructions string handed to clients at initialize. A fetch is audited (tier 0, prompt:operating_guide) like a resource read; listing is not (ADR 0008).

Full reference: docs/tools.md.

Quickstart

Requires Python 3.12+ (CPython, tested on Ubuntu 24.04).

git clone https://github.com/rmednitzer/relay-shell.git && cd relay-shell
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

# stdio transport (local agent / Claude Desktop / MCP Inspector)
relay-shell

# HTTP transport (streamable-http on 127.0.0.1:8080)
RELAY_SHELL_TRANSPORT=http relay-shell

# Validate config without starting the transport (useful for image bakes)
relay-shell --check-config

# Drift-detect shipped templates against /etc/... (useful in production cron)
relay-shell --verify-deploy

Register with an MCP client (stdio):

{ "mcpServers": { "relay-shell": { "command": "relay-shell" } } }

Configuration is environment-driven; see .env.example and docs/deployment.md.

Compatibility matrix

SurfaceSupportedNotes
Python3.12 / 3.13 / 3.14CI runs the full matrix; package floor is >=3.12.
Host OS (tested)Ubuntu 24.04 LTSValidation is run against this image; the systemd + Caddy installers assume it.
Host OS (dev)macOSUnsupported for production; pty/SSH paths work for local development.
Host OS (other)WindowsOut of scope — no PTY contract, no systemd integration.
Transportsstdio, streamable-httpStdio is the default. HTTP binds loopback and requires a TLS edge (see deployment.md).
SDKmcp==1.27.1Pinned (ADR 0001); bumps trigger a fresh validation pass.
SSH libraryasyncssh>=2.18 (tested at 2.23.0)Native async; no shell-out to system ssh.

Security posture

relay-shell runs unsandboxed with the privileges of its service account by design (see docs/adr/0002-no-sandbox-full-access.md): sandboxing the process would defeat the very capability it exists to provide. Safety is achieved with compensating controls, not by crippling the tool:

  • Audit - every invocation appended as one JSON line with a SHA-256 hash of the output (never the output body), byte length, exit code, request and client id, and the assessed tier. Append-only on disk; rotation-safe handler. Optional per-record hash chain (RELAY_SHELL_AUDIT_CHAIN, ADR 0007) makes edits, insertions, reorders, and interior deletions detectable with relay-shell --verify-audit, which is fail-closed (a missing / empty / head-truncated log fails; --segment accepts a rotation segment; tail-truncation needs the off-host copy).
  • Syscall visibility (optional) - RELAY_SHELL_SECCOMP_NOTIFY (ADR 0006) adds an audit-only seccomp user-notify channel that appends syscall_notify lines for a spawned child's execve / privilege / namespace / mount / write-open syscalls. It never blocks a syscall and installs only with CAP_SYS_ADMIN (never latching no_new_privs), so set-uid/sudo posture is preserved verbatim — visibility added, capability untouched.
  • Tiered authority - every call is classified Tier 0..3 (docs/adr/0003-tiered-authority.md). RELAY_SHELL_POLICY_MODE selects open (default), guarded, or readonly.
  • Redaction - audited arguments are scrubbed for tokens, keys, and Authorization material.
  • Bounds - timeout and output caps on every tool; bounded session count and buffers; idle/lifetime reaping.
  • Optional OAuth 2.1 - DCR with single-client lockdown, PKCE, file-backed rotating tokens, lazy expiry (HTTP transport).
  • Edge - parameterized Caddy config restricts the endpoint to known CIDRs with security headers and automated TLS (ACME / Let's Encrypt) installed via deploy/install-edge.sh; systemd unit applies resource caps.

This server grants real administrative power. Run it only as a scoped service account, only on hosts you are authorized to administer, behind the network controls in docs/deployment.md. See SECURITY.md for the threat model and reporting.

If your use case requires maximum model capability, relay-shell also supports an explicit privileged posture (root/sudo workflows). Use that only on isolated administrative hosts with strict network controls and full audit shipping.

Layout

src/relay_shell/   server, config, audit, policy, redaction, sessions,
                   shelltools, sshpool, inventory, errors, util, auth
deploy/            systemd unit + hardening drop-in, Caddyfile, logrotate, installers
docs/              architecture, tool reference, deployment, ADRs
tests/             unit + integration (in-process SSH server, no network)

Development

ruff check . && ruff format --check .
mypy
pytest

Contributing

See CONTRIBUTING.md for scope, branch naming, the local development loop, and how security-sensitive PRs are reviewed. docs/runbook.md is the canonical procedure for audit, review, validate, enhance, and extend tasks. Participation is governed by the Code of Conduct.

AI contributor guidance

  • AGENTS.md - repository-wide agent operating contract
  • CLAUDE.md - Claude-focused development and review guidance
  • docs/runbook.md - executable audit / review / validate / enhance / extend procedures plus the prioritized backlog

License

Apache-2.0. See LICENSE and NOTICE.

Ver o original no GitHub

Bom para

Relacionados