MCP SFTP Orchestrator

Orchestrates remote server tasks via SSH and SFTP with a persistent queue. Ideal for DevOps and AI agents.

Documentation

🚀 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