# mcp-server-ftp

An MCP (Model Context Protocol) server for FTP file operations. Browse, read, download, upload, and manage files on remote FTP servers.

Built with Rust, [rmcp](https://crates.io/crates/rmcp), and [suppaftp](https://crates.io/crates/suppaftp).

## Features

- **Multi-profile support** — configure multiple FTP servers and switch between them
- **Full file management** — list, read, download, upload, delete, rename, and create directories
- **Recursive operations** — download or upload entire directory trees
- **Binary-safe** — binary transfer mode for downloads/uploads, hex preview for non-text files via `read_file`
- **Passive/active mode** — configurable per profile
- **Connect-per-call** — each tool opens a fresh FTP connection, so there's no stale session state. Recursive operations hold one connection for the full traversal.

## Tools

| Tool | Description |
|------|-------------|
| `list_profiles` | List configured FTP server profiles (no passwords shown) |
| `list_directory` | List files/dirs at a remote path (type, size, date, name) |
| `read_file` | Read a remote file and return contents as text |
| `download_file` | Download a single remote file to a local path |
| `upload_file` | Upload a local file to a remote path |
| `download_directory` | Recursively download a remote directory |
| `upload_directory` | Recursively upload a local directory |
| `delete` | Delete a remote file or empty directory |
| `rename` | Rename or move a remote file or directory |
| `mkdir` | Create a remote directory |

All tools accept an optional `profile` parameter. When omitted, the `default_profile` from config is used.

## Configuration

Create a TOML config file at `~/.config/mcp-server-ftp/config.toml`:

```toml
default_profile = "myserver"

[[profiles]]
name = "myserver"
host = "ftp.example.com"
port = 21
username = "user"
password = "pass"
tls = false
passive = true
timeout_secs = 30
```

You can define multiple `[[profiles]]` blocks to manage several FTP servers.

### Profile fields

| Field | Default | Description |
|-------|---------|-------------|
| `name` | *(required)* | Profile name used to reference this server |
| `host` | *(required)* | FTP server hostname or IP |
| `port` | `21` | FTP port |
| `username` | `""` | FTP username |
| `password` | `""` | FTP password |
| `tls` | `false` | Enable TLS (not yet implemented) |
| `passive` | `true` | Use passive mode |
| `timeout_secs` | `30` | Connection timeout in seconds |

## Build

Requires Rust 2024 edition (1.85+).

```bash
cargo build --release
```

The binary is output to `target/release/mcp-server-ftp`.

## Usage with Claude Code

Add to your MCP server configuration:

```json
{
  "mcpServers": {
    "ftp": {
      "command": "/path/to/mcp-server-ftp"
    }
  }
}
```

Enable debug logging with the `RUST_LOG` environment variable:

```json
{
  "mcpServers": {
    "ftp": {
      "command": "/path/to/mcp-server-ftp",
      "env": {
        "RUST_LOG": "debug"
      }
    }
  }
}
```

## Project Structure

```
src/
  main.rs      — Entry point: config load, tracing init, stdio transport
  config.rs    — TOML config parsing, multi-profile support
  server.rs    — MCP tool definitions via rmcp #[tool_router]
  ftp.rs       — Async FTP client wrapper (connect, list, read, download, upload, delete, rename, mkdir)
```

## License

MIT