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.

Related MCP server: MCP Filesystem Server

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:

* 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

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):

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