A secure SSH fleet orchestrator built as a Model Context Protocol (MCP) server

Execute commands across your server fleet with declarative policy-as-code controls, network filtering, and comprehensive audit logging.

MCP SSH Orchestrator is a secure, policy-driven SSH command executor designed specifically for AI agents. It implements the Model Context Protocol (MCP) to provide safe, auditable access to your server infrastructure and treats servers.yml, credentials.yml, and policy.yml as first-class declarative policy-as-code artifacts.

• Policy-Based Access Control: Fine-grained command allow/deny rules with glob pattern matching
• Declarative Policy-as-Code: Version-controlled YAML governs hosts, credentials, and execution policy
• Network Security: IP allowlists/blocklists with CIDR support and DNS resolution verification
• Credential Management: Support for SSH keys and passwords via Docker secrets or environment variables
• Fleet Management: Tag-based host grouping for bulk operations
• Real-Time Streaming: Live command output with progress tracking
• Cancellation Support: Cancel long-running commands mid-execution
• Audit Logging: JSON audit trail to stderr for all operations
• Docker-Ready: Runs in containers with non-root user and health checks

AI agents need safe, controlled access to infrastructure. Traditional approaches like "run arbitrary shell commands" introduce significant security risks:

• 43% of analyzed MCP servers have command injection flaws
• Prompt injection can change agent behavior without code releases
• Unrestricted access leads to lateral movement and data exfiltration

This project implements Docker's MCP security best practices to provide:

• Containerized execution with resource limits
• Policy-enforcing gateway between agents and tools
• Comprehensive audit trails for compliance
• Defense-in-depth security model

graph TB
    subgraph "AI Agent"
        LLM[LLM Client]
    end

    subgraph "MCP Transport"
        STDIO[stdio Transport]
    end

    subgraph "mcp-ssh-orchestrator"
        MCP[MCP Server]
        POLICY[Policy Engine]
        SSH[SSH Client]
        AUDIT[Audit Logger]
    end

    subgraph "Target Infrastructure"
        WEB[Web Servers]
        DB[Database Servers]
        MON[Monitoring]
    end

    LLM --> STDIO
    STDIO --> MCP
    MCP --> POLICY
    POLICY --> SSH
    SSH --> WEB
    SSH --> DB
    SSH --> MON
    MCP --> AUDIT

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

# Run interactively
docker run -i --rm \
  -v ~/mcp-ssh/config:/app/config:ro \
  -v ~/mcp-ssh/keys:/app/keys:ro \
  ghcr.io/samerfarida/mcp-ssh-orchestrator:latest

1. Create configuration directory:

   mkdir -p ~/mcp-ssh/{config,keys,secrets}

2. Copy example configurations:

   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

3. Add your SSH keys:

   cp ~/.ssh/id_ed25519 ~/mcp-ssh/keys/
   chmod 0400 ~/mcp-ssh/keys/id_ed25519

This wiki is organized into 16 comprehensive sections:

Policy-as-code map: Start with Configuration for the three YAML files, then read Security Model to see how those declarative rules are enforced at runtime.

• MCP Overview - Understanding the Model Context Protocol
• Risks - Security challenges in MCP environments
• Design Goals - Project philosophy and principles
• Architecture - System design and component relationships

• Security Model - Defense-in-depth security architecture
• Configuration - Complete configuration reference
  • servers.yml - Host inventory management
  • credentials.yml - SSH authentication setup
  • policy.yml - Security policy engine

• Tools Reference - Complete MCP tools documentation
• Usage Cookbook - Practical examples and patterns
• Deployment - Production setup and scaling
• Integrations - Claude Desktop and other MCP clients

• Observability & Audit - Logging, monitoring, compliance
• Troubleshooting - Common issues and solutions
• Contributing - Development workflow and guidelines

• CHANGELOG - Version history and releases
• FAQ - Frequently asked questions
• Glossary - Terms and definitions

See complete Tools Reference for detailed documentation.

This project implements comprehensive security controls:

• Non-root execution (UID 10001)
• Read-only filesystem mounts
• Resource limits (CPU, memory)
• Minimal base image (python:3.13-slim)

• IP allowlists with CIDR support
• Host key verification (known_hosts)
• DNS resolution verification
• Egress controls

• Deny-by-default security model
• Glob pattern command matching
• Per-host and per-tag overrides
• Dangerous command substring blocking
• Declarative YAML policy-as-code checked into version control

• JSON audit logs to stderr
• Complete operation trail
• OWASP LLM07 (Insecure Plugin Design) mitigation
• MITRE ATT&CK aligned logging
• Security features support compliance efforts

We welcome contributions! See our Contributing Guide for:

• Development setup
• Code style guidelines
• Testing requirements
• Pull request process

Apache 2.0 - See LICENSE for details.

• GitHub Repository
• Issue Tracker
• MCP Specification
• Docker MCP Security Guide

Next Steps: Start with MCP Overview to understand the protocol, then explore Architecture to see how everything fits together.