sftp-manager

Manage your game servers by talking to them. An MCP server that gives any AI agent safe, sandboxed SFTP access to your Minecraft / Pterodactyl / TaroHosting boxes — read configs, edit them surgically, install addons, restore backups. No shell required.

you> on the survival server, bump max players to 40

ai>  Reading the file first.
     -> leer_archivo({"ruta": "server.properties"})
     -> reemplazar_en_archivo({"ruta": "server.properties",
                               "buscar": "max-players=20",
                               "reemplazar": "max-players=40"})

     [!] This operation modifies the server. Approve? (y/N)

ai>  Done. max-players is now 40.
     Backup saved at .ai_backups/20260731-004512__server.properties
     Restart the server from your panel to apply it.

Why this exists

Game hosting panels (Pterodactyl, TaroHosting, and friends) expose SFTP only — no shell. No ssh, no unzip, no grep, no rm -rf. Editing one line of a config becomes a download / edit / re-upload round trip through a clunky web file manager, and installing a mod pack is a manual unzip-and-drag ritual across hundreds of files.

sftp-manager hands that whole workflow to an AI agent through the Model Context Protocol — with guardrails, so the agent can't wander outside your server root, and with a parallel transfer engine, so operations that take minutes over a naive SFTP client take seconds.

Related MCP server: mcp-remote-ssh

Features

• 18 MCP tools covering the full lifecycle: browse, read, search, edit, upload, install, delete, restore — plus start / stop / restart through the panel API.

• Multi-server registry — declare every box you own in one servers.json, switch with a servidor parameter.

• Host key verification — trust-on-first-use by default, strict when you want it.

• Parallel transfer engine — bulk uploads and recursive deletes are spread across multiple SSH connections. See How it works.

• Path sandbox — every path resolves against the configured root before any network call.

• Automatic backups — every overwrite and delete copies the original into .ai_backups/ on the server first, with a timestamp. Fully restorable.

• Surgical edits — reemplazar_en_archivo refuses to run when the search fragment is ambiguous, instead of guessing.

• Destructive-operation hints — write and delete tools carry MCP destructiveHint, so your client asks before executing and shows the exact arguments.

• Self-healing connections — keepalive packets plus transparent reconnect when the transport dies.

• Per-tool timeouts — no call hangs forever; on timeout the connection is recycled and a clear error is returned.

• Secrets stay out of config — passwords are written as ${ENV_VAR} and resolved from the environment at load time.

• Addon installer — .zip / .mcaddon archives are extracted locally and the resulting tree uploaded, working around the missing remote shell. Includes Zip-Slip protection.

Requirements

• Python 3.10 or newer

• An SFTP-capable host (Pterodactyl-based panels, TaroHosting, or any plain SFTP server)

Install

git clone https://github.com/Gus2708/sftp-manager.git
cd sftp-manager
pip install -r requirements.txt
cp servers.example.json servers.json

Only paramiko, python-dotenv and mcp are needed for the MCP server. anthropic is required exclusively for the optional standalone CLI.

Configure your servers

servers.json declares every server you manage. Passwords are written as ${VARIABLE} references resolved from the environment (or a .env file), so the config file itself never holds a secret and is safe to commit or share.

{
  "default": "survival",
  "servers": {
    "survival": {
      "descripcion": "Main survival server",
      "juego": "Minecraft Bedrock 26.30",
      "host": "node1.tarohosting.net",
      "port": 2022,
      "user": "abc12345.f00d",
      "password": "${TARO_SURVIVAL_PASSWORD}",
      "root": "/",
      "max_read_bytes": 200000
    },
    "creative": {
      "descripcion": "Testing and builds",
      "host": "node2.tarohosting.net",
      "port": 2022,
      "user": "abc12345.beef",
      "password": "${TARO_CREATIVE_PASSWORD}",
      "root": "/"
    }
  }
}

Then put the actual secrets in .env (git-ignored):

TARO_SURVIVAL_PASSWORD=your-panel-password
TARO_CREATIVE_PASSWORD=your-other-password

Every tool accepts an optional servidor parameter. Omit it and the one marked default is used.

Keys accepted per server

Connection and identity:

Tuning — all optional, all with sane defaults. Reach for these when a node is slow, far away, or strict about concurrent connections:

Optionally, a nested panel block enables power control (see Restarting the server):

