ftp-ssh-mcp

# ftp-ssh-mcp

[![npm version](https://img.shields.io/npm/v/ftp-ssh-mcp.svg)](https://www.npmjs.com/package/ftp-ssh-mcp)
[![npm downloads](https://img.shields.io/npm/dm/ftp-ssh-mcp.svg)](https://www.npmjs.com/package/ftp-ssh-mcp)
[![CI](https://github.com/Chris221/ftp-ssh-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Chris221/ftp-ssh-mcp/actions/workflows/ci.yml)
[![node](https://img.shields.io/node/v/ftp-ssh-mcp.svg)](https://nodejs.org)
[![license](https://img.shields.io/npm/l/ftp-ssh-mcp.svg)](./LICENSE)

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.

<details open>
<summary><b>Claude Code</b> — <code>.mcp.json</code> in the project root</summary>

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

Windows:

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

</details>

<details>
<summary><b>Claude Desktop</b> — <code>claude_desktop_config.json</code></summary>

| OS | Path |
| --- | --- |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Linux | `~/.config/Claude/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.

</details>

<details>
<summary><b>Cursor</b> — <code>.cursor/mcp.json</code> (project) or <code>~/.cursor/mcp.json</code> (global)</summary>

Same `mcpServers` shape as Claude Code.

</details>

<details>
<summary><b>VS Code</b> — <code>.vscode/mcp.json</code> (workspace), or <b>MCP: Open User Configuration</b> for global</summary>

VS Code uses `servers`, **not** `mcpServers`:

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

</details>

<details>
<summary><b>Codex CLI</b> — <code>~/.codex/config.toml</code>, or <code>.codex/config.toml</code> in a trusted project</summary>

Codex uses TOML with a snake_case `mcp_servers` table:

```toml
[mcp_servers.remote]
command = "npx"
args = ["-y", "ftp-ssh-mcp@1"]
```

Windows:

```toml
[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`

</details>

### 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:

```json
{
  "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`](./.env.example) for every variable and Configuration below for what each does.

### 3. Check it before you rely on it

```bash
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

| Option | Does |
| --- | --- |
| `--selftest` | Resolve the configuration, print the tools it would register, and exit. Opens no connection. |
| `-q`, `--quiet` | Drop the informational startup warnings. |
| `-v`, `--version` | Print the version and exit. |
| `-h`, `--help` | Print usage and exit. |

`--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.

| Capability | Tools | Enabled when |
| --- | --- | --- |
| `files` | `file_list`, `file_upload`, `file_upload_dir`, `file_download`, `file_mkdir`, `file_delete` | An FTP or SSH profile is configured. `file_delete` additionally requires `REMOTE_ALLOW_DELETE=true`; all writes require `REMOTE_READONLY` to be unset or `false`. |
| `ssh` | `ssh_exec` | An SSH profile is configured with `SSH_BASE_DIR` set and `SSH_ALLOW_EXEC=true`. |
| `mysql` | `mysql_query` | An SSH profile is configured, and `DB_USER` and `DB_NAME` are both set. `DB_USER` must be set explicitly — it does not inherit `REMOTE_USER` — so the capability cannot switch itself on. Blocked entirely by `REMOTE_READONLY=true`. `DB_PASSWORD` is not required — see below. |

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 tha