ftp-deploy-mcp

ftp-deploy-mcp is an MCP (Model Context Protocol) server that provides AI coding agents with file deployment, inspection, and transfer capabilities for FTP, FTPS, and SFTP servers. It is positioned as the "deployment button for AI coding agents," enabling Claude Code, Claude Desktop, Cursor, Windsurf, Trae, Antigravity, or any MCP client to list, read, upload, download, and deploy files to the user's own servers.

In terms of purpose, it targets scenarios that require securely operating on remote files from AI coding agents, providing a focused set of MCP tools for server discovery, testing, directory listing, file reading, uploading, recursive deployment, downloading, directory creation, renaming, and deletion. All remote path parameters are relative to the configured remote root, and the server parameter is optional when defaultServer is set or when there is only one server.

Main capabilities include:

• Multi-server configuration: define multiple named servers in a single local configuration file.
• Recursive deployment: supports gitignore-like deployment exclusion rules, dry-run previews, and per-server readOnly mode.
• Local restrictions: limit the range of local files accessible to the MCP server via localRoot, which applies to ftp_upload, ftp_deploy, and ftp_download.
• Verified staged promotion: uploads and deployments first write to an unpredictable sibling temporary file, verify the actual byte count and SHA256, and then promote it via a single rename; verification or rename failure will not trigger deletion of the final target or a direct overwrite fallback. Downloads first verify an exclusive local temporary file, sync and close it, and then promote it. The default overwrite:false uses hard links to avoid overwriting files that appear midway; file systems that do not support hard links will fail closed.
• SFTP host key pinning: pin the host key via hostKeySha256, and support an array form during controlled rotation; reject symlink components.
• Credential protection: credentials are loaded locally from configuration, environment variables, or SSH keys, and are not proactively returned to the model; tool responses do not contain credential text.
• FileZilla import, interactive setup wizard, and read-only doctor command.
• Progress notifications: only send progress when the caller provides a progress token,incrementing the count, without including paths or credential text.
• Response compatibility and pagination: ftp_list returns a single page of results, including pagination fields such as total, count, offset, limit, has_more, and next_offset; except for ftp_read, on success it provides an MCP outputSchema and matching structuredContent.
• Annotations: all tools publish MCP annotations describing read-only, destructive, idempotent, and open-world behavior, but annotations are only client hints, not a security boundary.

Usage: Currently it must be installed from source. The steps are: install Node.js 22 or 24 (minimum 22); run git clone https://github.com/alebgl77/ftp-deploy-mcp.git And cd ftp-deploy-mcp; run npm ci --omit=dev --ignore-scripts; run npm run setup, then edit the generated server configuration to set an absolute localRoot, replace credentials, configure SFTP host key pinning or FTP/FTPS security confirmation; restart the MCP client and try a dry run. On Windows you can run install.cmd, and on macOS/Linux you can run ./install.sh instead of steps 3–4. Each generated server entry should be checked before connecting. Regarding configuration, the explicit configuration path priority is: --config <path> first, followed by FTP_MCP_CONFIG; if the explicit configuration is empty, missing, unreadable, or invalid, an error is reported and it does not fall back to other files. When there is no selector, the first configuration found is taken in order: ./ftp-servers.json, ~/.ftp-mcp/servers.json. Teaching examples include comments, but real configuration files must be strict JSON, and you can start from ftp-servers.example.json. Any string can contain ${ENV:VARIABLE_NAME}, and a missing variable produces a named configuration error. Regarding client integration, npm run setup detects supported clients, creates a timestamped backup before modifying an existing client configuration, and prints a configuration block for UI-only clients. For manual integration, replace the path in the command with the absolute path of this checkout. Common locations include Claude Code's .mcp.json, Cursor's ~/.cursor/mcp.json, and Windsurf's ~/.codeium/windsurf/mcp_config.json. Note: the npm package has not yet been published, so npx -y ftp-deploy-mcp is currently unavailable; the official MCP Registry publication status is pending, and registry-based installation methods are not yet available. GitHub source releases are separate from npm and official MCP Registry releases.

Use cases: Suitable for AI coding agents that need to deploy build artifacts, static assets, or configuration files to their own FTP, FTPS, or SFTP servers during development or operations; need controlled recursive deployment and exclusion rules; need read-onlyInspect remote server contents; situations requiring locally restricting the range of accessible files; and situations requiring SFTP host key verification and multi-server management.

Limits and security:

• The strongest boundary for FTP/FTPS is the server's own account isolation or chroot; client-side normalization can reject obvious traversal, but FTP lacks portable REALPATH/LSTAT primitives and cannot prove that server-side symbolic links stay within the configured subroot.
• SFTP verifies host pinning and rejects symbolic link components, but an attacker-controlled server may still change filesystem state between the check and the operation.
• readOnly reduces accidental writes through this MCP server, but cannot replace read-only credentials enforced by the remote server.
• FTP, insecureTLS, allowUnknownHostKey, and allowUnsafeRemoteRoot are explicit risk acceptances, not security features.
• Default deployment excludes content containing node_modules, .git, environment files, logs, operating system metadata, ftp-servers.json, and .ftp-mcp at any depth; retained .ftp-mcp-*.tmp basenames are always excluded.
• Within the same Node process, uploads, deployments, mkdir, renames, and deletions for the same normalized protocol, hostname, port, and username execute in FIFO order; the lock does not coordinate with other Node processes, DNS aliases, other accounts, or external clients on the same host.
• ftp_deploy is not transactional: if one or more transfers fail, the tool returns an MCP error with a partial deployment summary, and files already promoted are not rolled back.
• The process accepts at most 64 tool calls; beyond that it returns CAPACITY_LIMIT.
• Internal preparation is single-use and limited to 10 seconds, and does not extend the overall operation deadline.
• No telemetry.
• The repository test suite uses local FTP and SFTP servers and does not require an external network.

Migration notes (v0.1 to v0.2): add an absolute localRoot for each server used by upload, deploy, and download; add an out-of-band verified hostKeySha256 for each SFTP server, with allowUnknownHostKey:true only as a temporary explicit risk acceptance, and do not configure both at the same time; FTP/FTPS Prefer a dedicated server-side chroot, with the visible root as / and root set to /; non-root client paths now require allowUnsafeRemoteRoot:true and are still unsafe with respect to server-side symbolic links; treat a failed ftp_deploy as a partial deployment, and before retrying, inspect the summary and reconcile the remote tree; rerun npm run setup or update the MCP client command, then run npm run doctor and a dry run.