"panel": {
  "url": "https://panel.tarohosting.net",
  "api_key": "${TARO_PANEL_API_KEY}",
  "server_id": "1a2b3c4d"
}

Every key is validated at load time: non-numeric or out-of-range values fail immediately with the server name and the offending key, rather than surfacing as a confusing network error on the first tool call. Unknown keys are rejected too, so a typo like canaless is caught at startup instead of being silently ignored.

For a Pterodactyl-style panel, the connection values live under Settings → SFTP Details. Note the username is usually panel-user.server-id, and the password is your panel password.

Single-server fallback

If servers.json doesn't exist, the server falls back to one connection read entirely from the environment, using the SFTP_* variable names in the tables above plus SFTP_HOST, SFTP_USER, SFTP_PASSWORD / SFTP_KEY_PATH and SFTP_ROOT. Defaults and validation are identical in both modes — there is exactly one source of truth for them, in SFTPConfig.

Point SFTP_SERVERS_FILE at another path to load the registry from somewhere else.

Installing the MCP server in your editor / agent

The server speaks stdio, the transport every MCP client supports. The command is always the same:

command: python
args:    ["/absolute/path/to/sftp-manager/mcp_server.py"]

On Windows, use double backslashes in JSON: "G:\\Projects\\sftp-manager\\mcp_server.py". If Python isn't on your PATH under that name, use python3 or the absolute path to your interpreter (/path/to/.venv/bin/python) — this is the single most common setup failure.

Most clients share the same mcpServers JSON shape, so this is the block to copy:

{
  "mcpServers": {
    "sftp-manager": {
      "command": "python",
      "args": ["/absolute/path/to/sftp-manager/mcp_server.py"]
    }
  }
}

Claude Code

The repo ships a project-scoped .mcp.json, so cloning and opening the folder is enough. To register it globally instead:

claude mcp add sftp-manager --scope user -- python /absolute/path/to/sftp-manager/mcp_server.py

Verify with /mcp inside a session.

Claude Desktop

Paste the standard mcpServers block into claude_desktop_config.json:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

• Linux — ~/.config/Claude/claude_desktop_config.json

Restart the app afterwards.

Cursor

Standard mcpServers block in either:

• ~/.cursor/mcp.json — available in every project

• .cursor/mcp.json — this project only

Confirm under Settings → MCP.

VS Code (GitHub Copilot agent mode)

VS Code uses a servers key instead of mcpServers. Create .vscode/mcp.json:

{
  "servers": {
    "sftp-manager": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/sftp-manager/mcp_server.py"]
    }
  }
}

Windsurf

Standard mcpServers block in ~/.codeium/windsurf/mcp_config.json.

Cline / Roo Code

Open the MCP Servers panel → Configure MCP Servers, then add the standard mcpServers block to the settings file it opens.

Zed

Zed calls them context servers. In settings.json:

{
  "context_servers": {
    "sftp-manager": {
      "source": "custom",
      "command": "python",
      "args": ["/absolute/path/to/sftp-manager/mcp_server.py"]
    }
  }
}

JetBrains IDEs (AI Assistant / Junie)

Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add, then either fill in the command and arguments, or paste the standard mcpServers JSON block.

OpenAI Codex CLI

~/.codex/config.toml uses TOML:

[mcp_servers.sftp-manager]
command = "python"
args = ["/absolute/path/to/sftp-manager/mcp_server.py"]

Gemini CLI

Standard mcpServers block in ~/.gemini/settings.json.

Anything else

Any MCP-compatible client works — point it at python mcp_server.py over stdio. To debug a connection without an editor in the way, run the official inspector:

npx @modelcontextprotocol/inspector python mcp_server.py

Once connected, the first thing to ask your agent is: "list my servers".

Tools

Tool names and parameters are in Spanish because that is the project's working language and they form the stable public API. Descriptions and schemas guide the model, so you can prompt in any language — the agent maps your request onto the right call.

Notable behaviors worth knowing:

• leer_archivo caps at 200 KB, reports truncado: true when it hits the limit, and detects binaries instead of dumping bytes into the model's context.

• buscar walks at most 6 levels deep, returns at most 40 results, skips .git, node_modules and .ai_backups, and when filtering by content only scans files under 2 MB — reporting the first matching line number.

• borrar requires recursivo: true for directories and flat-out refuses to delete the sandbox root.

