gdocs-mcp

Drive as a filesystem

drive

Navigate and reorganize Google Workspace files, Docs tabs, and shared folders using shell-style ls, find, mkdir, cp, and mv commands.

Instructions

Navigate and reorganise Google Drive with shell commands: ls, find, mkdir, cp, mv. Arguments are positional and follow the usual shell forms. ls [path] — list a folder (default My Drive root). find [-type d|f] — search everything by name, including files no path can reach. mkdir [-p] — create a folder. cp — duplicate a file (preserves headers/footers, image sizing and exact formatting, which a markdown round-trip cannot rebuild). mv — move and/or rename, as on a filesystem: an existing folder as means "into it", anything else means "to that name". Paths start with / or ~ (My Drive); /shared/ is a shared drive, /shared-with-me the files others shared with you, and /lost+found the files you own that are in no folder at all. Anything not starting with / or ~ is read as a Drive id or URL, so ids from any other tool can be pasted straight in. Drive permits two files with the same name in one folder and folds case when matching, unlike any real filesystem — a path that matches more than one thing is refused with the candidates listed, never guessed. A doc is a folder of tabs: ls lists its tabs, ls shows each doc with its tab count, and a path continues into tabs (/Work/Contract/Part 2/Ch.4; a tab step may also be a tabId). mv on a tab renames it, nests it (dst is another tab, or a new name under one) or un-nests it (dst is the doc), and index reorders it; a tab cannot leave its doc, and cp of a tab is refused. Content is edited with edit_doc and written with write_doc, not here; there is no rm, and nothing here deletes a tab. A tab is made by write_doc to a new path.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "cmd": "<cmd>"
    },
    "name": "drive"
  }
}

Input Schema

Name	Required	Description
`cmd`	Yes
`args`	No	positional arguments for cmd, e.g. ["/Work/Roof", "/Archive"] for mv
`index`	No	mv of a tab only: its position among its new siblings, 0 first. Without it a tab keeps its place, or goes first when nested.
`account`	No	Google account email to use. Defaults to GDOCS_DEFAULT_ACCOUNT, or the sole account.
`expectName`	No	mv only: the name the source is expected to have; the move is refused if it resolved to something else
`acceptOwnershipTransfer`	No	mv only: required to move into /shared/… , which hands ownership to that drive's organisation and cannot be undone

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.0.0Oct 31, 2026

addedInput schema / properties / index

Added value: +{
+  "description": "mv of a tab only: its position among its new siblings, 0 first. Without it a tab keeps its place, or goes first when nested.",
+  "minimum": 0,
+  "type": "integer"
+}

Addedv0.6.0Aug 22, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full disclosure burden, and it does: ambiguity is refused with candidates listed rather than guessed, duplicate names and case-folding are called out as deviations from a real filesystem, cp preserves formatting a markdown round-trip would lose, and tabs cannot leave their doc, nor can they be copied. It also flags the non-obvious destructive edge (moving into /shared/ hands ownership to the drive's organisation), matching the schema note without contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded, then commands, then path model, then tab model, then exclusions — a sensible order for a dispatcher tool. It is dense and long, with the tab paragraph packed into a single block, but nearly every clause carries a decision-relevant constraint rather than repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter, five-subcommand tool with no annotations and no output schema, the description covers commands, path grammar, the tab model, refusal behavior and out-of-scope operations. It does not describe what ls or find actually return, which is the main remaining gap given the absence of an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 83%, so the baseline is 3, but the description adds real meaning: positional-argument conventions per command, path prefix semantics (/ and ~ for My Drive, /shared/, /shared-with-me, /lost+found), tab-step path continuation, and the rule that a non-prefixed value is treated as a Drive id or URL. It leaves expectName and account to the schema, so it stops short of full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: "Navigate and reorganise Google Drive with shell commands," then enumerates the five subcommands. It explicitly demarcates itself from siblings by stating that content is edited with edit_doc and written with write_doc, not here, and that there is no rm. An agent can distinguish this from read_doc/edit_doc/write_doc without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states when to use this tool (navigation, reorganisation, folder creation), when not to (content editing and writing belong to edit_doc/write_doc), and names the alternatives. It also covers the creation path for tabs ("A tab is made by write_doc to a new path") and the absence of deletion, which are exactly the wrong assumptions an agent would otherwise make.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.