Ftp Deploy MCP

ftp-deploy-mcp

The deploy button for AI coding agents.

Give Claude Code, Claude Desktop, Cursor, Windsurf, Trae, Antigravity, or any MCP client a focused way to list, read, upload, download, and deploy files on your own FTP, FTPS, and SFTP servers.

The stdio server implements MCP revision 2026-07-28 through the stable modular TypeScript SDK v2 and retains the SDK's legacy negotiation path for older MCP clients.

*Version française → README.fr.md*

CLI and MCP language: English by default; use --lang fr or FTP_MCP_LANG=fr. Language scope and precedence.

Purpose-built deployment controls keep credentials out of tool responses, support read-only servers and dry runs, and limit local file access with localRoot. The repository is covered by an extensive end-to-end suite that runs against local FTP and SFTP servers. There is no telemetry.

Availability: version 0.3.2 is published on

npm and the

Official MCP Registry.

Use npx -y ftp-deploy-mcp@0.3.2 for that version. The

GitHub release

is a separate source distribution; main can include later changes.

Registry visibility establishes availability, not locked dependency resolution

or qualification of a different commit. See the release guide.

Deployment modes: the ten base tools provide controlled transfers and dry runs. Enabling stateDir adds four durable tools with MCP confirmation, explicit resume and conservative rollback of acknowledged changes. These guarantees belong to the optional durable workflow; legacy ftp_deploy has no transaction or rollback.

Documentation

Architecture and scenarios

Explore the current and target architecture diagrams and illustrative scenarios in the bilingual interactive HTML guide. The guide and its English / French build instructions are in the repository, outside the npm package. After cloning, open site/index.html locally and use its language selector.

Animated verified deployment flow

For reduced motion, view the static completed-state image. See the visual system provenance and generation notes.

The visual direction was explored with ChatGPT Image; the final README assets are rendered deterministically. Their provenance and exact prompts document their illustrative role; they are not a certification.

First source install

1. Install a supported Node.js version: 22, 24 or 26 (minimum: 22).
2. Run git clone https://github.com/alebgl77/ftp-deploy-mcp.git, then cd ftp-deploy-mcp.
3. Run npm ci --omit=dev --ignore-scripts.
4. Run npm run setup, then edit the generated server config: set an absolute localRoot, replace credentials, and configure the SFTP host-key pin or the FTP/FTPS safety acknowledgments described below.
5. Restart the MCP client and try a dry run:

Call ftp_deploy with:

{"server":"prod","local_dir":"dist","remote_dir":"/","dry_run":true}

Windows users can run install.cmd and macOS/Linux users can run ./install.sh instead of steps 3–4. Review every generated server entry before the first connection.

For a tagged version, check out that exact tag before installing. npm ci uses the sole authoritative package-lock.json, with six exact direct pins and the reviewed graph. Keep it with the sources. --ignore-scripts disables automatic dependency lifecycle scripts; setup is a separate, explicit action.

Once published, the v0.3.2 source installation asset is named ftp-deploy-mcp-0.3.2-source.tar.gz: 90 files, including that lockfile. Verify its publication and checksums before extracting it in a fresh directory:

tar --ignore-zeros -xzf ftp-deploy-mcp-0.3.2-source.tar.gz

cd package npm ci --omit=dev --ignore-scripts node src/index.js setup

This installation archive excludes repository tests and maintainer scripts; GitHub's automatic source ZIP/tar contains the complete repository. The separate npm .tgz contains 89 files without a lockfile and follows npm dependency resolution. It provides no locked-install guarantee. See the release guide for verification and limits.

Protocol and security matrix

All three protocols also enforce localRoot for ftp_upload, ftp_deploy, and ftp_download. This limits which local files the MCP server can access.

What you get

• Ten focused MCP tools for server discovery, testing, listing, reading, uploading, recursive deploys, downloading, creating directories, renaming, and deleting.
• Four additional durable-workflow tools when stateDir is configured; confirmation and rollback follow the documented bounds.
• Multiple named servers in one local configuration.
• Gitignore-like deploy exclusions, dry-run, and per-server readOnly mode.
• FileZilla import, an interactive setup wizard, and a read-only doctor command.
• Credentials loaded locally from the config, environment variables, or SSH keys and never intentionally returned to the model.

Server configuration

An explicit configuration path is authoritative:

1. --config
2. FTP_MCP_CONFIG, when --config is absent

An empty, missing, unreadable, or invalid explicit configuration reports an error without falling back to another file. The MCP tools remain available to report the configuration problem. --config requires a path argument.

Without either selector, the first configuration found wins:

1. ./ftp-servers.json
2. ~/.ftp-mcp/servers.json

The teaching example below is JSON with comments. Real configuration files must be strict JSON; start from ftp-servers.example.json.

{

"defaultServer": "prod", "stateDir": "/home/alice/.local/state/ftp-deploy-mcp", "requirePlan": true, "servers": { "prod": { "protocol": "sftp", "host": "ssh.example.com", "port": 22, "user": "deploy", "password": "${ENV:PROD_PASSWORD}", "privateKeyPath": "~/.ssh/id_ed25519", "passphrase": "${ENV:PROD_KEY_PASSPHRASE}", "localRoot": "/home/alice/projects/site", "root": "/var/www/site", "hostKeySha256": "SHA256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "readOnly": false } } }

Replace the all-A fingerprint; it is deliberately non-functional for a real host. Use hostKeySha256 as an array during a controlled key rotation:

"hostKeySha256": [

"SHA256:old_verified_43_character_base64_value_here", "SHA256:new_verified_43_character_base64_value_here" ]

The illustrative labels above show the shape but are not valid pins. Each real entry is exactly SHA256: plus 43 characters of unpadded base64.

Field reference

| stateLimits | top level | Optional strict durable quotas for state, backups, plans, opera