ftp-mcp

An enterprise-grade Model Context Protocol (MCP) server providing sophisticated FTP and SFTP operations optimized specifically for AI coding assistants. Features smart synchronization, connection pooling, directory caching, unified diff patching, and comprehensive security controls.

Why this exists

Your AI can:

• spin up a VPS
• install a web server
• build your entire app

…and then gets stuck trying to upload files.

So it writes a Python script.
Then forgets it exists.
Then writes it again next session.

This fixes that.

One connection. One call. Done.

Built for AI to install. Designed for AI to use.

Features

• Connection Pooling & Caching: Sustains underlying connections across tool calls and leverages strict memory caching with smart aggressive invalidation for extreme sub-15ms performance.
• AI-Optimized Tooling: Implements chunking (startLine/endLine) for huge files, cursor-paginated limit bounds for vast directories, and diff-based local file morphing native to FTP without pulling heavy files.
• Security & Authorization: Native support for SSH Key exchanges (both direct and Agent-forwarding), Pass-phrase authentication, and explicit readOnly: true config profiling to sandbox dangerous modifications.
• Smart Directory Syncing: Deep hash-and-size sync algorithms for minimal network payload deployments, complete with --dryRun toggling that logs differences back to the LLM without modifying live directories.
• Git & Node Aware: Automatically unpacks .gitignore and .ftpignore environments. Semantically evaluates package.json for smart context summarization.
• AI-Guided Initialization: A dedicated "AI-First" configuration track (--init) that provides highly verbose instruction context during setup, ensuring AI assistants absorb server capabilities and operational constraints directly into their working memory.
• Interactive Initializer: Simple scaffolding of configurations natively via the CLI for human users.
• Audit Logging: Robust instrumentation generating structured .ftp-mcp-audit.log traces on all filesystem mutations.
• Comprehensive E2E Testing: Guaranteed operational functionality validated continuously by Node-based MCP IO test orchestration.

Quick Start

1. Install & Initialize

Run this in your target project directory to scaffold the configuration securely:

npx ftp-mcp --init

This will run an interactive initialization wizard dropping a .ftpconfig instance natively into your working directory. Then install the package globally so your MCP client can access it universally:

npm install -g ftp-mcp

2. Configure Credentials

Option A: Project Config File (Recommended)

Your .ftpconfig can hold dozens of isolated environments.

{
  "production": {
    "host": "ftp.example.com",
    "user": "prod-user",
    "password": "your-password",
    "port": 21,
    "secure": false,
    "readOnly": true
  },
  "staging": {
    "host": "sftp://staging.example.com",
    "user": "staging-user",
    "privateKey": "./keys/id_rsa",
    "passphrase": "my-secure-key",
    "port": 22
  },
  "default": {
    "host": "ftp.mysite.com",
    "user": "default-user",
    "password": "your-password"
  }
}

The server automatically identifies .ftpconfig relative to your execution layer and falls back to environment properties.

Option B: Environment Variables

Required:

# Windows
setx FTPMCP_HOST "ftp.example.com"
setx FTPMCP_USER "username"
setx FTPMCP_PASSWORD "password"

# Linux/Mac
export FTPMCP_HOST="ftp.example.com"
export FTPMCP_USER="username"
export FTPMCP_PASSWORD="password"

Advanced SFTP Keys:

export FTPMCP_PRIVATE_KEY="/path/to/id_rsa"
export FTPMCP_PASSPHRASE="optional-phrase"
export FTPMCP_AGENT="pageant"

3. Client Integration

Register the MCP server directly to your AI Code Editor (Cursor, Cline, Claude Desktop, Windsurf, etc.).

Example integration:

• Command: npx
• Arguments: -y ftp-mcp

Advanced AI Operations

Memory Auto-Chunking

When navigating large remote codebases, AI assistants conventionally hit token-overflow limits. ftp_get_contents supports startLine and endLine parameters. ftp-mcp intercepts the inbound download stream at the bytecode layer and cleanly drops data outside your strict index bounds, returning only the exact lines requested without destroying context.

Unified Diff Patching

