接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y [email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
FTP_MCP_CONFIG=<value> FTP_MCP_LANG=<value> claude mcp add io.github.alebgl77-ftp-deploy-mcp -- npx -y ftp-deploy-mcp@0.3.2在終端機中執行。
{ "mcpServers": { "io.github.alebgl77-ftp-deploy-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "FTP_MCP_CONFIG": "<value>", "FTP_MCP_LANG": "<value>" } } }}claude_desktop_config.json
遠端 URL 還是本機指令？ 兩種安裝方式的差異
來自發布者
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.
FTP/FTPS/SFTP deployment · Déploiement FTP/FTPS/SFTP. Local confinement / Confinement local.
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 [email protected]for that version. The GitHub release is a separate source distribution;maincan 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.
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.
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.
git clone https://github.com/alebgl77/ftp-deploy-mcp.git, then
cd ftp-deploy-mcp.npm ci --omit=dev --ignore-scripts.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.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.
All three protocols also enforce localRoot for ftp_upload, ftp_deploy,
and ftp_download. This limits which local files the MCP server can access.
stateDir is configured;
confirmation and rollback follow the documented bounds.readOnly mode.doctor
command.An explicit configuration path is authoritative:
--config <path>FTP_MCP_CONFIG, when --config is absentAn 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:
./ftp-servers.json~/.ftp-mcp/servers.jsonThe 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.
Any string can contain ${ENV:VARIABLE_NAME}. Missing variables produce a
named configuration error.
Do not trust a fingerprint obtained only through the connection you are about to verify.
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub -E sha256.SHA256:... value before putting it in
hostKeySha256. ssh-keyscan may collect a candidate key, but by itself it
does not authenticate that key.For rotation, verify the new fingerprint out of band, temporarily configure
both old and new pins, rotate the server key, confirm connections use the
expected key, then remove the old pin. Do not use allowUnknownHostKey as a
rotation shortcut.
All remote path arguments are relative to the configured remote root. The
server parameter is optional when defaultServer is set or only one server
exists.
The durable tools require the official MCP input_required confirmation flow;
there is no boolean fallback. Signed request state binds the session, method,
plan digest, operation, idempotency-key hash, resume choice, journal sequence,
and expiry. Declined, invalid, expired, or unsupported interaction has no remote
effect. Association alone is status-only; any nonterminal remote mutation
requires resume:true.
The guarantee level is observable_state_reconciled: per-file replacement is
server-dependent, multi-file atomicity and exactly-once execution are false,
and rollback covers only durably acknowledged files. SFTP supports replacement
plus new files under existing canonical parents; FTP/FTPS supports replacement
of existing regular files only. Durable execution never creates parents, purges
remote extras, automatically rolls back, or rolls back SATISFIED_UNOWNED.
Cooperating processes sharing one canonical stateDir serialize the exact
server alias before adapter construction. This is not a distributed remote lock
and does not coordinate different aliases or state directories. Overlapping
writable aliases, alias renames, mixed-binary upgrades, and a process killed
while holding a persistent lock require operator care: quiesce upgrades and
recover stale locks offline. External writers and ABA changes remain outside
the observable identity guarantee.
Uploads and deploys write to an unpredictable sibling temporary, verify its
actual byte count and SHA256 against the local source, then promote it with one
rename. A verification or rename failure never triggers deletion of the final
target or a direct-overwrite fallback. Downloads verify an exclusive local
temporary, synchronize and close it, then promote the complete file. The
default overwrite:false uses a hard link to avoid clobbering a file that
appeared meanwhile; filesystems without hard-link support fail closed.
Local and SFTP replacements preserve an existing regular target's permission bits (0777); FTP/FTPS cannot portably preserve permissions, so account creation defaults, umask and ACL policy need to suit the destination. Rename behavior depends on the server and filesystem. Legacy upload/deploy does not promise universal atomic replacement, a site transaction, or rollback. Readback adds network traffic. See transfer guarantees, limits and cleanup.
Within one Node process, upload, deploy, mkdir, rename, and delete run in FIFO order for the same normalized protocol, hostname, port, and username. Server aliases and roots share that lock. Downloads serialize by canonical local destination, including across servers. Read-only remote operations can overlap.
MCP cancellation and deadlines close active transports and stop subsequent
deploy files. Errors identify CANCELLED or TIMEOUT; TARGET_BUSY indicates
waiting for another operation. A timed-out call can return before an underlying
operation settles, but its lock remains owned until settlement and cleanup.
No uncertain mutation is retried automatically. Inspect partial remote/local
state before retrying; legacy mutation calls are not transactional deployment
and provide no rollback.
Internal preparation is single-use and limited to 10 seconds without extending the overall operation deadline. Admission remains held until the actual work and cleanup settle. A prepared context is released once, including when it arrives after cancellation; the handler is not called after preparation is cancelled or expires. Preparation callbacks themselves may act. Durable tools use the same settlement discipline. See the resource limits.
Progress notifications are sent only when the caller supplies a progress token, with increasing counters and no paths or credential text. Locks do not coordinate other Node processes, DNS aliases, other accounts, or external clients on the same host.
ftp_list returns one page instead of an unbounded directory listing. Its
successful response includes total, count, offset, limit, has_more,
and next_offset pagination fields. For example, a request with
{"server":"prod","path":"/assets","limit":2,"offset":2} may include the
following intentionally non-exhaustive excerpt. It omits the required
top-level server, path, and security_warning fields and the required
per-entry size_bytes and modified_at fields:
{
"structuredContent": {
"entries": [
{ "name": "app.css", "type": "file" },
{ "name": "app.js", "type": "file" }
],
"total": 6,
"count": 2,
"offset": 2,
"limit": 2,
"has_more": true,
"next_offset": 4
}
}
The existing human-readable content text is retained for compatibility.
On success, every tool except ftp_read also advertises an MCP
outputSchema and returns matching structuredContent; ftp_read remains a
bounded text-only tool on success. Each of the nine structured schemas accepts
either its strict success shape or a strict {error} envelope. Tool execution
errors return isError: true with localized text and structured code, request UUID,
effect observations and safe-retry guidance. Unknown tools remain protocol errors.
See the error contract.
The process admits at most 64 tool calls, including workers still cleaning up
after cancellation. Excess calls return CAPACITY_LIMIT. Local deployment scans
are asynchronous and separately bounded; see resource limits
for exact counting, SCAN_LIMIT and corrected custom exclusion behavior.
All tools publish MCP annotations describing read-only, destructive,
idempotent, and open-world behavior. These annotations are client hints, not a
security boundary; enforce access with server credentials, readOnly,
localRoot, and the protocol controls described above. ftp_deploy structured
results contain a summary and bounded samples, not exhaustive file lists.
ftp_deploy is not a transaction. If one or more transfers fail, the tool
returns an MCP error with a partial-deployment summary; files already promoted
before the failure are not rolled back.
Default deploy exclusions include node_modules, .git, environment files,
logs, OS metadata, ftp-servers.json, and .ftp-mcp content at any depth.
The reserved .ftp-mcp-*.tmp basename is always excluded, even if an explicit
include pattern matches it, so deploy cannot select a partial download temporary.
npm run setup detects supported clients, creates timestamped backups before
changing existing client configuration, and prints a block for UI-only clients.
To wire a client manually, replace the path below with the absolute path to
this checkout:
{
"mcpServers": {
"ftp": {
"command": "node",
"args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
}
}
}
Common locations include .mcp.json for Claude Code,
~/.cursor/mcp.json for Cursor, and
~/.codeium/windsurf/mcp_config.json for Windsurf. Claude Desktop and other
clients accept the same command/arguments structure through their MCP settings.
The published npm package can instead be launched with
npx -y [email protected]. Verify the exact version before updating;
pinning it does not also freeze npm's transitive dependency resolution.
node src/index.js import-filezilla --file /path/sitemanager.xml --out ./ftp-servers.json
npm run doctor
Imported passwords may be decoded into plaintext. Keep the output outside
version control, restrict its permissions, add localRoot, and review every
insecure-transport or FTP/FTPS remote-root warning before connecting.
doctor is read-only and reports configuration and client wiring without
printing passwords.
The availability links above identify published version 0.3.2. The migration steps below describe the security changes introduced after v0.1; they do not require republishing or moving an existing release tag.
localRoot to every server used by upload, deploy, or
download.hostKeySha256. Use
allowUnknownHostKey: true only as a temporary, explicit risk acceptance;
do not configure both fields./ and set root to /. A non-root client path now requires
allowUnsafeRemoteRoot: true and remains unsafe against server-side
symlinks.ftp_deploy as a partial deployment: inspect its summary and
reconcile the remote tree before retrying.npm run setup or update the MCP client command to this checkout,
then run npm run doctor and a dry run.Atomic replacement for newly written sensitive configuration is checked by the release tests; a version number alone does not establish that guarantee. See docs/RELEASE.md for the qualification and publication steps.
REALPATH/LSTAT primitives and cannot prove that a server-side
symlink stays inside a configured sub-root.realpath/lstat. A server controlled by an attacker can still change
filesystem state between checks and operations.readOnly reduces accidental writes through this MCP server; it is not a
substitute for read-only credentials enforced by the remote server.insecureTLS, allowUnknownHostKey, and
allowUnsafeRemoteRoot are explicit risk acceptances, not security features.Read the full security model and private disclosure policy.
npm test
npm run eval:scripted
node src/index.js --version
node src/index.js --help
The test suite uses local FTP and SFTP servers and does not require an external network. Contributions are welcome; see CONTRIBUTING.md. Maintainers should use the release guide. A reproducible, externally hosted read-only agent evaluation is documented in evaluations/README.md.
From a source checkout, npm run eval:scripted runs 43 cases in both languages
through the real SDK client and handlers, with an in-memory remote adapter:
86 scripted server-conformance results. See the
scripted conformance guide for reports and limits;
this command does not evaluate a model or replace the separate real-transport tests.
MIT — see LICENSE.
Built and maintained by Alexandre Beguel, Agentic AI Architect and external CAIO based in Paris. He works on production GenAI, LLMOps, LLM FinOps and evidence-first AI governance. beguel.com · LinkedIn · Profile in English, French and Spanish
FTP/FTPS/SFTP deployment · Déploiement FTP/FTPS/SFTP. Local confinement / Confinement local.
{ "mcpServers": { "io.github.alebgl77-ftp-deploy-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "FTP_MCP_CONFIG": "<value>", "FTP_MCP_LANG": "<value>" } } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式，而不是 PlugMCP 代理伺服器。
發布者列出了以下環境變數：FTP_MCP_CONFIG, FTP_MCP_LANG。
Ftp Deploy 透過 stdio 在本機執行。
上次檢查時間：2026-11-09。 FTP/FTPS/SFTP deployment · Déploiement FTP/FTPS/SFTP. Local confinement / Confinement local.