mcp-server-sftp

A fast Model Context Protocol (MCP) server that exposes an SFTP connection as tools — read, write, delete, list, mkdir, rmdir, rename, upload, download, stat, exists — plus pipelined batch tools (write_many, delete_many, upload_many, download_many) and a sync_dir for folder deploys.

It speaks SFTP over raw ssh2, so it works even against chrooted, SFTP-only accounts (ForceCommand internal-sftp, i.e. hosts with no shell exec). An optional write-path guard restricts mutating operations to a subtree.

Features

• Full file ops over SFTP — including delete / rmdir, which many SSH MCP servers omit.
• Batch + concurrent — *_many tools and sync_dir issue many requests in flight on a single channel, so bulk operations collapse from N × round-trips to ~1 × round-trip. On a high-latency link this is an order of magnitude faster (see Performance).
• Works on shell-less hosts — no exec required; pure SFTP subsystem.
• Write guard — SFTP_ALLOWED_PREFIX refuses writes/deletes/renames outside a chosen subtree (reads stay unrestricted). Applied per item in batch tools.
• Warm, reused connection — one ssh2 client + SFTP channel is opened at startup and reused, with automatic reconnect on drop, so the first tool call doesn't pay the SSH handshake.
• Credentials via env only — nothing is hard-coded; supports password or private-key auth.

Requirements

• Node.js >= 18
• An SSH/SFTP account on the target host

Installation

git clone https://github.com/wpfyorg/mcp-server-sftp.git
cd mcp-server-sftp
npm install

Configuration

The server is configured entirely through environment variables:

Variable	Required	Default	Description
SFTP_HOST	yes	—	Hostname or IP of the SFTP server
SFTP_USER	yes	—	SSH/SFTP username
SFTP_PASSWORD	*	—	Password auth (required unless using a key)
SFTP_PORT	no	22	SSH port
SFTP_PRIVATE_KEY	*	—	Path to a private key file (alternative to password)
SFTP_PASSPHRASE	no	—	Passphrase for the private key, if any
SFTP_ALLOWED_PREFIX	no	(none)	If set, writes/deletes/renames must be under this absolute path
SFTP_MAX_READ_BYTES	no	1048576	sftp_read refuses files larger than this (use sftp_download)
SFTP_READY_TIMEOUT	no	20000	SSH handshake timeout (ms)
SFTP_MAX_CONCURRENCY	no	8	Max in-flight operations per batch/sync_dir call
SFTP_TRANSFER_CONCURRENCY	no	64	Parallel chunks for upload/download (fastPut/fastGet)
SFTP_CHUNK_SIZE	no	32768	Chunk size in bytes for fastPut/fastGet

* Provide at least one of SFTP_PASSWORD or SFTP_PRIVATE_KEY.

MCP client configuration

Add the server to your MCP client config (e.g. Cursor .cursor/mcp.json, Claude Desktop, etc.):

{
  "mcpServers": {
    "sftp": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-sftp/index.mjs"],
      "env": {
        "SFTP_HOST": "203.0.113.10",
        "SFTP_PORT": "22",
        "SFTP_USER": "deploy",
        "SFTP_PASSWORD": "••••••••",
        "SFTP_ALLOWED_PREFIX": "/var/www/html/wp-content"
      }
    }
  }
}

Tools

Tool	Arguments	Notes
sftp_list	remotePath	List a directory (read-only)
sftp_read	remotePath	Read a text file; refuses files > SFTP_MAX_READ_BYTES
sftp_write	remotePath, content, createDirs?	Write/overwrite a text file
sftp_delete	remotePath	Delete a file
sftp_mkdir	remotePath, recursive? (default true)	Create a directory
sftp_rmdir	remotePath, recursive? (default false)	Remove a directory
sftp_rename	fromPath, toPath	Rename/move (destination is guarded)
sftp_upload	localPath, remotePath, createDirs?	Upload a local file (binary-safe)
sftp_download	remotePath, localPath	Download to a local path
sftp_stat	remotePath	Stat a path (read-only)
sftp_exists	remotePath	Returns false | 'd' | '-' | 'l'
sftp_write_many	files:[{remotePath,content}], createDirs?, concurrency?	Write many text files in parallel
sftp_delete_many	remotePaths:[...], concurrency?	Delete many files in parallel
sftp_upload_many	files:[{localPath,remotePath}], createDirs?, concurrency?	Upload many local files in parallel
sftp_download_many	files:[{remotePath,localPath}], concurrency?	Download many files in parallel
sftp_sync_dir	localDir, remoteDir, delete?, dryRun?, concurrency?	Sync a local folder to remote (upload missing/changed/newer; optional delete of orphans)

All paths must be absolute. Mutating tools (write, delete, mkdir, rmdir, rename, upload, all *_many, sync_dir) are subject to SFTP_ALLOWED_PREFIX when set; reads are always allowed. Batch tools return a per-item PASS/FAIL summary and report isError if any item failed.

Performance

The physical floor on a remote host is network round-trip time (RTT), and every SFTP operation costs several sequential round-trips. Against a host ~311 ms away, issuing operations one at a time is what makes a "deploy" feel slow — not the byte count.

SFTP allows many requests in flight on a single channel, so the batch tools and sync_dir pipeline their work over the one warm connection. Measured on the ~311 ms host (10 tiny files, raw ssh2):

Workload	Sequential	Pipelined (batch tool)	Speed-up
write × 10	~25.6 s	~2.2 s	~11×
stat × 10	~8.9 s	~0.9 s	~10×
delete × 10	~6 s	~2.0 s	~3×

Rule of thumb: N files done sequentially ≈ N × RTT; done in one batch ≈ 1 × RTT. For a real folder deploy, prefer sftp_sync_dir (or a *_many tool) over a loop of single calls.

Notes:

• The warm connection means the one-time SSH handshake is paid at startup, not on your first tool call.
• Beyond pipelining, the only way past the RTT floor is to run the server near the host (same region/datacenter, RTT → ~1 ms) — an infrastructure change, out of scope for this server.

Security notes

• Credentials are read from the environment — keep them in your MCP client config or a secrets manager, not in source.
• SFTP_ALLOWED_PREFIX is defense-in-depth on top of the server's own filesystem permissions; set it to the narrowest writable subtree you need.
• The server never invokes a shell; it uses the SFTP subsystem only.

License

MIT