Files
mcp-ssh-orchestrator/compose
Sammy Farida 6df4b6660f docs: improve documentation clarity and technical precision
- Refine security descriptions with specific technical controls
- Update phrasing to emphasize concrete security features
- Enhance readability across documentation files
2025-10-27 10:20:14 -04:00
..

MCP-SSH-ORCHESTRATOR — Compose Environment

This directory provides Docker Compose configurations for the
mcp-ssh-orchestrator
MCP (Model Context Protocol) server.

Choose Your Setup

We provide two Docker Compose files depending on your use case:

File Purpose When to Use
docker-compose.yml Production/End User - Pulls published image For end users who want to use the published image (default)
docker-compose.dev.yml Development/Testing - Builds from local source For developers and contributors working on the codebase

If you just want to use the tool and don't plan to modify the code:

  1. Create configuration directories:

    mkdir -p ~/mcp-ssh/{config,keys,secrets}
    
  2. Copy example configurations:

    # If you've cloned the repo
    cd mcp-ssh-orchestrator
    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
    
    # Edit these files with your actual hosts and credentials
    
  3. Add your SSH keys:

    cp ~/.ssh/id_ed25519 ~/mcp-ssh/keys/
    chmod 0400 ~/mcp-ssh/keys/id_ed25519
    
  4. Run with compose (default production setup):

    cd mcp-ssh-orchestrator/compose
    docker compose up
    

The production compose file automatically pulls the ghcr.io/samerfarida/mcp-ssh-orchestrator:latest image.


Development Setup (For Contributors)

If you're developing or contributing to the project:

  1. Use the setup script (auto-detects dev mode in repo):

    cd compose
    ./setup.sh dev
    

    Or just:

    ./setup.sh
    
  2. Run with development compose (builds from source):

    docker compose -f docker-compose.dev.yml up --build
    

This will build the container from the local Dockerfile in the repository root.


What's Included

File Purpose
docker-compose.yml Prod: Pulls published image from ghcr.io (default)
docker-compose.dev.yml Dev: Builds container from local source
.env.example Template for environment variables (copy to .env)
setup.sh Automated setup script for directories and configs
README.md You're reading it! Usage guide and examples

Prerequisites

Before running the container:

  1. Ensure Docker and Docker Compose v2+ are installed.

  2. For production use: Clone the repo or copy example configs to your chosen location.

  3. For development: Use the automated setup script:

    cd compose
    ./setup.sh dev
    

    This will:

    • Create required directories (../config, ../keys, ../secrets)
    • Copy example configuration files from ../examples/
    • Create .env from .env.example

    Note: The script auto-detects if you're in the repo, so just ./setup.sh works too.

For end users: You can also use the setup script:

cd ~/mcp-ssh  # or wherever you want your config
wget https://raw.githubusercontent.com/samerfarida/mcp-ssh-orchestrator/main/compose/setup.sh
chmod +x setup.sh
./setup.sh enduser
  1. Add your SSH private keys and password files under:
    • ../keys — SSH key files (e.g., id_ed25519)
    • ../secrets — password or passphrase files

Configuration

Environment Variables

Create a .env file to customize settings (optional):

# Copy example if not exists
cp .env.example .env

# Edit to tune settings
nano .env

Example .env:

MCP_SSH_MAX_CONCURRENCY=10
MCP_SSH_TIMEOUT_SEC=60

Running the Server

Option A: Production Mode (End Users)

Pull and run the published image (default):

# From the compose directory
docker compose up

This:

  • Pulls the ghcr.io/samerfarida/mcp-ssh-orchestrator:latest image
  • Mounts ../config, ../keys, and ../secrets as read-only volumes
  • Launches the MCP server in STDIO mode

Option B: Development Mode (Contributors)

Build from local source:

# From the compose directory
docker compose -f docker-compose.dev.yml up --build

This:

  • Builds the container from the local Dockerfile
  • Mounts ../config, ../keys, and ../secrets as read-only volumes
  • Launches the MCP server in STDIO mode

Note: The --build flag ensures changes to the source code are included.

Verify It's Running

You should see startup logs like:

{"evt": "server_start", "tool": "mcp-ssh-orchestrator", "mode": "stdio"}

Testing from Claude Desktop

For Production (using published image - default):

Add this to your Claude Desktop config.json:

{
  "mcpServers": {
    "mcp-ssh-orchestrator": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/ABS/PATH/mcp-ssh-orchestrator/compose/docker-compose.yml",
        "run",
        "--rm",
        "mcp-ssh"
      ]
    }
  }
}

For Development (using local build):

{
  "mcpServers": {
    "mcp-ssh-orchestrator": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/ABS/PATH/mcp-ssh-orchestrator/compose/docker-compose.dev.yml",
        "run",
        "--rm",
        "mcp-ssh"
      ]
    }
  }
}

Important

: Replace /ABS/PATH/mcp-ssh-orchestrator/ with your actual directory path.

Alternative: You can also use the direct Docker run command (simpler, no compose needed):

{
  "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"
      ]
    }
  }
}

Useful Commands

Production Mode (Default)

Action Command
Check logs docker compose logs -f
Pull latest image docker compose pull
Stop everything docker compose down -v

Development Mode

Action Command
Check logs docker compose -f docker-compose.dev.yml logs -f
Rebuild image docker compose -f docker-compose.dev.yml build --no-cache
Stop everything docker compose -f docker-compose.dev.yml down -v
Clean old images docker system prune -f

Developer Notes

• The server uses STDIO transport only. • Default config path: /app/config • Default entrypoint: python -m mcp_ssh.mcp_server stdio • Parallel SSH execution supports configurable concurrency limits. • Policy enforcement supports glob and regex patterns.