sftp-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
sftp-mcp
SFTP for AI assistants. Files only, no shell.
A Model Context Protocol server that lets Claude and other MCP clients browse, edit, transfer and sync files over plain SFTP. It works on chrooted, SFTP-only and shared-hosting accounts where SSH-based servers can't run, and the assistant never gets a shell.
Install · Configure · Tools · Security · Contribute
Why sftp-mcp?
Most MCP servers for remote machines are SSH servers that can also move files. They need a shell account and give the assistant command execution. sftp-mcp does the opposite: it only speaks the SFTP protocol.
sftp-mcp | Typical SSH MCP server | |
Works with SFTP-only and chrooted accounts | Yes | Usually needs a shell |
Assistant can run arbitrary commands | No | Yes |
Read-only, no-delete and path limits per server | Built in | Varies |
Many hosts from one process | Yes | Varies |
Parallel transfers over one warm connection per host | Yes | Varies |
Directory sync that uploads only changed files | Yes | Varies |
The only remote command it ever sends is a fixed sha256sum for hashing. If the account has no shell, it hashes over SFTP instead.
Pick sftp-mcp when the assistant should work with files: deploying a site, editing configs, pulling logs or syncing a build. Pick an SSH server when it needs to run commands.
Related MCP server: ssh-mcp
Installation
Requires Node.js 24 or newer. Most MCP clients can start the server straight from npm, with nothing to install:
npx -y sftp-mcpOr install it globally and use the sftp-mcp command:
npm install -g sftp-mcpQuick start
Add the server to your MCP client. For Claude Desktop, edit claude_desktop_config.json:
{
"mcpServers": {
"sftp": {
"command": "npx",
"args": ["-y", "sftp-mcp"],
"env": {
"SFTP_HOST": "sftp.example.com",
"SFTP_USER": "deploy",
"SFTP_PRIVATE_KEY": "/home/me/.ssh/id_ed25519"
}
}
}
}On Windows, npx may need to go through cmd: "command": "cmd", "args": ["/c", "npx", "-y", "sftp-mcp"].
For Claude Code:
claude mcp add sftp -e SFTP_HOST=sftp.example.com -e SFTP_USER=deploy \
-e SFTP_PRIVATE_KEY=$HOME/.ssh/id_ed25519 -- npx -y sftp-mcpRestart the client and ask it something like "list /var/www on the sftp server".
Configuration
All configuration comes from environment variables. Invalid values stop the server at startup with a clear error, so a typo never quietly loosens a policy.
Single server
Variable | Default | Description |
| required | SSH host |
|
| SSH port |
| required | SSH username |
| Password authentication | |
| Path to a private key file | |
| Passphrase for the private key |
The server is registered with the id default.
Multiple servers
Describe the servers as a JSON map of id to connection. Pass it inline in SFTP_SERVERS, or as a file path in SFTP_SERVERS_FILE. You can't set both.
{
"prod": {
"host": "prod.example.com",
"username": "deploy",
"privateKey": "/home/me/.ssh/id_ed25519",
"allowedWritePrefix": "/var/www",
"allowDestructive": false,
"description": "Production web"
},
"staging": {
"host": "staging.example.com",
"port": 2222,
"username": "ci",
"password": "secret"
}
}Field | Description |
| Required |
| Defaults to |
| Credentials. |
| Per-server overrides of the global settings below |
| Path restrictions, see Access control |
| Shown to the assistant in |
Ids must match [A-Za-z0-9][A-Za-z0-9_.-]*. Unknown fields stop startup. The single-server variables can't be combined with a server map.
Global settings
Variable | Default | Description |
|
| Deny every remote mutation |
|
|
|
| Absolute path prefix for mutations (single-server mode) | |
| Absolute path prefix for reads (single-server mode) | |
| Comma-separated tool names to hide from the client | |
|
| SSH handshake timeout, in ms |
|
| Size limit for |
|
| Default parallelism of the batch tools |
|
| In-flight requests per file transfer |
|
| Transfer chunk size in bytes (minimum 1024) |
| Also append logs to this file, for clients that hide stderr. Its directory must exist |
Booleans must be exactly true or false.
Access control
Policies apply to each server separately and are checked before any SFTP request is sent.
Policy | Effect |
| Blocks every mutation, including dry-run sync. Overrides everything else. |
| Writes, uploads and mkdir still work. Delete, rmdir, rename/move and non-dry-run sync are blocked. |
| Mutations only inside this path. Both ends of a rename are checked. |
| Listing, reading, downloads, stat and hashing only inside this path. |
Prefixes are normalized and compared as POSIX paths: /srv/app allows /srv/app and /srv/app/x, but not /srv/app-old. A prefix of / allows everything.
Prefix checks are lexical. A symlink on the server can still point outside the allowed prefix. For hard isolation, use a chroot, account permissions, or SFTP server configuration.
To hide tools from the assistant entirely, set SFTP_DISABLED_TOOLS, for example sftp_delete,sftp_sync_dir. Hidden tools are never registered, so they never appear in the client's tool list.
Tools
Every tool except sftp_list_servers takes a server argument (one of the configured ids).
Tool | Kind | Description |
| discovery | Configured servers with their address, policy and description |
| read | List a directory (type, size, mtime, name) |
| read | Read a text file, up to |
| read | File metadata |
| read |
|
| read | SHA-256 via |
| read | Download a remote file to a local path |
| read | Parallel downloads |
| write | Create or overwrite a text file from inline content |
| write | Upload a local file (binary-safe, parallel chunks) |
| write | Create a directory, optionally recursive |
| write | Parallel text writes |
| write | Parallel uploads |
| write | Upload missing, changed or newer files. Can also delete remote files missing locally. Supports |
| destructive | Delete a file |
| destructive | Remove a directory, optionally recursive |
| destructive | Rename or move |
| destructive | Parallel deletes |
Batch tools report each failure individually, so one bad file doesn't abort the batch.
Development
Requires Bun 1.4+ for tooling. The published package runs on plain Node.js 24+.
git clone https://github.com/AdversTM/sftp-mcp.git
cd sftp-mcp
bun install
bun run test # unit tests (vitest)
bun run typecheck # strict TypeScript
bun run check # Biome lint + format check (bun run format to fix)
bun run build # compile to dist/ for Node.jsProject layout
src/
index.ts entry point: config, transport, lifecycle
config.ts env / JSON parsing and validation (zod)
server.ts MCP registration: tool descriptions + input schemas
tool-catalog.ts canonical list of tool names
tools-read.ts read-only tool handlers
tools-write.ts mutation tool handlers
tools-batch.ts parallel batch tools and directory sync
paths.ts path normalization and access-policy guards
sftp-connection.ts ssh2 provider: warm connection, retry, hashing
sftp-operations.ts shared helpers over the provider interface
test/ vitest suites, using an in-memory SFTP provider
scripts/
smoke-test.mjs end-to-end check against a real SFTP serverAdding a tool
Add the name to
toolNamesinsrc/tool-catalog.ts.Add a description and a zod input schema in
src/server.ts. The compiler enforces both throughRecord<ToolName, …>.Implement the handler in the matching
tools-*.tsmodule. Before touching the provider, run every remote path throughdeps.guards.guardRead,guardWriteorguardDestructive.Cover it in
test/tools.test.ts.
End-to-end smoke test
Run the server against a disposable SFTP container:
docker run -d --rm --name sftp -p 127.0.0.1:2222:22 atmoz/sftp "smoke:smoke:::upload"
SFTP_HOST=127.0.0.1 SFTP_PORT=2222 SFTP_USER=smoke SFTP_PASSWORD=smoke \
node scripts/smoke-test.mjs node dist/index.jsContributing
Contributions are welcome. Please open an issue before starting large changes, and make sure test, typecheck and check pass.
License
MIT © Damian Szuster
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to maintain persistent SSH terminal sessions and transfer files to/from remote servers. Allows stateful command execution, natural language server management, and seamless file operations through SSH connections.10 npm35MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to execute shell commands and transfer files via SFTP across remote servers using existing SSH configurations. It supports parallel execution on server groups and provides built-in safety warnings for potentially destructive commands.662 PyPI7Mozilla Public 2.0
- AlicenseNot gradedqualityDmaintenanceProvides a browsable, mutable SFTP filesystem for AI agents, supporting file operations like listing, uploading, downloading, moving, and deleting.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage remote servers via SSH, including command execution, multi-host batch operations, SFTP file transfer, background job handling, DevOps diagnostics, port tunneling, and safety guardrails like high-risk command blocking and read-only mode.MIT