mcp-sftp-orchestrator

🚀 MCP Orchestrator — SSH/SFTP Infrastructure Orchestration Server

Version : 11.3.0 License : MIT Node : >= 18.0.0

A Model Context Protocol (MCP) server that turns any AI agent (Claude, OpenCode, Cursor...) into a full-fledged system administrator. Persistent queue, SSH connection pool, hybrid sync/async execution.

✨ Key Features

• 63 MCP tools — SSH, SFTP, file ops, monitoring, snapshots, tunnels
• Built-in security — Command blocklist, port allowlist, hash protection
• Multi-server — task_exec {alias:["vps1","vps2"]} or alias:"all"}
• Persistence — tmux + persistent queue = sessions that survive crashes
• Snapshots — Deduplicated versioning of your critical files
• SSH Tunnels — Local, Remote, SOCKS5 with secured port allowlist
• AI Guide — Built-in manual for the agent (section:index/workflows/audit/security)

🇫🇷 Version française : README.fr.md

---

📦 Installation

Via npx (recommended)

npx @fkom13/mcp-sftp-orchestrator

Via git

git clone https://github.com/fkom13/mcp-sftp-orchestrator.git
cd mcp-sftp-orchestrator
npm install
cp .env.example .env
# Edit .env with your paths

Requirements: Node.js >= 18.0.0

---

⚙️ Configuration (.env)

All variables are optional. Defaults are designed for standard usage.

| Variable | Default | Description | |----------|---------|-------------| | MCP_DATA_DIR | ~/.config/mcp-orchestrator | Data directory (servers.json, apis.json, queue.json) | | MCP_SYNC_TIMEOUT_S | 120 | Seconds before background execution | | MCP_DEFAULT_CMD_TIMEOUT_S | 600 | Default SSH timeout (0 = unlimited) | | MCP_INTERACTIVE_CMD_TIMEOUT_S | 300 | Interactive command timeout (0 = unlimited) | | MCP_MAX_WAIT_TIMEOUT_S | 600 | Max timeout for task_wait | | MAX_CONNECTIONS_PER_SERVER | 5 | Max parallel SSH connections per server | | MIN_CONNECTIONS_PER_SERVER | 1 | Min pooled connections per server | | IDLE_TIMEOUT | 300000 | Idle connection close delay (ms) | | KEEP_ALIVE_INTERVAL | 30000 | SSH keepalive interval (ms) | | MAX_QUEUE_SIZE | 1000 | Max jobs in queue | | SAVE_INTERVAL | 5000 | Queue disk save interval (ms) | | MCP_ALLOWED_ROOTS | (empty) | Restrict file access to these roots (comma-separated). Empty = full access | | MCP_DEBUG | false | Enable detailed debug logs |

---

🔌 MCP Client Configuration (OpenCode, Claude Desktop, etc.)

{
  "mcpServers": {
    "orchestrator": {
      "command": "node",
      "args": ["/path/to/sftp-mcp/server.js"],
      "env": {
        "MCP_DATA_DIR": "/path/to/sftp-mcp/data"
      }
    }
  }
}

---

🧰 Tool Reference (63 tools)

Help & Diagnostics

| Tool | Description | |------|-------------| | help | Complete guide: tools, env vars, parameter schemas | | guide | AI manual: workflows, cheatsheet, audit, security | | system_diagnostics | Full system diagnostic (queue, pool, servers, APIs) |

Server Management

| Tool | Description | |------|-------------| | server_add | Add/update a server alias | | server_list | List all configured servers | | server_remove | Remove a server alias | | infra_overview | Fleet-wide overview (roles, services, warnings) | | server_note_set/get/list/remove | Documented server context |

Security (Blocklist)

| Tool | Description | |------|-------------| | policy_blocklist_list | List blocked commands | | policy_blocklist_add | Add a pattern to blocklist | | policy_blocklist_remove | Remove a pattern from blocklist |

Task Execution

| Tool | Description | |------|-------------| | task_exec | SSH one-shot. Supports alias:["vps1","vps2"] or alias:"all" | | task_exec_interactive | SSH with interactive prompt handling | | task_exec_sequence | Sequential SSH commands | | task_transfer | SFTP transfer. Supports server_to_server | | task_transfer_multi | Bulk transfers with glob patterns |

