Ftp Ssh MCP

ftp-ssh-mcp

An MCP server for working with a single remote host over FTP, FTPS, SFTP, and SSH — the kind of host a typical shared-hosting plan or a plain VPS gives you, not a cloud provider's API. It groups its tools into three capability classes: file transfer (list, upload, download, mkdir, delete), shell execution over SSH, and a MySQL query wrapper that also runs over SSH. File transfer is the only capability enabled by default — shell execution and database access are both opt-in and stay off until you explicitly turn them on. Treat those two as equally dangerous: mysql_query runs arbitrary SQL on a production database and can escape to a shell, so it is not the milder of the pair.

Install

Published to npm and run with npx — there is nothing to clone or build. Requires Node 20 or newer. Works on Windows, macOS and Linux.

1. Add it to your MCP client

On Windows, use the `cmd /c` form shown for each client below. Most clients spawn command directly rather than through a shell, and npx on Windows is a .cmd shim that cannot be executed that way — the server simply fails to start, usually with no useful error. Treat this as the rule on Windows, not an edge case.

Claude Code — .mcp.json in the project root

{

"mcpServers": { "remote": { "command": "npx", "args": ["-y", "ftp-ssh-mcp@1"] } } }

Windows:

{

"mcpServers": { "remote": { "command": "cmd", "args": ["/c", "npx", "-y", "ftp-ssh-mcp@1"] } } }

Claude Desktop — claude_desktop_config.json

Same mcpServers shape as Claude Code. Claude Desktop has no project directory, so set MCP_ENV_FILE to an absolute path — see step 2.

Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

Same mcpServers shape as Claude Code.

VS Code — .vscode/mcp.json (workspace), or MCP: Open User Configuration for global

VS Code uses servers, not mcpServers:

{

"servers": { "remote": { "command": "npx", "args": ["-y", "ftp-ssh-mcp@1"] } } }

Codex CLI — ~/.codex/config.toml , or .codex/config.toml in a trusted project

Codex uses TOML with a snake_case mcp_servers table:

[mcp_servers.remote]

command = "npx" args = ["-y", "ftp-ssh-mcp@1"]

Windows:

[mcp_servers.remote]

command = "cmd" args = ["/c", "npx", "-y", "ftp-ssh-mcp@1"]

Or add it from the shell: codex mcp add remote -- npx -y ftp-ssh-mcp@1

2. Point it at a host

Create a .env file in your project root. The server reads it from the working directory, which is the project root for project-scoped clients:

REMOTE_HOST=ftp.example.com

REMOTE_USER=deploy REMOTE_PASSWORD=your-password REMOTE_BASE_DIR=/home/deploy/public_html

That is enough for the six file tools over FTPS. Keep this file out of version control — add .env and .env.* to .gitignore. Getting credentials out of a tracked config file is the reason the server reads .env at all.

If your client has no project directory (Claude Desktop), or you want several servers against different accounts, point each at its own file instead:

{

"mcpServers": { "prod": { "command": "npx", "args": ["-y", "ftp-ssh-mcp@1"], "env": { "MCP_ENV_FILE": "/absolute/path/to/.env.prod" } } } }

A fuller setup, adding shell execution and database access — both off unless you opt in:

REMOTE_HOST=example.com

REMOTE_USER=deploy REMOTE_PASSWORD=your-password REMOTE_BASE_DIR=/home/deploy/public_html

Pin the host key. Without this, any host key is accepted — see Security.

SSH_HOST_FINGERPRINT=SHA256:your-fingerprint-here SSH_PORT=22 SSH_BASE_DIR=/home/deploy SSH_ALLOW_EXEC=true SSH_ALLOWED_CMDS=@basic,@node

Runs the mysql client on the host over SSH. At least as dangerous as

SSH_ALLOW_EXEC — read the Security section before enabling.

DB_USER=deploy_dbuser DB_PASSWORD=your-db-password DB_NAME=deploy_db

Off by default; required for file_delete.

REMOTE_ALLOW_DELETE=true

See .env.example for every variable and Configuration below for what each does.

3. Check it before you rely on it

npx -y ftp-ssh-mcp@1 --selftest

Run it from the directory holding your .env. It resolves configuration, registers tools and prints a one-line summary — without opening a connection — then exits. Use it to confirm the right capabilities came up before wiring the server into a client:

ftp-ssh-mcp 1.0.1 selftest OK. env=.env, transport=ftp, host=example.com,

capabilities=[files, ssh, mysql], tools=[file_list, file_upload, ...]

It exits non-zero with a message naming the missing variable if configuration is incomplete. See Troubleshooting.

Options

--version and --help answer before any configuration is read, so they work on a machine with nothing set up yet. Both print to stdout; everything else the server says goes to stderr, because stdout is the JSON-RPC channel.

--quiet silences the warnings about a missing DB_PASSWORD, an MCP_CAPABILITIES entry that registered no tools, and a relative base directory. It deliberately does not silence the two that say your security posture is weaker than you might assume — an unverified host key, or path confinement switched off. A flag set once in a client's config file is never looked at again, so those stay visible until you fix them, which is the only silence worth having.

Capabilities

A capability's tools are only registered when it is both configured (its required variables are set) and, if MCP_CAPABILITIES restricts the set, named in that list.

The files tools are transport-neutral: they work over whichever transport FILE_TRANSPORT selects (ftp or sftp), and each call can override the transport for that one call if both profiles are configured. mysql_query is a convenience wrapper, not a database driver — it pipes SQL over SSH to the mysql client already installed on the host (mysql --user=... --database=... --table, with the SQL sent on stdin), then parses the CLI's table output. There is no connection pooling and no parameterised-query support. It exists because most shared hosts will not accept a database connection from outside the host itself; if you need a real client-side database integration, use one instead of mysql_query. Enable it with the same caution as `ssh_exec`, not less — see Security.

Configuration

Every setting is resolved from environment variables in this order: a profile-specific variable (FTP_* or SSH_*) first, then the shared REMOTE_* fallback, then a built-in default. Two independent profiles exist — FTP and SSH — and you may configure either, both, or neither in isolation (though at least one is required to start).

Variables are normally read from process environment, but the server also loads a .env file from the current working directory before resolving configuration, so credentials can live outside the MCP client's own (often tracked) config file. A real environment variable already set takes precedence over the .env file. Point at a different file with MCP_ENV_FILE — a leading ~ is expanded to your home directory, a relative value is resolved against the working directory, and a set-but-unreadable one fails startup rather than silently falling back to .env and loading different credentials than the ones you named. The `.env` parser does not support inline comments — KEY=value # note treats everything after = as the value, including # note, so keep comments on their own line.

Secret inheritance

Non-secret settings (HOST, USER, BASE_DIR) fall back to REMOTE_* freely. Secrets (PASSWORD, PRIVATE_KEY, PASSPHRASE) fall back to REMOTE_PASSWORD **only when the profile does not set its own *_USER**. A profile that names its own user is declaring a distinct identity, and sending that identity a password meant for a different account causes repeated authentication failures — on many shared hosts, enough failures trip brute-force protection and lock the account out at the host level. If FTP_USER (or SSH_USER) is set, its password must be set explicitly too.

Variables

| `SSH_BASE_DIR