io.b3os/google-drive 1.0.0 · files, documents, productivity · MIT

Find and read files in Google Drive with your own Google OAuth token: search with Drive's query language, get file metadata, export Google Docs, Sheets and Slides as plain text, Markdown or CSV, download text files, and create folders. Includes shared drives. Needs drive.readonly (or drive.file for files the app created, drive for create-folder).

Every call's result carries upstream_status and timing: validate_ms, inject_ms, render_ms, upstream_ms, map_ms and total_ms. upstream is the service's time; the others are B3OS's own (call actions). The snippets below show no timing values, because a fixture records none.

Connection

google, type oauth2: Google account (Drive).

An OAuth access token for your Google account from your own Google Cloud OAuth client, with the scopes listed here. Store the refresh_token, client_id and client_secret with it so the vault can refresh the token (access tokens last an hour); B3OS never uses a Google client of its own.

How to get one: developers.google.com.

Scopes the pack's actions use: https://www.googleapis.com/auth/drive.readonly, https://www.googleapis.com/auth/drive.file. The manifest names them per connection, not per action.

The credential is sent only to www.googleapis.com.

Store the credential once as a vault connection for this pack and key, then name its id in a call's connections. Leave the key out and B3OS uses the project's newest connection for the pack and key without a subject (connections).

Hosts it reaches: www.googleapis.com.

Actions

ActionEffectMCP toolTitle
search-filesreadgoogle-drive__search-filesSearch files
get-filereadgoogle-drive__get-fileGet file metadata
export-documentreadgoogle-drive__export-documentExport Google Doc, Sheet or Slides
download-textreadgoogle-drive__download-textDownload text file
create-folderwritegoogle-drive__create-folderCreate folder

search-files

Search files. Files and folders matching a Drive query, for example name contains 'roadmap' and mimeType = 'application/vnd.google-apps.document' and trashed = false, or 'FOLDER_ID' in parents. Sorted by last modified by default. Page with page_token.

Ref io.b3os/google-drive/search-files@1.0.0 · effect read · connection google · MCP tool google-drive__search-files

bash
curl -s https://beta-api.b3os.org/v1/actions/call \ -H "Authorization: Bearer $B3OS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ref": "io.b3os/google-drive/search-files@1", "input": { "query": "name contains '\''roadmap'\'' and trashed = false", "page_size": 2 }, "connections": {"google": "conn_01m5t6cbgdjs1ketgcqwa2sne8"} }'

Output, labeled fixture: Search files (documented response shape, example values). From the bundle's fixtures/search-files.json, not a live call.

json
{ "files": [ { "id": "1aBcDeFgHiJkLmNoPqRsTuVwXyZ012345", "name": "Q4 roadmap", "mime_type": "application/vnd.google-apps.document", "modified_time": "2026-10-25T21:30:00.000Z", "created_time": "2026-09-02T16:00:00.000Z", "size": null, "web_view_link": "https://docs.google.com/document/d/1aBcDeFgHiJkLmNoPqRsTuVwXyZ012345/edit", "parents": ["0AFolderRootExample"], "owner": "Mona Example", "owner_email": "mona@acme.example", "trashed": false, "starred": false }, { "id": "1zYxWvUtSrQpOnMlKjIhGfEdCbA987654", "name": "roadmap-2025.pdf", "mime_type": "application/pdf", "modified_time": "2026-10-25T21:30:00.000Z", "created_time": "2026-09-02T16:00:00.000Z", "size": "482113", "web_view_link": "https://drive.google.com/file/d/1zYxWvUtSrQpOnMlKjIhGfEdCbA987654/view", "parents": ["0AFolderRootExample"], "owner": "Mona Example", "owner_email": "mona@acme.example", "trashed": false, "starred": false } ], "next_page_token": "~!!~AI9FV7Q-example"}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

pack_error.codeService statusRetryableMessage
not_found404nobuilt from the service's response
connection_unauthorized401noGoogle rejected the access token (expired or revoked); refresh or reconnect it.
rate_limited429, 403yesbuilt from the service's response
forbidden403nobuilt from the service's response
invalid_request400nobuilt from the service's response
conflict409nobuilt from the service's response

get-file

Get file metadata. One file's name, type, size, owner, parents, timestamps and web link.

Ref io.b3os/google-drive/get-file@1.0.0 · effect read · connection google · MCP tool google-drive__get-file

bash
curl -s https://beta-api.b3os.org/v1/actions/call \ -H "Authorization: Bearer $B3OS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ref": "io.b3os/google-drive/get-file@1", "input": {"id": "1aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"}, "connections": {"google": "conn_01m5t6cbgdjs1ketgcqwa2sne8"} }'

Output, labeled fixture: Get file metadata (documented response shape, example values). From the bundle's fixtures/get-file.json, not a live call.

json
{ "id": "1aBcDeFgHiJkLmNoPqRsTuVwXyZ012345", "name": "Q4 roadmap", "mime_type": "application/vnd.google-apps.document", "modified_time": "2026-10-25T21:30:00.000Z", "created_time": "2026-09-02T16:00:00.000Z", "size": null, "web_view_link": "https://docs.google.com/document/d/1aBcDeFgHiJkLmNoPqRsTuVwXyZ012345/edit", "parents": ["0AFolderRootExample"], "owner": "Mona Example", "owner_email": "mona@acme.example", "trashed": false, "starred": false}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

