MCP SSH Orchestrator

Zero-Trust SSH Orchestration for AI Assistants. Enforce declarative policy-as-code and audited access for Claude Desktop, Cursor, and any MCP-aware client.

Launch in minutes with Docker + MCP tooling, deny-by-default controls, and hardened SSH key management.

What Problem Does This Solve?

Imagine this: Your AI assistant (Claude, ChatGPT, etc.) can access your servers, but you’re terrified of what it might do. rm -rf /? Delete your databases? Change firewall rules?

Now imagine this: Your AI has governed, auditable access to your infrastructure. It can check logs, restart services, and manage your fleet, but only if your security policies allow it.

That’s exactly what MCP SSH Orchestrator provides: the power of AI-driven server management with deny-by-default access control, IP allowlists, host key verification, and comprehensive audit logging backed by declarative YAML policy-as-code (config/servers.yml, config/credentials.yml, config/policy.yml).

What is MCP?

MCP (Model Context Protocol) is a protocol that enables AI assistants to securely interact with external systems and data sources. MCP SSH Orchestrator implements this protocol to provide secure, policy-governed SSH access for AI assistants.

Features

Zero-Trust Security Model

Deny-by-default: Nothing runs unless explicitly allowed
Network controls: IP allowlists prevent lateral movement
Command whitelisting: Only approved commands can execute
Declarative policy-as-code: Versioned YAML files define hosts, credentials, and allowed commands
Comprehensive audit trails: Every action is logged in JSON

Prevents Common Attack Vectors

Dangerous commands blocked: rm -rf, dd, file deletions
Network isolation: Servers can’t access external internet
No privilege escalation: Runs as non-root in containers
Resource limits: CPU and memory caps prevent DOS

Production-Ready Audit & Security

OWASP LLM Top 10 protected: Mitigates LLM07 (Insecure Plugin Design), LLM08 (Excessive Agency), LLM01 (Prompt Injection)
MITRE ATT&CK aligned: Prevents T1071 (Application Layer Protocol), T1659 (Content Injection)
Structured JSON audit logs: Complete audit trail with timestamps, hashes, and IPs
Forensics ready: Command hashing, IP tracking, detailed metadata
Real-time monitoring: Progress logs for long-running tasks

Use Cases

Homelab Enthusiasts

Automate routine server maintenance with AI
Safely manage Proxmox, TrueNAS, Docker hosts
Get help troubleshooting without losing SSH security

Security Engineers

Audit and control AI access to infrastructure
Implement zero-trust principles with declarative policy-as-code configs
Meet compliance requirements with structured logging

DevOps Teams

Let AI handle routine tasks: log checks, service restarts, updates
Manage fleets of servers through conversational interface
Reduce manual toil while maintaining security standards

Platform Engineers

Enable AI-powered infrastructure management
Provide secure self-service access to developers
Bridge the gap between AI and infrastructure securely

Getting Started

1. Prepare local configuration (one-time)

# Optional: bootstrap everything with the compose helper script
./compose/setup.sh enduser

# Or download it separately
curl -fsSLO https://raw.githubusercontent.com/samerfarida/mcp-ssh-orchestrator/main/compose/setup.sh
chmod +x setup.sh
./setup.sh enduser

If you prefer to lay things out manually:

# Pull the latest release
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:latest

# Create directories for config, keys, and secrets
mkdir -p ~/mcp-ssh/{config,keys,secrets}

# Copy example configs to get started quickly
cp examples/example-servers.yml ~/mcp-ssh/config/servers.yml
cp examples/example-credentials.yml ~/mcp-ssh/config/credentials.yml
cp examples/example-policy.yml ~/mcp-ssh/config/policy.yml

# Add your SSH key (replace with your private key file)
cp ~/.ssh/id_ed25519 ~/mcp-ssh/keys/
chmod 0400 ~/mcp-ssh/keys/id_ed25519

2. Launch the orchestrator container

docker run -d --name mcp-ssh-orchestrator \
  -v ~/mcp-ssh/config:/app/config:ro \
  -v ~/mcp-ssh/keys:/app/keys:ro \
  -v ~/mcp-ssh/secrets:/app/secrets:ro \
  ghcr.io/samerfarida/mcp-ssh-orchestrator:latest

3. Connect your MCP client

Cursor: Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-ssh-orchestrator": {
      "command": "docker",
      "args": ["start", "-a", "mcp-ssh-orchestrator"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}

Claude Desktop (macOS): Update ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ssh-orchestrator": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USERNAME/mcp-ssh/config:/app/config:ro",
        "-v", "/Users/YOUR_USERNAME/mcp-ssh/keys:/app/keys:ro",
        "-v", "/Users/YOUR_USERNAME/mcp-ssh/secrets:/app/secrets:ro",
        "ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
      ]
    }
  }
}

Key Differentiators

Production-Ready Security: OpenSSF Scorecard 7.5+ score
Zero-Trust Architecture: Deny-by-default, allow-by-exception
OWASP LLM Top 10 Protected: Mitigates insecure plugin design, excessive agency, prompt injection
MITRE ATT&CK Aligned: Prevents content injection and unauthorized protocol usage
Security-Focused: Built on security-first principles against real CVEs (CVE-2025-49596, CVE-2025-6514)
Easy Integration: Works with Claude, ChatGPT, and any MCP client
Open Source: Apache 2.0 licensed, community-driven

MCP Tools Available

Your AI assistant gets 13 powerful tools with built-in security:

Discovery & Planning

ssh_list_hosts - See all available servers
ssh_describe_host - Get host details and tags
ssh_plan - Test commands before running (dry-run mode)

Execution

ssh_run - Execute single command on one server
ssh_run_on_tag - Run command on multiple servers (e.g., all “web” servers)
ssh_run_async - Start long-running tasks in background

Monitoring & Control

ssh_get_task_status - Check progress of async tasks
ssh_get_task_output - Stream output in real-time
ssh_get_task_result - Get final result when done
ssh_cancel - Stop a running synchronous task safely
ssh_cancel_async_task - Stop a running async task safely

Management

ssh_reload_config - Update hosts/credentials without restart
ssh_ping - Verify connectivity to a host

Documentation

License

Apache 2.0 - See LICENSE for details.