MCP Ssh Orchestrator

🚀 MCP SSH Orchestrator

MCP SSH Orchestrator provides zero - trust SSH orchestration for AI assistants, enabling governed and auditable access to infrastructure with deny - by - default access control and comprehensive security features.

🚀 Quick Start

1. Prepare local configuration (one - time)

# Optional: bootstrap everything with the compose helper script
# (runs from the repo root or from your target config directory)
./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, follow the steps below.

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

# 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

# (Optional) Pin trusted hosts and prepare secret files
cp ~/.ssh/known_hosts ~/mcp-ssh/keys/known_hosts
cat > ~/mcp-ssh/secrets/prod_db_password.txt <<'EOF'
CHANGE-ME
EOF

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:0.3.3

Restart later with docker start mcp-ssh-orchestrator. Prefer disposable containers? Use docker run -i --rm ... instead.

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:0.3.3"
            ]
        }
    }
}

(Windows path: %APPDATA%\\Claude\\claude_desktop_config.json.) More examples (Docker Desktop, multi - environment, SDK usage) live in the Integrations guide.

4. Test the connection

# List configured hosts through the MCP server
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_list_hosts","arguments":{}},"id":1}' | \
  docker run -i --rm \
    -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:0.3.3

Cursor/Claude should now show the orchestrator as connected. Jump to the Usage Cookbook for guided scenarios.

✨ 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
• 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

📦 Installation

The installation steps are included in the Quick Start section.

💻 Usage Examples

Basic Usage

Refer to the Quick Start section for basic usage examples, including setting up the configuration, launching the container, connecting the MCP client, and testing the connection.

Advanced Usage

For more advanced usage scenarios, such as using Docker Desktop, multi - environment setups, and SDK usage, please refer to the Integrations guide.

📚 Documentation

🔧 Technical Details

Defense - in - Depth Architecture

Layer 1: Transport Security    → stdio, container isolation
Layer 2: Network Security      → IP allowlists, host key verification  
Layer 3: Policy Security        → Deny - by - default, pattern matching
Layer 4: Application Security  → Non - root execution, resource limits

What Gets Blocked

# Dangerous commands automatically denied
deny_substrings:
  # Destructive operations
  - "rm -rf /"
  - ":(){ :|:& };:"
  - "mkfs "
  - "dd if=/dev/zero"
  - "shutdown -h"
  - "reboot"
  - "userdel "
  - "passwd "
  # Lateral movement / egress tools
  - "ssh "
  - "scp "
  - "rsync -e ssh"
  - "curl "
  - "wget "
  - "nc "
  - "nmap "
  - "telnet "
  - "kubectl "
  - "aws "
  - "gcloud "
  - "az "

# Network isolation enforced
network:
  allow: ["10.0.0.0/8"]  # Only private IPs
  deny: ["0.0.0.0/0"]     # No public internet access

What Gets Allowed (Examples)

# Safe, read - only commands
rules:
  - action: "allow"
    aliases:
      - "*"
    tags:
      - "observability"
    commands:
      - "uptime*"
      - "df -h*"
      - "free -m*"

  # Log inspection (safe)
  - action: "allow"
    aliases:
      - "*"
    tags:
      - "observability"
    commands:
      - "tail -n 200 /var/log/*"
      - "grep -n * /var/log/*"
      - "journalctl --no - pager -n 100 *"

  # Service management (controlled)
  - action: "allow"
    aliases:
      - "web-*"
      - "db-*"
    tags:
      - "production"
      - "critical - service"
    commands:
      - "systemctl restart nginx"
      - "systemctl status nginx"
      - "systemctl status postgresql"

Protection Against Real Threats

MCP SSH Orchestrator directly addresses documented vulnerabilities in the MCP ecosystem:

• CVE - 2025 - 49596: Localhost - exposed MCP services → Mitigated with stdio - only transport
• CVE - 2025 - 6514: Command injection in MCP servers → Mitigated with policy - based validation
• 43% of MCP servers have command injection flaws → Zero - trust security model Full Security Model Documentation | Security Risks Analysis

📄 License

Apache 2.0 - See LICENSE for details.

Who Is This For?

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 policy - as - code
• 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

Real - World Use Cases

Scenario 1: Homelab Automation

You say: "Claude, my home server is running slow. Can you check the disk usage on my Proxmox host?" What happens:

• Policy checks: Only df -h allowed on that host
• Network check: Proxmox IP is in allowlist
• Command executes safely
• Audit log records the operation

Scenario 2: Incident Response

You say: "Check nginx logs for errors across all web servers" What happens:

• Tag - based execution runs tail -f /var/log/nginx/error.log on all web servers
• Network - isolated execution (no external access)
• Real - time progress logs show you what's happening
• Complete audit trail for post - incident review

Scenario 3: Compliance & Auditing

Your security team needs to know: "Who accessed what and when?" What happens:

• JSON audit logs capture every action with timestamps
• Command hashing preserves privacy while enabling forensics
• IP addresses logged for network compliance
• Easy to parse with jq for reporting

What Can AI Do With This? (MCP Tools)

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 task safely

Management

• ssh_reload_config - Update hosts/credentials without restart
• ssh_ping - Verify connectivity to a host Complete Tools Reference with Examples

Learn More

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

What Users Are Saying

"Finally, I can let Claude manage my Proxmox cluster without fear!" - Homelab Admin "This is what infrastructure - as - code should have been. Declarative security for AI access." - Platform Engineer "The structured audit logs make incident response so much easier." - Security Engineer

Contributing

We welcome contributions! See our Contributing Guide for:

• Development setup
• Code of conduct
• How to submit PRs
• Architecture decisions

Links

• GitHub Repository - Star us on GitHub!
• Issue Tracker - Report bugs or request features
• MCP Specification - Learn about MCP
• Docker MCP Security Guide - Security best practices