pip install · paste-back OAuth · drive.file scope · MCP

One command.
Your Drive.

The whole agent-to-Google-Drive dance — consent URL, the "unverified app" warning, the failing localhost redirect, the single-use code — compressed into one pip-installable command. Every upload is verified by size and hash, logged in a manifest, and reviewable in your Drive. An optional MCP server lets agents do it all with tool calls.

01

Why paste-back (and not a redirect server)

Google pins the OAuth redirect to http://127.0.0.1:53682/ — on the user's machine. The agent runs headless in a sandbox, a different machine entirely. A tunnel can't intercept it; a redirect server would be extra attack surface. So the flow goes through the one channel both humans and agents share: the chat.

STEP 1

agent2drive url

Prints a consent URL with a random one-time state nonce and the narrowest scope Google offers (drive.file). Bring your own OAuth client with client — recommended.

STEP 2

The user clicks Allow

"Google hasn't verified this app" → Advanced → Go to rclone (unsafe) → Allow. Expected for rclone's published public client.

STEP 3

Paste the address bar

The browser "fails" on 127.0.0.1 — copy that full URL (it now carries the code) and paste it back. connect --stdin exchanges it before the 10-minute expiry.

Why the browser "fails": it isn't failing — Google is redirecting to an address that only exists on the user's own machine. That failed page is the expected path; the URL in the address bar is the deliverable. The code is single-use and expires in ~10 minutes — exchange it first, before anything else.
02

Slots — where files land

Everything lives under one root folder (AgentDeliveries by default, GDRIVE_ROOT to change it), one folder per project. No structure is imposed inside it — folders exist only when you name one. Slot names are validated; traversal is rejected.

AgentDeliveries/
├── my-project/
│   ├── final/ any name you chose
│   ├── raw/ created on demand, never imposed
│   └── MANIFEST.md audit trail
└── canvas/ your review slot
CommandWhat it does
statuslive token check (AUTH_OK / AUTH_MISSING, exit 0/2)
urlprints the consent URL + stores a one-time state nonce
clientsets your own OAuth client id/secret (prompts, never prints)
connectexchanges the pasted URL, writes chmod-600 config, verifies quota
initcreates the slot root + MANIFEST.md
uploadverifies size + MD5 + SHA-1, logs a manifest row; --replace to overwrite
ls / manifestlist files / print the delivery history
03

Verified by hash, not just size

Earlier releases only compared file sizes. 0.3.0 made the promise real: Google Drive serves MD5 and SHA-1 natively, so the tool compares both against the local file, plus the byte count. A mismatch removes the remote copy and fails loudly. Nothing is written to the manifest unless verification passes.

THREE CHECKS

size · MD5 · SHA-1

verified: size True · md5 True · sha1 True → OK. If hashes can't be read, the result is SIZE-ONLY and the command exits non-zero — never a silent fake success.

OVERWRITE GATE

no silent replacements

A same-name upload fails by default. Pass --replace (CLI) or confirm='REPLACE' (MCP) to overwrite deliberately.

AUDIT TRAIL

MANIFEST.md per slot

Every verified delivery appends UTC time, filename, folder, bytes, MD5, SHA-1 and result. Read it with agent2drive manifest <slot>.

CROSS-PLATFORM

self-restoring, correctly

Missing or wrong-arch rclone is re-downloaded for linux/macOS/Windows on amd64/arm64 and checked before use. A2D_HOME keeps pip installs out of site-packages.

04

Security, plainly

Least privilege by design; honest about what is stored where, and how to take it all back.

SCOPE

drive.file only

The agent can only see and manage files it created itself. The rest of your Drive is invisible to it. Revoke any time: myaccount.google.com → Security → Third-party apps.

STORAGE

chmod 600, gitignored, never printed

The refresh token lives in state/rclone/rclone.conf. state/, bin/, .tmp/ are gitignored. No token is ever printed, logged, or committed.

CLIENT

bring your own (recommended)

