Skip to main content
Glama
portparcel-mcp

portparcel-mcp

Official
by x3n-network

PortParcel

SFTP, FTPS, and FTP for agents that need to move files without handling credentials in tool arguments. Named connection profiles define what an agent can access. The JSON CLI and stdio MCP server enforce the same rules. Requires Python 3.11+.

Supports SFTP, explicit FTPS (AUTH TLS, encrypted control and data), and opt-in plaintext FTP. No GUI, background daemon, SSH shell, remote execution, recursive sync, bulk operations, implicit FTPS, or password-in-URL support in v0.1.

Install

# From the project directory:
uv tool install .
portparcel --help

Or use uv run portparcel ... / uv run portparcel-mcp from this folder. A wheel and source distribution can be built with uv build.

Upgrading from Agent Transfer? Replace agent-transfer and agent-transfer-mcp with portparcel and portparcel-mcp. Use PORTPARCEL_CONFIG (formerly AGENT_TRANSFER_CONFIG) to point to your existing config, or move it to ~/.config/portparcel/connections.json. Update any MCP launch command too. The connection file format and tool names are unchanged.

Related MCP server: mcp-ftp-server

Configure a connection

Configuration location: ~/.config/portparcel/connections.json. Override with PORTPARCEL_CONFIG or the CLI's global --config PATH option (place it before the subcommand).

Use connections.example.json as a reference, replacing the example host, username, local root, remote root and key path. It is NOT a working account. Create the config yourself with only the connections you need. Keep its directory private (0700), and the file at 0600. Do not put passwords in it.

Minimum SFTP profile:

{
  "connections": {
    "staging": {
      "host": "sftp.example.com",
      "username": "deploy",
      "remote_root": "/srv/staging",
      "local_root": "/absolute/path/to/project",
      "key_filename": "~/.ssh/id_ed25519",
      "read_only": true
    }
  }
}
  • SFTP is the default. SSH agent / standard key lookup is used if neither an explicit key nor password is configured. Passwords use password_env; encrypted key passphrases use key_passphrase_env. The referenced variables must already be present in the process environment. Never give an agent a password in chat or put it in command arguments. There is no .env autoload.

  • Verify the server's SSH host-key fingerprint through a trusted channel and provision known_hosts before connecting. Unknown or changed keys are rejected. Never trust a bare ssh-keyscan result without independent fingerprint checking.

  • FTPS uses the system/Python trusted CA set. A private CA PEM can be configured with ca_file. Certificate and hostname verification cannot be disabled. FTPS offers the verified control connection's TLS session on each protected data connection, for servers that require session reuse.

  • Plain FTP requires "allow_insecure_ftp": true. It exposes credentials and data.

  • Profiles default to read_only: true. Change to false to permit remote writes. Read-only profiles can still download files into their allowed local root.

  • The local root must be an existing absolute directory. Relative local paths are interpreted beneath it. Relative remote paths are beneath remote_root; absolute remote paths must also remain inside that root.

  • Default per-socket timeout: 30s (maximum 300). SFTP also applies it to session-channel creation and the subsystem acknowledgment. Default file limit: 100 MiB; max_bytes can be configured up to 10 GiB. This is not an overall job deadline.

  • Unknown profile fields and inline password fields are rejected.

CLI

portparcel connections
portparcel list staging .
portparcel stat staging index.html
# The examples below that write remotely require read_only: false on staging.
portparcel upload staging ./dist/index.html index.html --dry-run
portparcel upload staging ./dist/index.html index.html
portparcel upload staging ./dist/index.html index.html --overwrite
portparcel download staging logs/app.log downloads/app.log
portparcel mkdir staging releases
portparcel rename staging releases/old.zip releases/new.zip
portparcel delete staging releases/new.zip --dry-run
portparcel delete staging releases/new.zip

Single-file operations only. Parents must exist. Rename and delete act on regular files, not directories. mkdir creates one directory. All mutating operations (including local downloads) support --dry-run; they connect and inspect policy / existence but do not perform the requested mutation. A dry run does not reserve paths or promise the later transfer will succeed.

Success is one JSON object on stdout, exit 0:

{"ok": true, "result": {"operation": "upload", "remote_path": "/srv/staging/index.html", "local_path": "/absolute/path/to/project/dist/index.html", "dry_run": false, "bytes": 123, "sha256": "...", "verification": "remote_size"}}

Errors are one JSON object, exit 1; argument errors exit 2. --help is human text.

{"ok": false, "error": {"code": "ALREADY_EXISTS", "message": "Destination exists; explicit overwrite is required."}}