pack_error.codeService statusRetryableMessage
not_found404nobuilt from the service's response
connection_unauthorized401noGoogle rejected the access token (expired or revoked); refresh or reconnect it.
rate_limited429, 403yesbuilt from the service's response
forbidden403nobuilt from the service's response
invalid_request400nobuilt from the service's response
conflict409nobuilt from the service's response

export-document

Export Google Doc, Sheet or Slides. The contents of a Google Doc as plain text or Markdown, of a Sheet's first tab as CSV, or of Slides as plain text. Exports are limited to 10 MB by Google. For other text files use download-text.

Ref io.b3os/google-drive/export-document@1.0.0 · effect read · connection google · MCP tool google-drive__export-document

bash
curl -s https://beta-api.b3os.org/v1/actions/call \ -H "Authorization: Bearer $B3OS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ref": "io.b3os/google-drive/export-document@1", "input": { "id": "1aBcDeFgHiJkLmNoPqRsTuVwXyZ012345", "format": "text/markdown" }, "connections": {"google": "conn_01m5t6cbgdjs1ketgcqwa2sne8"} }'

Output, labeled fixture: Export Google Doc, Sheet or Slides (documented response shape, example values). From the bundle's fixtures/export-document.json, not a live call.

json
{ "id": "1aBcDeFgHiJkLmNoPqRsTuVwXyZ012345", "format": "text/markdown", "content": "# Q4 roadmap\n\n## Goals\n\n- Ship checkout v2\n- Cut p50 checkout latency in half\n"}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

pack_error.codeService statusRetryableMessage
not_found404nobuilt from the service's response
connection_unauthorized401noGoogle rejected the access token (expired or revoked); refresh or reconnect it.
rate_limited429, 403yesbuilt from the service's response
forbidden403nobuilt from the service's response
invalid_request400nobuilt from the service's response
conflict409nobuilt from the service's response

download-text

Download text file. The contents of a regular file stored in Drive (txt, csv, md, json, ...) as text. Binary files come back garbled; Google Docs need export-document. Very large files can exceed the runtime's response size limit.

Ref io.b3os/google-drive/download-text@1.0.0 · effect read · connection google · MCP tool google-drive__download-text

bash
curl -s https://beta-api.b3os.org/v1/actions/call \ -H "Authorization: Bearer $B3OS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ref": "io.b3os/google-drive/download-text@1", "input": {"id": "1zYxWvUtSrQpOnMlKjIhGfEdCbA987655"}, "connections": {"google": "conn_01m5t6cbgdjs1ketgcqwa2sne8"} }'

Output, labeled fixture: Download text file (documented response shape, example values). From the bundle's fixtures/download-text.json, not a live call.

json
{ "id": "1zYxWvUtSrQpOnMlKjIhGfEdCbA987655", "content": "company,stage,amount\nAcme,Proposal,12000\n"}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

pack_error.codeService statusRetryableMessage
not_found404nobuilt from the service's response
connection_unauthorized401noGoogle rejected the access token (expired or revoked); refresh or reconnect it.
rate_limited429, 403yesbuilt from the service's response
forbidden403nobuilt from the service's response
invalid_request400nobuilt from the service's response
conflict409nobuilt from the service's response

create-folder

Create folder. Create a folder, optionally inside another folder (parent_id). Returns its id and link. Not idempotent: Drive allows several folders with the same name.

Ref io.b3os/google-drive/create-folder@1.0.0 · effect write · connection google · MCP tool google-drive__create-folder

bash
curl -s https://beta-api.b3os.org/v1/actions/call \ -H "Authorization: Bearer $B3OS_API_KEY" \ -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \ -H "Content-Type: application/json" \ -d '{ "ref": "io.b3os/google-drive/create-folder@1", "input": {"name": "Launch assets", "parent_id": "0AFolderRootExample"}, "connections": {"google": "conn_01m5t6cbgdjs1ketgcqwa2sne8"} }'

Output, labeled fixture: Create folder (documented response shape, example values). From the bundle's fixtures/create-folder.json, not a live call.

json
{ "id": "1FoLdErIdExample0123456789", "name": "Launch assets", "mime_type": "application/vnd.google-apps.folder", "modified_time": "2026-10-25T21:30:00.000Z", "created_time": "2026-09-02T16:00:00.000Z", "size": null, "web_view_link": "https://drive.google.com/drive/folders/1FoLdErIdExample0123456789", "parents": ["0AFolderRootExample"], "owner": "Mona Example", "owner_email": "mona@acme.example", "trashed": false, "starred": false}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

pack_error.codeService statusRetryableMessage
not_found404nobuilt from the service's response
connection_unauthorized401noGoogle rejected the access token (expired or revoked); refresh or reconnect it.
rate_limited429, 403yesbuilt from the service's response
forbidden403nobuilt from the service's response
invalid_request400nobuilt from the service's response
conflict409nobuilt from the service's response
Ask a question... ⌘I