Monitoring

| Tool | Description | |------|-------------| | get_system_resources | CPU, RAM, Disk metrics | | get_services_status | systemd, Docker, PM2 status (graceful fallback) | | get_fail2ban_status | Fail2Ban status | | check_api_health | HTTP health check |

Logs

| Tool | Description | |------|-------------| | get_pm2_logs | PM2 logs | | get_docker_logs | Docker logs | | tail_file | Tail a remote file |

File Operations (Local + Remote)

| Tool | Description | |------|-------------| | file_read | Read file + SHA-256 hash (edit protection) | | file_write | Create/overwrite with dryRun and backup | | file_edit | Surgical or full edit + hash protection |

Comparison & Drift Detection

| Tool | Description | |------|-------------| | diff_files | Compare 2 files (local/remote, cross-server) | | diff_folders | Compare 2 directories | | compare_all_sources | Detect drifts across N servers |

Persistent Shell Sessions

| Tool | Description | |------|-------------| | shell_create | Open a persistent shell (cd/env preserved) | | shell_exec | Execute in an existing session | | shell_list / shell_close | List/close sessions |

tmux (Surviving Terminal Sessions)

| Tool | Description | |------|-------------| | tmux_create | Create a persistent tmux session | | tmux_exec | Send a command to a session | | tmux_read | Read session buffer | | tmux_list / tmux_kill | List/kill sessions |

SSH Tunnels

| Tool | Description | |------|-------------| | tunnel_create | Local/remote/SOCKS5 tunnel, persistent via tmux | | tunnel_list | List active tunnels | | tunnel_close | Close a tunnel | | tunnel_allowlist_add/remove | Manage allowed ports |

Snapshots (File Versioning)

| Tool | Description | |------|-------------| | snapshot_create | Capture file state with deduplication | | snapshot_list | List snapshots | | snapshot_diff | Compare 2 snapshots | | snapshot_restore | Restore (dryRun by default) | | snapshot_delete | Delete + orphan cleanup |

Queue & Monitoring

| Tool | Description | |------|-------------| | task_queue | View all active/pending tasks | | task_status | Task detail by ID | | task_history | Filterable history | | task_retry | Retry a failed task | | task_wait | Wait for a background task | | task_logs | MCP internal logs | | queue_stats / pool_stats | Queue and SSH pool stats |

API Catalog

| Tool | Description | |------|-------------| | api_add / api_list / api_remove | API monitoring catalog | | api_check | Health check via SSH + curl |

---

📖 Usage Examples

Multi-server

# One command, multiple servers
task_exec {alias:["vps1","vps2","vps3"], cmd:"uptime"}

# Entire fleet
task_exec {alias:"all", cmd:"df -h /"}

SOCKS5 Proxy Tunnel

tunnel_create {name:"proxy", type:"socks", listen_port:1080, via:"vps_paris"}
# → Browser → SOCKS5 127.0.0.1:1080 → Paris VPS

Local Tunnel (access remote service)

tunnel_create {name:"crm", type:"local", listen_port:8080, target:"127.0.0.1:3100", via:"vps_prod"}
# → http://localhost:8080 → production CRM

Remote Tunnel (expose local service)

tunnel_create {name:"dev", type:"remote", listen_port:9090, target:"127.0.0.1:3000", via:"vps", source:"vps_prod", key_path:"/home/user/.ssh/vps.key"}
# → vps_prod:9090 → your local machine:3000

Persistent tmux Session

tmux_create {alias:"vps", name:"build", start_cmd:"npm run build"}
tmux_read {alias:"vps", session:"build"}
tmux_kill {alias:"vps", session:"build"}

Security Blocklist

# List blocked commands
policy_blocklist_list
# → ["rm -rf /", "mkfs*", ...]

# Conscious bypass
task_exec {alias:"vps", cmd:"rm -rf /tmp/cache", skip_policy:true}

Secure File Editing

# Read + hash
file_read {source:{type:"remote", alias:"vps", path:"/etc/nginx/nginx.conf"}}
# → content + hash

# Edit with protection
file_edit {source:{type:"remote", alias:"vps", path:"/etc/nginx/nginx.conf"},
           oldString:"worker_connections 768;",
           newString:"worker_connections 1024;",
           expectedHash:"abc123...",
           backup:true}