rclone's published default still works as a fallback, but it is rate-limited and retiring during 2026. Use agent2drive client with your own Desktop OAuth client id + secret.

OAUTH STATE

random, one-time, 15-minute TTL

url issues a nonce; connect verifies and consumes it. Replayed or expired pastes are rejected. Use --stdin so codes never land in shell history.

RESILIENCE

self-restoring

Missing rclone → re-downloaded for your CPU. Only the refresh token is irreplaceable locally — losing it costs one fresh consent click. Nothing on Drive is ever affected.

MCP SAFETY

stdio, allowlist, redaction

No HTTP listener. A2D_ALLOWED_ROOTS restricts which local files an agent can upload, overwrites need explicit confirmation, and secrets never appear in tool results.

05

Optional MCP server

From 0.4.0, the same workflow is available as an MCP stdio server. Eight tools, two resources and a delivery prompt; in OpenCode they appear as tools.agent2drive.a2d_upload(...). Core print() output is captured into structured results so it can't corrupt the JSON-RPC stream.

# install with the MCP extra
pipx install 'agent2drive[mcp]'

# register as a local stdio server in OpenCode
opencode mcp add agent2drive -- agent2drive-mcp

# optional: restrict which local folders agents may upload from
opencode mcp add agent2drive \
  --env A2D_HOME=~/.config/agent2drive \
  --env A2D_ALLOWED_ROOTS=~/projects \
  -- agent2drive-mcp
ToolPurpose
a2d_status / a2d_connectcheck auth / exchange the user's pasted redirect URL
a2d_set_client / a2d_consent_urlconfigure your own client / get the consent link
a2d_init_slot / a2d_uploadcreate a slot / upload with hash verification and manifest row
a2d_list / a2d_manifestlist files / read the delivery audit trail

Full design, resources, prompt and security notes: docs/MCP.md ↗

06

Install & quickstart

# install (pipx recommended)
pipx install 'agent2drive[mcp]'
# or: python3 -m pip install --user 'agent2drive[mcp]'

# one-time: use your own OAuth client (recommended)
agent2drive client <client_id> <client_secret>
agent2drive url
agent2drive connect --stdin   # paste the failed 127.0.0.1 URL
agent2drive status

# create a review slot and deliver files
agent2drive init canvas
agent2drive upload canvas ./report.pdf final
agent2drive upload canvas ./notes.md
agent2drive manifest canvas

# or let an agent bootstrap the whole thing
curl -fsSL https://raw.githubusercontent.com/Bilal140202/agent2drive/main/install.sh | sh

Copy-paste agent prompt: AGENT_SETUP.md ↗

07

FAQ

Why does the browser "fail" after I click Allow?

It isn't failing. Google redirects to 127.0.0.1:53682 — an address that only exists on your machine. The failed page's URL is the code carrier: copy the whole thing from the address bar and paste it back.

Can it see my other Drive files?

No. The drive.file scope makes everything the agent didn't create invisible to it. Uploads land only in GDRIVE_ROOT/<slot>[/<your-folder>].

What does "verified" actually mean?

Local file size, MD5 and SHA-1 are compared with the uploaded copy. Drive serves both hashes natively. A mismatch deletes the remote copy and fails; unavailable hashes produce SIZE-ONLY with a non-zero exit. Hashes detect corruption, not adversarial tampering.

What happens when the sandbox is wiped?

rclone re-downloads for your CPU and the OAuth client re-derives automatically on the next command. If the refresh token is gone, you click Allow once more — your Drive contents are unaffected either way.

Windows, macOS, or ARM?

Handled automatically since 0.3.0: the correct rclone build is detected and downloaded for linux/macOS/Windows on amd64 or arm64. Override with RCLONE_ZIP for unusual platforms.

Where are tokens stored for a pip install?

Under ~/.config/agent2drive/ (XDG), or A2D_HOME if set. Nothing is written into site-packages. Source checkouts keep state beside the code.