Instead of requesting a 5,000-line remote file, making a 2-line edit locally, and pushing the huge file back, ftp-mcp exposes an ftp_patch_file command. Simply provide a standard Unified Diff patch string, and ftp-mcp will read the live destination, map diff logic, and commit the modification directly over SCP.

Semantic Workspace Analysis

Calling ftp_analyze_workspace will traverse the remote filesystem natively investigating configurations (package.json, composer.json). It will evaluate structure patterns and package dependencies, instantly reporting exact context of the remote language mapping (e.g. "Node.js Environment operating React mapping to Express").

Native MCP Prompts

The server provides built-in prompts that guide AI agents through complex workflows:

• audit-project: Instructs the agent on how to perform a deep security and architectural audit of a remote codebase.
• deploy-checklist: Provides a standard safety checklist for agents to verify before performing production deployments or massive synchronizations.

Resource Templates (Remote File Access)

Access remote files as standard MCP resources without explicitly calling a tool:

• URI Template: mcp://remote-file/{path}
• Supports direct UTF-8 reading and respects all PolicyEngine security boundaries and path-traversal guards.

Operational Transparency

• Real-time Logging: Emits protocol-native logging notifications for internal events like connection pooling, cache reuse, and transfer lifecycle steps.
• Progress Tracking: Long-running operations (ftp_sync, ftp_batch_upload, etc.) emit granular progress updates (0-100%) so the AI agent and user can monitor large transfers in real-time.

Strict Safe-Mode Execution

Set "readOnly": true in any .ftpconfig profile. AI interactions over ftp_delete, ftp_patch_file, ftp_put_contents, or ftp_sync(direction: "upload") will immediately halt with a standardized sandbox violation, keeping production environments entirely safe from hallucinated tool executions.

Smart Sync Generation

Deploy environments utilizing deep comparison trees via ftp_sync.

• Use dryRun: true to have the system safely evaluate the entire sync matrix, printing standard output natively to the context console reporting exactly what logic would have executed.
• ftp_sync deeply integrates with standard .gitignore indexing and custom .ftpignore pattern files perfectly out-of-the-box.

Complete Tool Reference

Connection Management

• ftp_connect: Switch between named FTP profiles.

File Content Operations

• ftp_get_contents: Read file content directly from the server utilizing paginated line extraction.
• ftp_put_contents: Write content directly to a remote file.
• ftp_patch_file: Apply unified diff modifications cleanly over the network.
• ftp_summarize_file: Generates token-light structural signatures representing the files contents natively.

Metadata & File Information

• ftp_stat: Get detailed metadata regarding permissions, bytes, and modification arrays.
• ftp_exists: Conditional logic pipeline for execution paths without traversing subdirectories.
• ftp_disk_space: System OS level free-byte parsing (SFTP ONLY).
• ftp_analyze_workspace: Pull complex semantic environments based on workspace root configuration definitions.

Directory Operations

• ftp_list: List all files/directories subject to limit and offset token bounding rules.
• ftp_tree: Build full recursive maps.
• ftp_search: Target files by wildcard properties instantly down the document tree.
• ftp_mkdir / ftp_rmdir: Folder creation and complex recursive destruction commands.

File Transfer

• ftp_upload / ftp_download: Strict file 1-to-1 transports.
• ftp_batch_upload / ftp_batch_download: Multi-mapped array uploads avoiding multi-tool overhead.
• ftp_sync: Advanced deep-logic size-tree mappings dropping into deployment synchronization pools.

File Management

• ftp_delete: Drop target properties.
• ftp_copy: OS level SSH file duplications ignoring massive TCP IO transport arrays.
• ftp_rename: Target displacement mappings.
• ftp_chmod: OS level Permission flags executing bit-mask rules natively on SFTP sockets.

Architecture Guidelines

• Audit Logging is continuously enabled. Ensure the terminal running the MCP protocol maintains structural write-permissions to the local project deployment folder.
• Ensure any currentConfig caching resets are tied exclusively to ftp_connect profile pivoting.

Changelog

See CHANGELOG.md for a detailed list of changes in each release.

License

MIT

Author: Kynlo Akari