Skip to main content
Glama
warith-harchaoui

sftp-helper

by warith-harchaoui
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

SFTP Helper

🇫🇷 · 🇬🇧

CI License: BSD-3-Clause Python

SFTP Helper belongs to a collection of libraries called AI Helpers developped for building Artificial Intelligence

This toolbox requires:

  • a config.json for the sftp parameters (or YAML or environment variables or .env)

  • that you previously added you SSH key of your local machine in the SFTP server

🌍 AI Helpers

logo

SFTP Helper is a Python library that provides utility functions for working with SFTP servers via paramiko. Host key verification is on by default — ~/.ssh/known_hosts is loaded and unknown hosts are rejected.

Installation

Prerequisites — Python 3.10–3.13 and git, cross-platform:

  • 🍎 macOS (Homebrew): brew install python git

  • 🐧 Ubuntu/Debian: sudo apt update && sudo apt install -y python3 python3-pip git

  • 🪟 Windows (PowerShell): winget install Python.Python.3.12 Git.Git

Then install the package:

Install Package

We can recommand python environments. Check this link if you don't know how

🥸 Tech tips

pip install --force-reinstall --no-cache-dir git+https://github.com/warith-harchaoui/sftp-helper.git@v2.2.2

Or, from a checkout:

pip install -r requirements.txt
pip install -e .

Related MCP server: Local Files MCP Server

Write your own configuration file

A ready-to-fill template is committed at sftp_config.json.example. Copy it to sftp_config.json and edit in place — real *config.json files are gitignored so you cannot accidentally commit secrets:

cp sftp_config.json.example sftp_config.json
# then edit sftp_config.json with your credentials

You may also provide a YAML version (sftp_config.yaml), environment variables, or an .env file — sftp-helper falls back in that order via os_helper.get_config:

JSON

{
    "sftp_host": "<sftp_host>",
    "sftp_login": "<sftp_login>",
    "sftp_passwd": "<sftp_passwd>",
    "sftp_https": "<sftp_https>",
    "sftp_destination_path": "<sftp_destination_path>",
}

or

YAML

sftp_host: "<sftp_host>"
sftp_login: "<sftp_login>"
sftp_passwd: "<sftp_passwd>"
sftp_https: "<sftp_https>"
sftp_destination_path: "<sftp_destination_path>"

or

ENVIRONMENT VARIABLES

SFTP_HOST="<sftp_host>" \
SFTP_LOGIN="<sftp_login>" \
SFTP_PASSWD="<sftp_passwd>" \
SFTP_HTTPS="<sftp_https>" \
SFTP_DESTINATION_PATH="<sftp_destination_path>" \
python <your_python_script>

or

.env

SFTP_HOST                = <sftp_host>
SFTP_LOGIN               = <sftp_login>
SFTP_PASSWD              = <sftp_passwd>
SFTP_HTTPS               = <sftp_https>
SFTP_DESTINATION_PATH    = <sftp_destination_path>

In which you can find these information in your favorite FTP tool (mine is FileZilla):

  • <sftp_host> is the server path sftp. ...

  • <sftp_login> and <sftp_passwd> that you use in FileZilla

  • <sftp_destination_path> is the remote folder path

  • <sftp_https> corresponds to the web URL of <sftp_destination_path>

  • is your python script :)

Usage

For the full catalog of recipes (uploads, downloads, existence checks, recursive directory creation, temporary remote files with auto-cleanup, strict host-key verification), see 📋 EXAMPLES.md.

Here's an example of how to use SFTP helper (won't work without a valid path/to/sftp_config.json):

import sftp_helper as sftph
import os_helper as osh

# Write a small text file
local_file = "example.txt"
with open(local_file, "wt") as f:
    f.write("A small example of text")

# Load creds from JSON / YAML file, or fall back to .env / environment vars.
cred = sftph.credentials("path/to/sftp_config.json")

remote_file = cred["sftp_destination_path"] + "/" + local_file
url = cred["sftp_https"] + "/" + local_file

# upload() raises on failure and returns the destination URL on success.
sftph.upload(local_file, cred, remote_file)
print(f"Uploaded {local_file} to {remote_file}")
# Uploaded example.txt to /remote/base/path/example.txt

assert osh.is_working_url(url), f"URL not reachable: {url}"
print(f"URL is live: {url}")
# URL is live: https://files.example.com/example.txt

Temporary remote files

If you need a unique remote path that gets cleaned up automatically, use the remote_tempfile context manager:

import sftp_helper as sftph
import os_helper as osh

credentials = sftph.credentials("path/to/sftp_config.json")

with sftph.remote_tempfile(credentials, ext="txt") as (sftp_address, url):
    sftph.upload("local.txt", credentials, sftp_address)
    assert osh.is_working_url(url)
# On exit, the remote file is deleted.

Host key verification

sftp_helper never disables host key verification. The default policy is paramiko.RejectPolicy() and ~/.ssh/known_hosts is loaded automatically. To trust a server in a non-default location, point at an extra known_hosts file via the optional sftp_known_hosts credential.

Multi-surface exposure

sftp-helper is not just a library — the same functions are exposed as a CLI, a FastAPI HTTP surface, and an MCP tool set:

# Python library (default)
import sftp_helper as sftph

# argparse-based CLI (installed automatically)
sftp-helper upload   --config sftp_config.json --input local.txt --remote /uploads/local.txt
sftp-helper download --config sftp_config.json --remote /uploads/local.txt --output out.txt
sftp-helper exists   --config sftp_config.json --remote /uploads/local.txt
sftp-helper mkdir    --config sftp_config.json --remote /uploads/a/b/c

# click-based CLI twin (needs the [cli] extra)
pip install 'sftp-helper[cli] @ git+https://github.com/warith-harchaoui/sftp-helper.git@v2.2.2'
sftp-helper-click upload --config sftp_config.json --input local.txt --remote /uploads/local.txt

# FastAPI HTTP surface (needs the [api] extra)
pip install 'sftp-helper[api] @ git+https://github.com/warith-harchaoui/sftp-helper.git@v2.2.2'
SFTP_HELPER_CONFIG=./sftp_config.json uvicorn sftp_helper.api:app --port 8000
# → OpenAPI docs at http://localhost:8000/docs

# MCP tools over FastAPI (needs the [api,mcp] extras)
pip install 'sftp-helper[api,mcp] @ git+https://github.com/warith-harchaoui/sftp-helper.git@v2.2.2'
sftp-helper-mcp                  # serves FastAPI + MCP on port 8000

Docker image (HTTP + MCP on port 8000):

docker build -t sftp-helper .
docker run --rm -p 8000:8000 \
  -v $PWD/sftp_config.json:/app/sftp_config.json:ro \
  -e SFTP_HELPER_CONFIG=/app/sftp_config.json \
  sftp-helper

An innovative GUI plan (pipeline dashboard, storage health panel, live transfer feed) lives in GUI.md.

The competitive landscape (paramiko, pysftp, asyncssh, Fabric, smart-open, PyFilesystem2, lftp, Rclone, …) is analysed in LANDSCAPE.md.

Author

Acknowledgements

Special thanks to Mohamed Chelali and Bachir Zerroug for fruitful discussions.

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/warith-harchaoui/sftp-helper'

If you have feedback or need assistance with the MCP directory API, please join our Discord server