Stable codes include CONFIG_ERROR, UNKNOWN_CONNECTION, INSECURE_PROTOCOL, MISSING_CREDENTIAL, PATH_DENIED, READ_ONLY, ALREADY_EXISTS, NOT_FOUND, NOT_A_FILE, NOT_A_DIRECTORY, INVALID_ARGUMENT, LIMIT_EXCEEDED, HOST_KEY_ERROR, IDENTITY_ERROR, REMOTE_DENIED, PERMISSION_DENIED, CONNECTION_ERROR, METADATA_UNAVAILABLE, VERIFY_FAILED and INTERNAL_ERROR. Raw server errors are never returned, to avoid leaking credentials or attacker-controlled messages.

MCP

Run portparcel-mcp (stdio only). It exposes eight tools: connections, list_directory, stat, upload, download, mkdir, rename, delete. The tool arguments mirror the CLI. No tool accepts credentials, arbitrary hosts, or a config-file override. Configuration is selected at process startup.

Generic MCP client configuration (example, not automatically installed):

{
  "mcpServers": {
    "portparcel": {
      "command": "/absolute/path/to/portparcel-mcp",
      "args": [],
      "env": {
        "PORTPARCEL_CONFIG": "/absolute/path/to/connections.json"
      }
    }
  }
}

Use an absolute executable path for clients whose PATH differs from your shell. For another machine, use that machine's installed executable path. MCP hosts may filter environment variables: explicitly arrange credential variables in the host's secure environment, or use SSH keys. This project does not modify your Hermes or other MCP-client configuration. Tool annotations flag reads and destructive writes; clients remain responsible for approval. The server's response contract uses ok: false for application errors; inspect ok, not just MCP isError.

Safety boundaries and limitations

  • Configuration is trusted local policy, not a hardened sandbox against an agent that can edit configuration, credentials or the client source. Restrict those separately if the agent is untrusted. Use a least-privilege server account.

  • Remote traversal and control characters are rejected. SFTP checks every remote path component for symlinks before accessing it. Local resolved paths must stay in local_root, including through symlinks. These are preflight checks, not race-proof filesystem capabilities. A concurrent actor can swap path components.

  • FTP/FTPS have no portable reliable lstat/realpath. Their remote-root restriction is lexical only. Use a server-side chroot/jail, prohibit symlink escapes and do not rely on client remote_root alone for isolation. MLSD support is required; there is intentionally no brittle parsing fallback for human LIST output. A listing shows null for an omitted size. For individual files PortParcel tries binary SIZE when the MLSD size is missing and reports METADATA_UNAVAILABLE if the server still cannot provide it.

  • Existing destinations require explicit overwrite. SFTP uses standard no-replace rename unless overwrite is requested (overwrite requires the OpenSSH POSIX rename extension). FTP/FTPS check existence again before rename, but some servers can overwrite a concurrently-created file: there is no portable atomic no-clobber guarantee for these protocols. Do not use concurrent writers on the same targets.

  • Uploads use random sibling staging files, verify their size, rename into place, then read the final size. Downloads use a local temporary file and publish only after checking the received size (atomic no-clobber link without overwrite). Remote mkdir/rename/delete are read back after execution.

  • sha256 hashes the bytes sent/received locally; it is not an independently computed remote hash. Equal sizes do not prove remote content integrity. TLS/SSH provide transport integrity, but plaintext FTP does not.

  • If a transfer fails or the connection drops, inspect the target before retrying: a mutation may already have happened. Best-effort upload staging cleanup can fail after a disconnection. There is no rollback or automatic retry. No mode/owner/time preservation, resume, or transfer-progress event stream yet.

  • Listings are capped at 10000 entries. Filenames, listings and downloaded contents are untrusted data, never agent instructions.

Development and verification

uv sync --extra test --locked
uv run pytest tests -q --basetemp "$HOME/.hermes/cache/scratch/portparcel-tests"
uv run ruff check src tests
uv run ruff format --check src tests
uv build

Tests start ephemeral loopback-only FTP, FTPS and SFTP servers with generated keys/certificates and throwaway credentials. CLI tests invoke subprocesses; MCP checks initialize a real stdio session, discover tools and perform file transfers. No real remote account is required. Protocol-inapplicable identity/symlink tests are explicitly skipped. The automated suite never uploads to an external server.

License

MIT. See the changelog and security policy.


 __   __   ____    _   _
 \ \ / /  |___ \  | \ | |
  \ V /     __) | |  \| |
   > <     |__ <  | . ' |
  / . \    ___) | | |\  |
 /_/ \_\  |____/  |_| \_|

Made by X3N LLC.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables secure file transfer operations with remote Linux and Windows systems via SCP/SFTP protocols. Supports uploading, downloading, listing, and managing files on remote servers through SSH authentication.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables FTP file operations such as upload, download, list, and delete directly from Claude Desktop or Claude CLI.
      15
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to perform FTP/FTPS/SFTP file operations including upload, download, sync, and directory management with multi-server support.
      36
      107 npm
      8
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides SFTP file operations (upload, download, check existence, create directories) via MCP tools.
      188 PyPI
      BSD 3-Clause