{"id":"6a538bc7-d78c-4443-b8a8-053ad0c4e132","slug":"kynlos-ftp-mcp","kind":"mcp","name":"ftp-mcp","summary":"MCP server for FTP/SFTP — smart sync, diff patching, caching, and security controls for AI coding assistants.","owner":"Kynlos","repoUrl":"https://github.com/Kynlos/ftp-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-04-04T22:13:24.000Z","addedAt":"2026-10-14T10:58:09.974Z","logoUrl":"https://avatars.githubusercontent.com/u/76403026?u=067ffd65879ceba7096ae2f3db485d30652a0b8c&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","files-documents"],"tags":["ai","ai-tools","claude","cline","codex","cursor","dev-tools","file-sync"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T00:42:57.373Z","sample":false,"url":"https://conduits.dev/tools/kynlos-ftp-mcp","language":"JavaScript","transports":["stdio"],"install":{"npm":"ftp-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# ftp-mcp\n\nAn 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.\n\n## Why this exists\n\nYour AI can:\n- spin up a VPS\n- install a web server\n- build your entire app\n\n…and then gets stuck trying to upload files.\n\nSo it writes a Python script.  \nThen forgets it exists.  \nThen writes it again next session.\n\nThis fixes that.\n\nOne connection. One call. Done.\n\nBuilt for AI to install. Designed for AI to use.\n\n## Features\n\n- **Connection Pooling & Caching**: Sustains underlying connections across tool calls and leverages strict memory caching with smart aggressive invalidation for extreme sub-15ms performance.\n- **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.\n- **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.\n- **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.\n- **Git & Node Aware**: Automatically unpacks `.gitignore` and `.ftpignore` environments. Semantically evaluates `package.json` for smart context summarization.\n- **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.\n- **Interactive Initializer**: Simple scaffolding of configurations natively via the CLI for human users.\n- **Audit Logging**: Robust instrumentation generating structured `.ftp-mcp-audit.log` traces on all filesystem mutations.\n- **Comprehensive E2E Testing**: Guaranteed operational functionality validated continuously by Node-based MCP IO test orchestration.\n\n## Quick Start\n\n### 1. Install & Initialize\n\nRun this in your target project directory to scaffold the configuration securely:\n\n```bash\nnpx ftp-mcp --init\n```\n\nThis 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:\n\n```bash\nnpm install -g ftp-mcp\n```\n\n### 2. Configure Credentials\n\n**Option A: Project Config File (Recommended)**\n\nYour `.ftpconfig` can hold dozens of isolated environments.\n\n```json\n{\n  \"production\": {\n    \"host\": \"ftp.example.com\",\n    \"user\": \"prod-user\",\n    \"password\": \"your-password\",\n    \"port\": 21,\n    \"secure\": false,\n    \"readOnly\": true\n  },\n  \"staging\": {\n    \"host\": \"sftp://staging.example.com\",\n    \"user\": \"staging-user\",\n    \"privateKey\": \"./keys/id_rsa\",\n    \"passphrase\": \"my-secure-key\",\n    \"port\": 22\n  },\n  \"default\": {\n    \"host\": \"ftp.mysite.com\",\n    \"user\": \"default-user\",\n    \"password\": \"your-password\"\n  }\n}\n```\n\nThe server automatically identifies `.ftpconfig` relative to your execution layer and falls back to environment properties.\n\n**Option B: Environment Variables**\n\n**Required:**\n```bash\n# Windows\nsetx FTPMCP_HOST \"ftp.example.com\"\nsetx FTPMCP_USER \"username\"\nsetx FTPMCP_PASSWORD \"password\"\n\n# Linux/Mac\nexport FTPMCP_HOST=\"ftp.example.com\"\nexport FTPMCP_USER=\"username\"\nexport FTPMCP_PASSWORD=\"password\"\n```\n\n**Advanced SFTP Keys:**\n```bash\nexport FTPMCP_PRIVATE_KEY=\"/path/to/id_rsa\"\nexport FTPMCP_PASSPHRASE=\"optional-phrase\"\nexport FTPMCP_AGENT=\"pageant\"\n```\n\n### 3. Client Integration\n\nRegister the MCP server directly to your AI Code Editor (Cursor, Cline, Claude Desktop, Windsurf, etc.).\n\nExample integration:\n- **Command:** `npx`\n- **Arguments:** `-y ftp-mcp`\n\n## Advanced AI Operations\n\n### Memory Auto-Chunking\nWhen 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.\n\n### Unified Diff Patching\nInstead 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.\n\n### Semantic Workspace Analysis\nCalling `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\").\n\n### Native MCP Prompts\nThe server provides built-in prompts that guide AI agents through complex workflows:\n- **`audit-project`**: Instructs the agent on how to perform a deep security and architectural audit of a remote codebase.\n- **`deploy-checklist`**: Provides a standard safety checklist for agents to verify before performing production deployments or massive synchronizations.\n\n### Resource Templates (Remote File Access)\nAccess remote files as standard MCP resources without explicitly calling a tool:\n- **URI Template**: `mcp://remote-file/{path}`\n- Supports direct UTF-8 reading and respects all `PolicyEngine` security boundaries and path-traversal guards.\n\n### Operational Transparency\n- **Real-time Logging**: Emits protocol-native logging notifications for internal events like connection pooling, cache reuse, and transfer lifecycle steps.\n- **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.\n\n### Strict Safe-Mode Execution\nSet `\"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.\n\n### Smart Sync Generation\nDeploy environments utilizing deep comparison trees via `ftp_sync`. \n\n- 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.\n- `ftp_sync` deeply integrates with standard `.gitignore` indexing and custom `.ftpignore` pattern files perfectly out-of-the-box.\n\n## Complete Tool Reference\n\n### Connection Management\n- `ftp_connect`: Switch between named FTP profiles.\n\n### File Content Operations\n- `ftp_get_contents`: Read file content directly from the server utilizing paginated line extraction.\n- `ftp_put_contents`: Write content directly to a remote file.\n- `ftp_patch_file`: Apply unified diff modifications cleanly over the network.\n- `ftp_summarize_file`: Generates token-light structural signatures representing the files contents natively.\n\n### Metadata & File Information\n- `ftp_stat`: Get detailed metadata regarding permissions, bytes, and modification arrays.\n- `ftp_exists`: Conditional logic pipeline for execution paths without traversing subdirectories.\n- `ftp_disk_space`: System OS level free-byte parsing (SFTP ONLY).\n- `ftp_analyze_workspace`: Pull complex semantic environments based on workspace root configuration definitions.\n\n### Directory Operations\n- `ftp_list`: List all files/directories subject to `limit` and `offset` token bounding rules.\n- `ftp_tree`: Build full recursive maps.\n- `ftp_search`: Target files by wildcard properties instantly down the document tree.\n- `ftp_mkdir` / `ftp_rmdir`: Folder creation and complex recursive destruction commands.\n\n### File Transfer\n- `ftp_upload` / `ftp_download`: Strict file 1-to-1 transports.\n- `ftp_batch_upload` / `ftp_batch_download`: Multi-mapped array uploads avoiding multi-tool overhead.\n- `ftp_sync`: Advanced deep-logic size-tree mappings dropping into deployment synchronization pools.\n\n### File Management\n- `ftp_delete`: Drop target properties.\n- `ftp_copy`: OS level SSH file duplications ignoring massive TCP IO transport arrays.\n- `ftp_rename`: Target displacement mappings.\n- `ftp_chmod`: OS level Permission flags executing bit-mask rules natively on SFTP sockets.\n\n## Architecture Guidelines\n\n- Audit Logging is continuously enabled. Ensure the terminal running the MCP protocol maintains structural write-permissions to the local project deployment folder.\n- Ensure any `currentConfig` caching resets are tied exclusively to `ftp_connect` profile pivoting.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes in each release.\n\n## License\n\n[MIT](LICENSE)\n\n**Author:** [Kynlo Akari](https://github.com/Kynlos/)\n"}