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.
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.
agent2drive urlPrints 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.
"Google hasn't verified this app" → Advanced → Go to rclone (unsafe) → Allow. Expected for rclone's published public client.
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.
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.
| Command | What it does |
|---|---|
| status | live token check (AUTH_OK / AUTH_MISSING, exit 0/2) |
| url | prints the consent URL + stores a one-time state nonce |
| client | sets your own OAuth client id/secret (prompts, never prints) |
| connect | exchanges the pasted URL, writes chmod-600 config, verifies quota |
| init | creates the slot root + MANIFEST.md |
| upload | verifies size + MD5 + SHA-1, logs a manifest row; --replace to overwrite |
| ls / manifest | list files / print the delivery history |
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.
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.
A same-name upload fails by default. Pass --replace
(CLI) or confirm='REPLACE' (MCP) to overwrite deliberately.
Every verified delivery appends UTC time, filename, folder, bytes,
MD5, SHA-1 and result. Read it with agent2drive manifest <slot>.
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.
Least privilege by design; honest about what is stored where, and how to take it all back.
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.
The refresh token lives in state/rclone/rclone.conf.
state/, bin/,
.tmp/ are gitignored. No token is ever printed, logged, or committed.
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.
url issues a nonce; connect verifies and
consumes it. Replayed or expired pastes are rejected. Use
--stdin so codes never land in shell history.
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.
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.
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
| Tool | Purpose |
|---|---|
| a2d_status / a2d_connect | check auth / exchange the user's pasted redirect URL |
| a2d_set_client / a2d_consent_url | configure your own client / get the consent link |
| a2d_init_slot / a2d_upload | create a slot / upload with hash verification and manifest row |
| a2d_list / a2d_manifest | list files / read the delivery audit trail |
Full design, resources, prompt and security notes: docs/MCP.md ↗
# 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 ↗
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.
No. The drive.file scope makes everything the agent
didn't create invisible to it. Uploads land only in
GDRIVE_ROOT/<slot>[/<your-folder>].
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.
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.
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.
Under ~/.config/agent2drive/ (XDG), or
A2D_HOME if set. Nothing is written into
site-packages. Source checkouts keep state beside the code.