- Fix AsyncTaskManager tests to expect dictionaries instead of JSON strings - Fix error message assertions in server tool tests - Remove unused variables and fix whitespace issues - All 74 tests now pass with 55% code coverage - All linting issues resolved
mcp-ssh-orchestrator
A secure SSH fleet orchestrator built as a Model Context Protocol (MCP) server
Execute commands across your server fleet with policy-based access control, network filtering, and comprehensive audit logging.
Features
- Policy-Based Access Control: Fine-grained command allow/deny rules with glob pattern matching
- 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
- Async Task Support: SEP-1686 compliant asynchronous execution with real-time progress monitoring
- 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
Quick Start
Using Docker (Recommended)
# Pull the image
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
# 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:0.1.0
Using Docker Compose
End Users (Production):
# Clone the repository
git clone https://github.com/samerfarida/mcp-ssh-orchestrator
cd mcp-ssh-orchestrator
# Set up your configuration
cp examples/example-servers.yml config/servers.yml
cp examples/example-credentials.yml config/credentials.yml
cp examples/example-policy.yml config/policy.yml
# Edit config files with your hosts and credentials
# Place SSH keys in keys/ directory
# Run with compose (default - pulls published image)
cd compose
docker compose up
Developers (Local Build):
# Run with development compose (builds from source)
cd compose
docker compose -f docker-compose.dev.yml up --build
See the Compose README for more details on both options.
Local Development
# Clone the repository
git clone https://github.com/samerfarida/mcp-ssh-orchestrator
cd mcp-ssh-orchestrator
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install in editable mode
pip install -e .
# Run the MCP server
python -m mcp_ssh.mcp_server stdio
Configuration
Directory Structure
mcp-ssh-orchestrator/
├── config/
│ ├── servers.yml # Host inventory
│ ├── credentials.yml # SSH credentials
│ └── policy.yml # Security policies
├── keys/ # SSH private keys (chmod 0400)
└── secrets/ # Docker secrets (passwords, passphrases)
Policy Configuration
The policy.yml file controls security policies, command allow/deny rules, and execution limits. For comprehensive documentation:
- Policy Reference - Complete configuration reference with all options and defaults
- Policy Examples - Practical examples for different environments and use cases
- Policy Security - Security best practices and troubleshooting guide
servers.yml
Define your SSH hosts:
hosts:
- alias: "web1"
host: "10.0.0.11"
port: 22
credentials: "prod_admin"
tags:
- "web"
- "prod"
- "linux"
- alias: "db1"
host: "10.0.0.21"
port: 22
credentials: "prod_admin"
tags:
- "db"
- "prod"
- "linux"
credentials.yml
Configure SSH authentication:
entries:
- name: "prod_admin"
username: "ubuntu"
key_path: "id_ed25519" # Relative to /app/keys
key_passphrase_secret: "" # Optional passphrase
password_secret: "" # For password auth
- name: "password_auth"
username: "admin"
key_path: ""
password_secret: "admin_password" # Resolved from secret
Secrets Resolution:
- Environment variable:
MCP_SSH_SECRET_<NAME>(uppercase) - Docker secret file:
/app/secrets/<name>
policy.yml
Define security rules:
# Global limits
limits:
max_seconds: 60
max_output_bytes: 1048576
require_known_host: true
# Network controls
network:
allow_cidrs:
- "10.0.0.0/8"
block_ips: []
# Command rules
rules:
- action: "allow"
aliases: ["*"]
tags: []
commands:
- "uname*"
- "uptime*"
- "df -h*"
- action: "deny"
aliases: ["*"]
tags: []
commands:
- "rm -rf*"
- "shutdown*"
MCP Tools
ssh_ping
Health check.
{
"name": "ssh_ping",
"arguments": {}
}
ssh_list_hosts
List all configured hosts.
{
"name": "ssh_list_hosts",
"arguments": {}
}
Returns:
["web1", "db1", "app1"]
ssh_describe_host
Get host details.
{
"name": "ssh_describe_host",
"arguments": {
"alias": "web1"
}
}
ssh_plan
Dry-run a command (shows policy decision without executing).
{
"name": "ssh_plan",
"arguments": {
"alias": "web1",
"command": "uptime"
}
}
ssh_run
Execute a command on a host.
{
"name": "ssh_run",
"arguments": {
"alias": "web1",
"command": "uptime"
}
}
Returns:
{
"task_id": "web1:a1b2c3d4:1234567890",
"alias": "web1",
"exit_code": 0,
"duration_ms": 123,
"cancelled": false,
"timeout": false,
"target_ip": "10.0.0.11",
"output": "up 42 days, 3:14"
}
ssh_run_on_tag
Execute a command on all hosts with a tag.
{
"name": "ssh_run_on_tag",
"arguments": {
"tag": "prod",
"command": "uptime"
}
}
ssh_cancel
Cancel a running command.
{
"name": "ssh_cancel",
"arguments": {
"task_id": "web1:a1b2c3d4:1234567890"
}
}
ssh_reload_config
Reload configuration files without restarting.
{
"name": "ssh_reload_config",
"arguments": {}
}
Async Task Support (SEP-1686)
For long-running operations, use the async task tools that provide non-blocking execution with real-time progress monitoring:
ssh_run_async
Start SSH command asynchronously (SEP-1686 compliant).
{
"name": "ssh_run_async",
"arguments": {
"alias": "web1",
"command": "apt update && apt upgrade -y"
}
}
Returns immediately with task metadata:
{
"task_id": "web1:a1b2c3d4:1234567890",
"status": "pending",
"keepAlive": 300,
"pollFrequency": 5,
"alias": "web1",
"command": "apt update && apt upgrade -y",
"hash": "a1b2c3d4"
}
ssh_get_task_status
Get current status of an async task.
{
"name": "ssh_get_task_status",
"arguments": {
"task_id": "web1:a1b2c3d4:1234567890"
}
}
Returns:
{
"task_id": "web1:a1b2c3d4:1234567890",
"status": "running",
"keepAlive": 300,
"pollFrequency": 5,
"progress_percent": 45,
"elapsed_ms": 12000,
"bytes_read": 2048,
"output_lines_available": 12
}
ssh_get_task_result
Get final result of completed task.
{
"name": "ssh_get_task_result",
"arguments": {
"task_id": "web1:a1b2c3d4:1234567890"
}
}
Returns:
{
"task_id": "web1:a1b2c3d4:1234567890",
"status": "completed",
"exit_code": 0,
"duration_ms": 45000,
"output": "Reading package lists... Done\nBuilding dependency tree... Done",
"cancelled": false,
"timeout": false,
"target_ip": "10.0.0.11"
}
ssh_get_task_output
Get recent output lines from running or completed task.
{
"name": "ssh_get_task_output",
"arguments": {
"task_id": "web1:a1b2c3d4:1234567890",
"max_lines": 50
}
}
ssh_cancel_async_task
Cancel a running async task.
{
"name": "ssh_cancel_async_task",
"arguments": {
"task_id": "web1:a1b2c3d4:1234567890"
}
}
Async Task Benefits
- Non-blocking execution: Start commands and continue with other tasks
- Real-time progress: Monitor progress without repeated SSH connections
- Efficient resource usage: Single background connection per task
- SEP-1686 compliance: Standardized task lifecycle management
- Configurable TTL: Task results kept for 5 minutes (configurable per host/tag)
- MCP notifications: Server-initiated updates for task state changes
Docker Desktop Integration
Quick Setup
-
Create configuration directory:
mkdir -p ~/mcp-ssh/{config,keys,secrets} -
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 -
Add your SSH keys:
cp ~/.ssh/id_ed25519 ~/mcp-ssh/keys/ chmod 0400 ~/mcp-ssh/keys/id_ed25519 -
Configure Claude Desktop (
~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS):
{
"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.1.0"
]
}
}
}
Replace YOUR_USERNAME with your actual username!
Docker Desktop GUI Configuration
For users who prefer the Docker Desktop GUI:
- Open Docker Desktop and go to Settings → Resources → File Sharing
- Add your configuration directory to the shared folders list
- Use the GUI to configure MCP servers in Claude Desktop settings
Environment Variables for Secrets
Instead of files, you can use environment variables:
{
"mcpServers": {
"ssh-orchestrator": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "MCP_SSH_SECRET_STAGING_PASSWORD=your-password",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/keys:/app/keys:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0"
]
}
}
}
Complete Setup Guide
For detailed setup instructions, see DOCKER_DESKTOP.md.
Security Best Practices
- SSH Keys: Use key-based authentication instead of passwords
- File Permissions: Set private keys to
chmod 0400 - Known Hosts: Enable
require_known_host: truein production - Network Filtering: Use
allow_cidrsto restrict target IPs - Command Policies: Start with deny-by-default and allow specific patterns
- Read-Only Mounts: Mount config and keys as read-only (
:ro) - Secrets: Never commit secrets to Git; use Docker secrets or env vars
- Audit Logs: Monitor stderr output for security events
Development
Running Tests
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=mcp_ssh --cov-report=html
Linting
# Format code
black src/ tests/
# Lint
ruff check src/ tests/
# Type check
mypy src/
Building Docker Image
docker build -t mcp-ssh-orchestrator:local .
Contributing
See CONTRIBUTING.md for development setup and contribution guidelines.
This project follows the Contributor Covenant Code of Conduct.
License
Apache 2.0 - See LICENSE for details.