mcpdrives
Documentation menu

Documentation

The shell

drive_sh gives an agent bash over the whole drive. Each mount is a top-level folder, so the commands an agent already knows work across providers.

Example

This is real output from the service's shell, on an example drive with three mounts. The last command fails because /aws-archive is read only for this connection.

$ mounts
PATH          ACCESS                           STORAGE
/aws-archive  read                             aws
/inbox        create                           minio
/r2-media     read, create, overwrite, delete  r2
$ cp -r /aws-archive/2025 /r2-media/backup
$ ls /r2-media/backup | wc -l
12
$ grep -rl TODO /r2-media/backup | head -3
/r2-media/backup/report-01.md
/r2-media/backup/report-02.md
/r2-media/backup/report-03.md
$ echo draft > /aws-archive/new.md
mcpdrives: the command could not run: EACCES: permission denied (mount /aws-archive is read), open '/aws-archive/new.md'

Commands

The shell is an interpreter written in TypeScript, not a Linux machine. It supports pipes, redirection, globbing, variables, loops, functions and these 81 commands:

  • alias
  • awk
  • base64
  • basename
  • bash
  • cat
  • chmod
  • clear
  • column
  • comm
  • cp
  • cut
  • date
  • diff
  • dirname
  • du
  • echo
  • egrep
  • env
  • expand
  • expr
  • false
  • fgrep
  • file
  • find
  • fold
  • grep
  • gunzip
  • gzip
  • head
  • help
  • history
  • hostname
  • html-to-markdown
  • join
  • jq
  • ln
  • ls
  • md5sum
  • mkdir
  • mktemp
  • mv
  • nl
  • od
  • paste
  • printenv
  • printf
  • pwd
  • readlink
  • rev
  • rg
  • rm
  • rmdir
  • sed
  • seq
  • sh
  • sha1sum
  • sha256sum
  • sleep
  • sort
  • split
  • stat
  • strings
  • tac
  • tail
  • tee
  • time
  • timeout
  • touch
  • tr
  • tree
  • true
  • unalias
  • unexpand
  • uniq
  • wc
  • which
  • whoami
  • xargs
  • yes
  • zcat

There is no network and no other program. curl, git, python3 and node are not available; use drive_transfer links from the agent's own environment for network transfers and Code Mode for logic that bash makes awkward.

Drive commands

CommandWhat it does
mountsLists the mounts with their access and provider.
url PATHPrints a signed download link for a file.
upload-url PATHPrints a signed upload link and the headers it needs.
info PATHPrints the details of a file or folder as JSON: type, size, modified time, content type and ETag.

How files behave

  • Writes are buffered and saved when the command line finishes, one write per file. A redirect such as > /work/report.md becomes a single upload.
  • cp, mv and rm -r on folders use the same copy engine as drive_files: server-side within one storage account, streamed between providers, and continued as a background job when they run long.
  • /tmp is scratch space in memory for one command line. It is empty at the start of every call.
  • Object storage has no symbolic links or permission bits. ln -s fails with ENOTSUP, and chmod succeeds without changing anything.
  • Mount points and the drive's root cannot be deleted. rm -rf /r2-media fails, while rm -rf /r2-media/* empties the mount if the connection may delete.
  • A refused write or delete is reported on standard error and the command exits with status 1, even with rm -f.

Limits

  • A command line runs for up to 30 seconds. Long copies continue in the background after 20 seconds.
  • Up to 60,000 characters of output return to the agent; the rest is cut and marked.
  • A single file written from the shell can be up to 16 MiB, and one command line can buffer up to 64 MiB of writes. Use upload links for larger files.
  • The shell can be turned off per drive in its settings.