ftp-deploy-mcp

<div align="center">

<img src="https://raw.githubusercontent.com/alebgl77/ftp-deploy-mcp/main/assets/logo.svg" width="96" alt="ftp-deploy-mcp logo">

# 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](./README.fr.md)*

CLI and MCP language: English by default; use `--lang fr` or `FTP_MCP_LANG=fr`.
[Language scope and precedence](./docs/LANGUAGES.md).

[![CI](https://github.com/alebgl77/ftp-deploy-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/alebgl77/ftp-deploy-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![Node >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](./package.json)
[![MCP compatible](https://img.shields.io/badge/MCP-compatible-8A2BE2.svg)](https://modelcontextprotocol.io)

<img src="https://raw.githubusercontent.com/alebgl77/ftp-deploy-mcp/main/assets/banner-en.png" width="100%" alt="ftp-deploy-mcp — Controlled deployment for your AI agents; FTP, FTPS, SFTP over MCP stdio">

</div>

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:** the package is available from npm and listed in the
> Official MCP Registry; `npx -y ftp-deploy-mcp` runs the currently published
> version. This checkout targets version 0.3.2. Confirm that this exact version
> appears on both registries before treating its publication as complete.
> GitHub source releases remain a separate distribution channel; find their
> published versions on
> [GitHub Releases](https://github.com/alebgl77/ftp-deploy-mcp/releases/latest).

## Documentation

| Document | English | Français |
|---|---|---|
| Overview and installation | [README](./README.md) | [README](./README.fr.md) |
| Changes | [Changelog](./CHANGELOG.md) | [Modifications](./CHANGELOG.fr.md) |
| Contributing | [Guide](./CONTRIBUTING.md) | [Guide](./CONTRIBUTING.fr.md) |
| Security policy | [Policy](./SECURITY.md) | [Politique](./SECURITY.fr.md) |
| Security model | [Model](./docs/SECURITY-MODEL.md) | [Modèle](./docs/SECURITY-MODEL.fr.md) |
| Release process | [Guide](./docs/RELEASE.md) | [Guide](./docs/RELEASE.fr.md) |
| Agent evaluation | [Instructions](./evaluations/README.md) | [Instructions](./evaluations/README.fr.md) |
| Agent performance and client integration | [Guide](./docs/AGENT-PERFORMANCE.md) | [Guide](./docs/AGENT-PERFORMANCE.fr.md) |
| Scripted MCP conformance | [Guide](./docs/SCRIPTED-EVALUATIONS.md) | [Guide](./docs/SCRIPTED-EVALUATIONS.fr.md) |
| CLI and MCP languages | [Guide](./docs/LANGUAGES.md) | [Guide](./docs/LANGUAGES.fr.md) |
| MCP error contract | [Contract](./docs/ERROR-CONTRACT.md) | [Contrat](./docs/ERROR-CONTRACT.fr.md) |
| Verified staged transfers | [Guide](./docs/TRANSFERS.md) | [Guide](./docs/TRANSFERS.fr.md) |
| Scan and admission limits | [Limits](./docs/RESOURCE-BOUNDS.md) | [Limites](./docs/RESOURCE-BOUNDS.fr.md) |
| Durable state storage | [Library](./docs/STATE-STORAGE.md) | [Bibliothèque](./docs/STATE-STORAGE.fr.md) |
| Durable workflow model | [Model](./docs/WORKFLOW-MODEL.md) | [Modèle](./docs/WORKFLOW-MODEL.fr.md) |
| MIT license | [Canonical text](./LICENSE) | [Informative translation](./LICENSE.fr.md) |

## Architecture and scenarios

<div align="center">

<img src="https://raw.githubusercontent.com/alebgl77/ftp-deploy-mcp/main/assets/architecture-overview.png" width="100%" alt="Architecture overview: MCP client routes locally confined FTP, FTPS, and SFTP transfers through ftp-deploy-mcp.">

</div>

Explore the current and target architecture diagrams and illustrative scenarios
in the bilingual [interactive HTML guide](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/site/index.html).
The guide and its
[English](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/site/README.md) / [French](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/site/README.fr.md)
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

<div align="center">

<img src="https://raw.githubusercontent.com/alebgl77/ftp-deploy-mcp/main/assets/verified-deployment-flow.gif" width="100%" alt="Animated verified deployment flow: scan, plan, approve, transfer, verify, and promote with a rollback safety path.">

</div>

For reduced motion, view the [static completed-state image](https://raw.githubusercontent.com/alebgl77/ftp-deploy-mcp/main/assets/verified-deployment-flow.png).
See the [visual system provenance and generation notes](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/assets/provenance/visual-system-2026-10-17.md).

The visual direction was explored with ChatGPT Image; the final README assets
are rendered deterministically. Their
[provenance and exact prompts](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/assets/provenance/README.md)
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:

```text
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:

```bash
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](./docs/RELEASE.md) for verification and limits.

## Protocol and security matrix

| Protocol | Transport identity | Remote-root behavior | Recommended use |
|---|---|---|---|
| **SFTP** | Encrypted. `hostKeySha256` is required unless `allowUnknownHostKey: true` explicitly accepts impersonation risk. | `realpath`/`lstat` checks refuse symlink components and keep operations below `root`. A malicious or changing server can still create a race between validation and use. | Preferred. Pin a fingerprint verified out of band. |
| **FTPS** | Encrypted when certificate verification succeeds. `insecureTLS: true` also requires `allowInsecure: true` and disables MITM protection. | A client-side sub-root cannot be a reliable anti-symlink jail. `root` other than `/` is refused unless `allowUnsafeRemoteRoot: true`. | Use a dedicated, server-side chrooted account whose visible root is `/`. |
| **FTP** | Plaintext. Refused unless `allowInsecure: true` accepts interception and credential exposure. | Same limitation as FTPS: the real boundary is the server account/chroot, not lexical client path checks. | Legacy-only, on a trusted network, with a dedicated chrooted account. |

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.
- 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 <path>`
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](./ftp-servers.example.json).

```jsonc
{
  "defaultServer": "prod",
  "stateDir": "/home/alice/.local/state/ftp-deploy-mcp",
  "requirePlan": true,
  "servers": {
    "prod": {
      "protocol": "sftp",
      "host": "ssh.example.