# Preview without writing
file_edit {source:{type:"remote", alias:"vps", path:"/etc/nginx/nginx.conf"},
           oldString:"worker_connections 768;",
           newString:"worker_connections 1024;",
           dryRun:true}

Snapshot Before Risky Changes

# Before
snapshot_create {source:{type:"remote", alias:"vps"}, paths:["/etc/nginx/"], tag:"before-fix"}

# After if something broke
snapshot_restore {snapshotId:"...", target:{type:"remote", alias:"vps"}, dryRun:false, force:true}

Multi-server Drift Detection

compare_all_sources {sources:[
  {type:"remote", alias:"vps1", path:"/etc/nginx/nginx.conf", label:"prod"},
  {type:"remote", alias:"vps2", path:"/etc/nginx/nginx.conf", label:"staging"}
]}

---

📚 AI Built-in Manual (guide)

The orchestrator includes an interactive manual for your AI agent:

guide section:index       # Table of contents
guide section:workflows   # Copy-paste recipes
guide section:cheatsheet  # Tool → usage table
guide section:audit       # Full fleet audit in 8 steps
guide section:security    # Blocklist + tunnels
guide section:pitfalls    # Common mistakes

---

🏗️ Architecture

MCP Client (stdio)
    │
server.js ─── 63 MCP tools registered
    │
    ├── queue.js ─────── Persistent job queue (JSON + backup)
    ├── ssh.js ───────── SSH execution (pool + dedicated connections)
    ├── sftp.js ──────── SFTP transfers (upload/download/multi)
    ├── sshPool.js ───── Persistent SSH connection pool
    ├── servers.js ───── CRUD server aliases
    ├── apis.js ──────── CRUD API catalog
    ├── history.js ───── Task history
    ├── config.js ────── Centralized configuration
    ├── utils.js ─────── Utilities (escapeShellArg)
    ├── fileOps.js ───── File operations (read/write/edit)
    ├── diffEngine.js ── Diff engine (files/dirs/sources)
    ├── compareEngine.js ─ Multi-source comparison
    ├── diffFormatter.js ─ Diff formatting
    ├── sourceAdapter.js ─ Local/remote abstraction
    ├── shellSessions.js ─ Persistent shell sessions
    ├── snapshotManager.js ─ Versioned snapshots
    ├── notes.js ──────── Documented server context
    ├── policies.js ──── Command blocklist
    ├── tunnels.js ────── SSH tunnels (local/remote/SOCKS)
    ├── guide.js ──────── AI built-in manual
    └── diagnose.js ───── Diagnostics

Job Lifecycle

pending → running → completed / failed
                      ↓ (on restart)
                    crashed → retry → pending

---

🔒 Security

• Command Blocklist : rm -rf /, mkfs*, fork bombs, and other destructive commands are blocked by default
• Conscious bypass : skip_policy: true to force execution
• Tunnel port allowlist : only explicitly allowed ports can be used
• File access restriction : MCP_ALLOWED_ROOTS env var to limit file operations to specific directories
• escapeShellArg() : all URLs and paths are escaped before being passed to curl/shell
• Plaintext secret detection : warning on startup if passwords/API keys are in plaintext
• Pre-modification snapshots : backup:true on file_edit/file_write for instant rollback
• Recommendation : use SSH keys (not passwords), store secrets in Vaultwarden

---

🧪 Tests

node diagnose.js        # Full diagnostic
node test_mcp.js        # MCP smoke test
node test_features.js   # Unit tests (queue, pool, glob, prompts, crash)

---

🛣️ Roadmap

| Version | Changes | |---------|---------| | 10.0.0 | New tools: file_read/write/edit, diff, snapshots, shell, notes | | 10.4.0 | server_to_server, help with schemas, audit guide | | 11.0.0 | Command Blocklist, Multi-host (alias:"all"), tmux | | 11.2.0 | SSH Tunnels (local/remote/SOCKS5), allowlist, ssh2 stderr fix | | 11.3.0 | AllowedRoots (MCP_ALLOWED_ROOTS) for file restriction | | 12.0.0 (planned) | Auto key setup for tunnels, webhooks, static dashboard |

---

📄 License

MIT — Copyright (c) 2025-2026 Franck (fkom13)