# CrossFTP Commander MCP

**CrossFTP Commander MCP** is a [Model Context Protocol](https://modelcontextprotocol.io) server built on the same engine as [CrossFTP Commander](commander.md). It lets AI clients such as Cursor call CrossFTP tools over stdio to validate and run uploads, deletes, and syncs — without putting passwords in tool arguments.

MCP is a component of CrossFTP Enterprise. With an Enterprise (or Site / Eval Enterprise) license on your machine, you can use CrossFTP GUI, Commander CLI, or Commander MCP from the same portable package.

**On this page:** [What it does](#what-commander-mcp-does) · [Requirements](#requirements) · [Onboard](#onboard-in-five-steps) · [Workflow](#recommended-deploy-workflow) · [Tools](#available-tools) · [Security](#security-defaults) · [CLI vs MCP](#commander-cli-vs-mcp)

---

## What Commander MCP does

Your MCP client starts `commander-mcp` as a local stdio server. One JVM stays up for the session and exposes tools that:

- List deploy profiles and bookmark sites (no secrets)
- Validate or upload selected files under a profile
- Validate or delete remotes for removed paths
- Preview or run a full-tree sync when you explicitly need it
- Continue or abort a long-running execute after a timeout

Credentials stay in CrossFTP's bookmark store (`sites.xml`). Deploy profiles live in a workspace `crossftp-deploy.json` that maps a profile name to a site ID and optional blocklist — no passwords.

Supported protocols are the same as Commander: FTP, SFTP, FTPS, WebDav, Amazon S3, Google Storage, and related cloud protocols configured in your sites.

---

## Requirements

- **Java 17+** on the PATH (or set `JAVA_HOME`) for `commander-mcp`
- **Portable package** (`crossftp-all-bin`) that includes `commander-mcp.sh` / `commander-mcp.bat` and the `mcp/` runtime libraries
- **CrossFTP Enterprise** license registered on that machine (GUI, Commander, or MCP share the same license home)
- At least one site bookmark whose remote path is the deploy root
- An MCP-capable client (for example Cursor) that can launch a local stdio server

---

## Onboard in five steps

**Setup video:** [CrossFTP Commander MCP setup guide](https://youtu.be/fcBA-m6wR6w)

### 1. Install the portable package and Java 17+

Download the portable package, extract it, and confirm Java 17+ is available. On Windows use `commander-mcp.bat`; on Mac/Linux make the script executable and use `commander-mcp.sh`.

```bash
chmod +x ./commander-mcp.sh
java -version
```

Register your Enterprise license in CrossFTP GUI (*Help → Register*) or with Commander's `registerLicense` action if you have not already.

### 2. Create or pick a site bookmark

MCP does not add sites or edit passwords. Create the site in CrossFTP Site Manager or with Commander `addSite`, then copy the site ID.

Set the bookmark's remote path to the directory that should receive deploys. Prefer overwrite rules (not Ask) for headless transfers.

If your bookmarks use a **custom** master password, set this environment variable for the MCP process only (never put it in tool args or deploy JSON):

```bash
CROSSFTP_BOOKMARKS_MASTER_PASSWORD=your-master-password
```

### 3. Add `crossftp-deploy.json` in the website root

Place `crossftp-deploy.json` in the folder you want to deploy from (the website root). Paths the agent uploads are relative to that folder. A starter file ships as `crossftp-deploy.example.json` in the portable package:

```json
{
  "version": 1,
  "profiles": {
    "website-prod": {
      "description": "Website → production",
      "site_id": "change-to-your-website-id",
      "blocklist_globs": ["**/vendor/**", "**/.env"]
    }
  }
}
```

Replace `site_id` with your site ID. Optional `blocklist_globs` are merged with built-in skips (for example `**/.env`, `**/.git/**`, key material).

Pass this file to MCP with `--deployConfig`. That path must end with `crossftp-deploy.json`; its parent directory becomes the workspace website root.

### 4. Register the server in your MCP client

Example Cursor `mcp.json` entry (adjust the absolute path to your portable package):

```json
{
  "mcpServers": {
    "crossftp-commander": {
      "command": "D:/CrossFTP/commander-mcp.bat",
      "args": [
        "--deployConfig",
        "${workspaceFolder}/crossftp-deploy.json"
      ]
    }
  }
}
```

On Mac/Linux, point `command` at `commander-mcp.sh` instead. Optional flags and env:

- `--configDir` — absolute CrossFTP config home (default `~/.crossftp`)
- `CROSSFTP_CONFIG_DIR` / `CROSSFTP_MCP_DEPLOY_CONFIG` — same as the CLI flags when set in the environment
- `CROSSFTP_BOOKMARKS_MASTER_PASSWORD` — only when using a custom bookmark master password

Custom master password example:

```json
"env": {
  "CROSSFTP_BOOKMARKS_MASTER_PASSWORD": "…"
}
```

Restart or reload MCP servers in the client after saving the config.

### 5. Verify the connection

From the client, call `commander_show_info`. You should see product, license (`enterprise_capable`), runtime, config paths, and a deploy summary. Then call `commander_list_profiles` and `commander_list_sites` to confirm the profile's `site_id` matches a site.

---

## Recommended deploy workflow

1. Let the agent gather changed paths locally (for example `git diff --name-only`). MCP does not run git.
2. Call `commander_upload_files` or `commander_delete_files` with `dry_run: true` (default) to validate paths and remotes.
3. Review the preview. Confirm deletes carefully (each remote path).
4. Call the same tool again with `dry_run: false` to execute.
5. Use `commander_sync` only for an explicit full-tree realign — not for routine git deploys. Sync never deletes remotes missing locally (`deleteUnnessary` stays false); use delete for removals.

If execute times out, the transfer may still be running. Use `commander_control_task` with `continue` or `abort` and the returned `task_id`.

---

## Available tools

| Tool | Purpose |
|------|---------|
| `commander_show_info` | Product, license, runtime, paths, deploy summary |
| `commander_list_profiles` | Profiles from `crossftp-deploy.json` |
| `commander_list_sites` / `commander_get_site` | Site IDs and non-secret metadata |
| `commander_update_site` | Update non-secret fields (`remote_root`, `host`, `port`, `username`) |
| `commander_upload_files` | Validate or upload `files[]` under a profile |
| `commander_delete_files` | Validate or delete remotes for removed paths |
| `commander_sync` | Preview or run full workspace → remote root sync |
| `commander_control_task` | After `task_timeout`: continue waiting or abort |

Tool responses are JSON. Validate mode returns a preview; execute mode adds transfer status and logs. Passwords and file contents are never returned.

---

## Security defaults

- No credentials in tool arguments or MCP responses
- Paths must stay relative to the website root that contains `crossftp-deploy.json`
- Server-enforced blocklist plus profile `blocklist_globs`
- Default `dry_run: true` — validate before execute
- Stdio transport only; audit lines go under the CrossFTP config home (`mcp/mcp-audit-*.log`)

---

## Commander CLI vs MCP

Both share the same JAR and transfer engine. Use [Commander CLI](commander.md) for scripts, schedulers, and full site CRUD (including passwords). Use MCP when an AI client should drive validate-then-deploy from a workspace profile.