• instalar_addon uploads non-.zip files as-is, and for archives extracts locally then uploads the resulting tree.

How it works

Four layers, each with one job:

mcp_server.py    stdio MCP server: schemas, timeouts, destructive hints   <- entry point
   |
tools.py         tool catalog + dispatcher (shared with standalone mode)
   |
servers.py       multi-server registry, ${ENV} expansion, connection pool
   |          \
sftp_client.py  panel.py    SFTPManager: sandbox, backups, parallel engine
                            PanelClient: power control over the panel HTTP API

mcp_server.py is async but paramiko is blocking, so every call is dispatched to a worker thread via asyncio.to_thread and wrapped in asyncio.wait_for with a per-tool budget (45 s for listar, 300 s for borrar, 900 s for instalar_addon, and so on). On timeout the connection is deliberately closed — a paramiko thread can't be killed, but killing its socket makes it abort instead of quietly consuming the channel forever.

One connection per channel, not one channel per connection

This is the non-obvious part, and it's the reason bulk operations are fast here.

SFTP has no recursive delete and no bulk upload: every single file costs a network round trip. Deleting a 2,000-file addon serially over a 120 ms link is four minutes of waiting. The obvious fix is to open several SFTP channels over the existing SSH transport.

That does not work. Pterodactyl-style panels run their own SFTP implementation which accepts exactly one channel per connection — requesting a second one doesn't error, it blocks forever. What they do accept is multiple simultaneous SSH connections.

So _canales() opens N full SSH connections (canales, default 8), and opens them concurrently, because each handshake costs ~2 s and doing ten in series would cost 20 s before any work begins. Each worker thread then owns one connection exclusively, so tasks are dealt out in fixed batches rather than pulled from a shared pool.

Extra connections are only worth their handshake above a threshold (umbral_paralelo, 25 items). Below that, everything runs on the primary connection.

Other things the engine does

• Recursive delete walks the tree level by level, listing each level in parallel, then deletes all files in parallel, then removes directories deepest-first (siblings at the same depth are independent, so those go in parallel too). A cheap one-call probe short-circuits small flat folders back to the serial path.

• Directory uploads build the complete file list before touching the network, then create parent directories shallowest-first, then push files in parallel. Empty directories are skipped entirely — some obfuscated addons ship thousands of decoy directories with no files, and creating them one by one costs minutes of network for nothing.

• A _dirs_ok set caches directories already known to exist, so uploading a deep tree doesn't re-stat() the same parents dozens of times.

• Keepalive packets every 15 s stop the transport from going zombie while idle — the symptom is nasty, since the socket still looks alive but every operation hangs until the timeout fires. On top of that, the sftp property checks transport liveness before each use and reconnects transparently.

• Pterodactyl quirks are handled explicitly: it answers a generic failure instead of ENOENT for missing paths, so those errors are translated into readable messages.

A real walkthrough: installing a Bedrock addon

This is the workflow the project was actually built for, condensed. The full operational guide lives in docs/bedrock-addons-shaders.md.

Bedrock doesn't activate a pack just because the files are on disk — it has to be registered against the world. So it's a two-step job, and the second step is a JSON edit:

1. Upload the pack — instalar_addon with remoto: "behavior_packs" (or "resource_packs"). A .mcaddon carries both a behavior and a resource pack; treat them as two separate installs.

2. Read the manifest — leer_archivo on the uploaded manifest.json and take uuid and version from the header section, never from modules. Mixing those up is the source of the classic "Pack with id not found".

3. Register it against the world — worlds/<world name>/world_behavior_packs.json. Use reemplazar_en_archivo to find the closing ] and splice the new entry in, rather than rewriting the file: that preserves every pack already installed.

4. Restart from the panel. SFTP can't do it.

Troubleshooting with the tools

What it explicitly won't do

• No remote command execution, no remote unzip. instalar_addon extracts on your machine and uploads the tree.

• No shader management. Shaders are 100% client-side (RenderDragon). There is no server-side file to upload, so if someone asks for "install a shader on the server", the correct answer is an explanation, not a folder.

Restarting the server

SFTP genuinely cannot restart anything — but Pterodactyl-based panels expose a separate HTTP API that can, and sftp-manager speaks it. Add a panel block to a server and two more tools appear: estado_servidor (read-only) and controlar_servidor (destructive).

