Sftp Orchestrator MCP Server

🚀 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.

---

🔌 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

Server Management

Security (Blocklist)

Task Execution

Monitoring

Logs

File Operations (Local + Remote)

Comparison & Drift Detection

Persistent Shell Sessions

tmux (Surviving Terminal Sessions)

SSH Tunnels

Snapshots (File Versioning)

Queue & Monitoring

API Catalog

---

📖 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

---

📄 License

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