"panel": {
  "url": "https://panel.tarohosting.net",
  "api_key": "${TARO_PANEL_API_KEY}",
  "server_id": "1a2b3c4d"
}

The API key is a client key — Account → API Credentials in the panel, not an application key. It can only touch servers belonging to the account that created it. The server_id is the short id in the panel URL, not the display name. In single-server mode the same thing is configured with PANEL_URL, PANEL_API_KEY and PANEL_SERVER_ID.

controlar_servidor takes encender, apagar, reiniciar or forzar_apagado (the last one kills the process without saving and can corrupt a world — it exists for when a normal stop hangs). The signal is asynchronous: the panel accepts it and the state changes a few seconds later, so the tool tells the model to confirm with estado_servidor rather than assuming.

Two details that matter in practice:

• The SFTP connection is never opened for these two tools. A stopped server usually refuses SFTP, and controlar_servidor is exactly what you need in that situation — opening a connection first would make it unusable precisely when it matters.

• Panel config is optional and stays optional. If you never add the block, nothing changes; the two tools return an error explaining how to enable them, and every file tool works as before. listar_servidores reports control_de_energia per server so the model knows whether it can offer a restart at all.

Host key verification

Earlier versions accepted any host key without checking (AutoAddPolicy), which left the first connection open to interception. There are now three policies, set with host_key_policy:

The default is deliberately not strict: that would break every existing setup on upgrade. If you want the strong guarantee, set strict and seed the file first:

ssh-keyscan -p 2022 node1.tarohosting.net >> ~/.ssh/known_hosts

When a key changes, the error says so explicitly rather than failing with a generic handshake message — a reinstalled node and an active MITM look identical to the client, and you should be the one deciding which it was.

Safety model

Handing an LLM write access to a live game server deserves more than good intentions.

Every row above is covered by a test — see Tests.

Standalone mode (optional)

Prefer a terminal over an MCP client? cli.py runs its own tool-use loop against the Anthropic API, with the same tools and a y/N prompt on anything destructive. It needs ANTHROPIC_API_KEY in your .env and uses the single-server environment config.

python cli.py

Commands: /salir, /reset, /backups, /ayuda.

Tests

pip install -r requirements-dev.txt
python -m pytest

126 tests, no network and no real server involved: tests/conftest.py provides an in-memory double of paramiko's SFTP client, and the panel API is exercised by intercepting urlopen. The suite runs on Linux and Windows across Python 3.10 and 3.13 in CI — Windows is there on purpose, since the client juggles local and remote path separators and that is exactly where it breaks.

What's covered:

That last file is worth calling out: the "easy to forget" steps in Adding a tool are now enforced by tests rather than by a warning in a README nobody re-reads.

Contributing

Issues and pull requests are welcome — bug reports, new tools, support for other panel APIs, translations. CI runs the suite on every pull request.

Adding a tool

1. Add the method to SFTPManager in sftp_client.py.

2. Add an entry to TOOLS in tools.py with its input_schema.

3. Wire it into build_dispatch.

4. If it modifies anything, add it to the DESTRUCTIVAS set.

5. Add an @app.tool(...) function in mcp_server.py delegating to _run("name", servidor, ...).

6. Give it a timeout budget in TIMEOUTS.

Steps 4 and 6 are easy to forget and both matter: skipping 4 means the standalone CLI won't ask for confirmation, and skipping 6 silently falls back to a 60 s budget that a bulk operation will blow through. tests/test_tools.py fails if you miss any of them, so CI catches it before a reviewer has to.

Ideas worth picking up

• Per-tool progress reporting for long uploads (MCP supports progress notifications).

• Support for panels that aren't Pterodactyl-compatible.

• Reading world_behavior_packs.json as a first-class operation instead of raw text edits.

Using OpenRouter instead of the Anthropic API

The schemas are OpenAI-compatible by renaming input_schema → parameters. Swap the client in agent.py for openai.OpenAI(base_url="https://openrouter.ai/api/v1") and adapt the loop to tool_calls / role: "tool".

Security

Never commit .env or servers.json — both are git-ignored by default. If you think you've leaked a credential, rotate the panel password immediately; deleting the file in a later commit does not remove it from git history.

Found a security issue? Open an issue describing the impact, without including credentials.

License

MIT © Gustavo Reyes