List the Google accounts that have been authorized for this server.

Write this project’s defaults to a .gdocs-mcp.json in the current working directory (or update an existing one up the tree). Set a default account and/or a default folder (URL or id). The folder is where write_doc is told new docs go: a new doc given as a bare name or at the top of My Drive is refused once, naming the folder and the full path to call. It is read when the server starts, so write_doc’s description shows a change after a restart; the refusal reads it fresh. To set a folder by name, find it first with drive({ cmd: 'find' }) and pass its id.

Show the effective .gdocs-mcp.json defaults (account/folder) for the current working directory, and where the file is.

Read a Google Doc as markdown + inline HTML. The read opens with a block — one CSS rule per named style (p = Normal text, h1–h6, .title, .subtitle), in pt — and a paragraph or run shows style="…" only where it differs from its rule (text-align, line-height, margin-top/bottom/left/right, text-indent; a hanging indent is margin-left:36pt with a negative text-indent). Title and Subtitle paragraphs read as . A page break reads as on its own line, where the break is. Every element in a paragraph reads, so an edit that quotes one can give it back: a footnote is [^1] with its note as a [^1]: line at the end; a date is Nov 15, 2026; a person or a link chip is Jane Doe (the text is Google’s); a dropdown is with its list as a Draft line after the block; a horizontal rule is --- on a line of its own; a column break is ; an equation and a page-number field are empty and whose title says to edit them in Google Docs. A table of contents is not read. List items show no indent: their nesting owns it. mode: clean (committed text, default) · tracked (suggestions shown as /) · accepted · rejected. segment picks the content tree: body (default), header, footer, or all (body plus every header/footer, each labelled). Text that would otherwise read as markup is marked as literal: a paragraph wrapped in … ("4. Term" is a paragraph, not a list) or a backslash before a character (5 * 3), and \ is a real backslash — write them back as read, and the document keeps only the words. A body read always reports which headers/footers exist and what they hold, since their content — a letterhead logo, a page number — is NOT part of the body and would otherwise be invisible.

Replace an exact unique snippet of text in a Google Doc (like a local file Edit). old_string is matched markup-tolerantly; ambiguous matches return surrounding context to disambiguate; a table is matched as its rows, in the form read_doc shows it (a pipe table, or the HTML of a styled one). Elements read_doc shows are kept when old_string and new_string both hold them as read (a person chip inside a sentence you reword survives), deleted when new_string leaves them out, and created when new_string adds one: [^label] with a [^label]: note line, Nov 15, 2026 (the text’s shape picks the date format), for a person or for a Drive file, with its line, and --- for a rule. A column break, equation, page-number field, or link chip to anything but a Drive file cannot be made: it is refused before anything is sent, and a chip’s text is Google’s (a chip given other words is refused). A footnote’s note is edited by quoting its [^1]: line, and a dropdown’s list by quoting its line. INSERTING IS AN EDIT: quote the text to add after (or before), write it back in new_string, and add the new content to it. Text from old_string that comes back unchanged is kept as it is, with its style, comments and suggestions, so old_string | Total | $4,200 | and new_string | Total | $4,200 |\n\nPayment due within 30 days. leaves the table alone and adds the paragraph after it; a match that ends in a table puts the new blocks after the whole table. An anchor in the middle of a paragraph splits the paragraph there. A new block carries its own style, not its anchor’s: a paragraph added after a heading, a Title or a list item is Normal text with no bullet unless the markdown says otherwise, while text added inside an existing paragraph keeps that paragraph’s style. An empty doc, tab, header or footer has nothing to anchor on: use write_doc. new_string is the same markdown and inline HTML write_doc takes: headings, lists, tables, images (<img src width height> or ![alt](src); a centered one is <p style="text-align:center"><img …></p>, local files resolve against baseDir), page breaks, and inline constructs (bold, italic, code, text, <u>, <span style="color:…;font-size:…pt">, <p style="…">, <p class="title">, and a page break as a line of its own: <div style="page-break-after:always"></div>, so new_string Title page\n<div style="page-break-after:always"></div> puts what follows on a new page; old_string can span a break) — the same spelling read_doc emits, so a read can be edited and written back. STYLE IS CSS, and this is the only way to change it. Restyle text you are not otherwise changing by giving the same words with different markup: old_string <p>4. Term, new_string <p style="margin-left:36pt; text-indent:-18pt">4. Term sends only style requests — no delete, no insert, so a long paragraph is never retyped and its words cannot change; markup missing from new_string is cleared (drop the wrapper to remove an indent). To restyle a whole named style, edit its rule in read_doc’s block: old_string p { font-family: Arial; font-size: 11pt, new_string p { font-family: Arial; font-size: 12pt becomes one updateNamedStyle and every paragraph that does not override it follows. An unsupported property (border, float, a px length, a typo) fails the edit before any request is sent, listing every offending line and the supported set. TABLE STYLE is CSS on the table’s HTML, changed the same way: read_doc shows a table with any cell or row style, wide or short columns, pinned rows or merged cells as with , (a minimum), (exactly the pinned rows), (border, padding, background, vertical-align) and colspan or rowspan, one row per line, while a table with nothing but Docs defaults stays a pipe table. old_string <td>Client</td>, new_string <td style="background:#eeeeee">Client</td> sends only the style request, and every cell whose words come back unchanged is kept, not retyped; styling a pipe table is giving the whole table back as HTML with the same words. A table edit that changes rows, columns or merges is a comparison: quote the rows around the change, write the rows you want, and only the difference is sent, an insertTableRow, deleteTableRow, insertTableColumn, deleteTableColumn, mergeTableCells or unmergeTableCells plus the text of the cells that changed, so cells you did not change keep their comments and style. A new row or column copies the style of the row above (the row below when the row above is a header row) or the column to its left (to its right for a new first column), and a style you write on it wins; links are not copied. A row or column you move is a delete and an insert: when comments quote its text the first call is refused with a confirmLoss string, so ask the user and pass it back as confirmLoss after their yes. A change that cannot be read cleanly (a row that could be an edit of either of two new rows, a table that shares no row with the old one, a column added without its line) is refused and says what to quote; a table is never rewritten whole. SUGGEST: pass suggest: true to send the edit as suggestions, for a person to accept or reject in Docs, when the user wants to review the change or the doc is not theirs; the result lists in suggestions the ids of the suggestions that now hold the edited text (a change next to your own pending suggestion joins it, and then its id is the one listed). It defaults to false, and then the edit is applied as live text: if the doc has pending suggestions from other reviewers, tell the user your edit sits alongside them as an accepted change. A change Docs cannot suggest (a table column width, for one) refuses the whole edit before anything is sent.

Read a doc’s (or tab’s) page setup — margins, page size (in points, plus a preset name if it matches letter/legal/a4/tabloid), and orientation. The read counterpart to set_page_setup; use it to mirror another document’s layout onto a new doc.

Set document-level page setup for a doc (or tab): page margins, page size, and orientation — the File > Page setup controls. Margins and explicit page sizes are in points (72 pt = 1 inch). pageSize is a preset (letter/legal/a4/tabloid) or an explicit {width,height} in points; orientation (portrait/landscape) swaps the page dimensions. Always a direct change: page geometry is a document-style change, so there is no suggest option.

Download every embedded image in a Google Doc to a local folder. Returns the objectId→filename mapping, which correlates with read_doc’s <img src="image:<objectId>"> markers so you can rewrite them to local paths (the inverse of publishing).

List the pending suggestions (tracked changes) in a Google Doc, in document order. Each has an id, a summary (Docs’ own words for it, as in the Docs sidebar, e.g. Replace: “30” with “45”), a context (the change in its sentence, [deleted→inserted], so two suggestions with the same summary can be told apart), and its author and time. Returns the doc title. Pass the title as expectTitle and each context as expectContext to apply_suggestions. segment: "header" or "footer" lists that one’s suggestions.

Accept or reject pending suggestions (from list_suggestions) in one update. Each one is resolved on its own, exactly as clicking the check or the cross in Docs: accept keeps the proposed change, reject restores the original. Two suggestions that touch each other (by different people) are decided one at a time, and the text comes out as Docs makes it; to decide them together, pass both. A style-only suggestion resolves like any other. expectTitle is checked against the live document first (status "wrong_doc" on a mismatch, e.g. an id from a different, similarly-titled document), and each expectContext is checked against the live suggestion (status "error" on a mismatch or an id that is gone); nothing is changed unless all match. Pass the title and each suggestion’s context from list_suggestions, verbatim.

List the comments on a Google Doc, each with the text it is on (quotedText), the sentence around it (context, the text in ⟦⟧), its author (a display name, never an email) and time, whether it is open or resolved, its body and its replies. A comment with a range is on that part of the doc, in the body or in a header or footer, and moves with its text; a comment with none was made in Drive and has only its quoted text. Pass a comment’s id as replyTo to add_comment, and its quotedText as expectQuotedText to resolve_comment.

Comment on text in a Google Doc: quotedText is the text the comment sits on, found the way edit_doc finds old_string (markup-tolerant; text that matches more than once is refused with the context of each match, so quote more of it). The comment stays on that text as it moves. Docs has no comment on the whole doc, so quotedText is required; put overall feedback on the title, or on its first words. The tab comes from path, and segment: "header" or "footer" comments in the page header or footer. To reply to an existing comment instead, pass replyTo (a comment id from list_comments) and no quotedText; the reply goes to the doc named by path, whatever its tab.

Resolve (or reopen) a comment thread by comment id. expectQuotedText is REQUIRED: the quotedText list_comments gave for that comment, exactly. It is checked against the live comment first, so a stale or wrong id is refused instead of resolving the wrong thread.

Export a Google Doc to a real file on disk — pdf (default), docx, odt, rtf, txt, html, epub, or md. Google renders it server-side (File > Download in the UI), so page setup, pagination and layout match the editor. A doc path exports every tab; a tab path (/folder/doc/tab) exports only that tab, through an endpoint Google does not document and rate-limits — if it fails the call is refused and says so, it never falls back to the whole doc. Returns the local path and byte size. Note: Drive refuses to export files larger than 10 MB.

Write markdown-rendered content to a path, like the local Write tool. A path that names nothing is CREATED and never asks, but only an absolute path (or a Drive id or URL start) creates: a bare name like Contract is refused with the full path to call. When the project has a default folder for new docs, a new doc at the top of My Drive (/Contract) is refused once too, with the default folder’s full path to call, so the user is told where it goes first; the same call repeated goes through: /Work/Contract creates a doc in the folder /Work, /Work/Contract/Notes a tab in that doc, /Work/Contract/Part 2/Ch.4 a child tab under Part 2 (only the last step may be new; make the folder with drive mkdir first). A path that names something is REPLACED, and the first call is refused with a loss summary — the paragraphs of text and everything a read cannot carry that the replace would take with it: comments, suggestions, tab stops, links to bookmarks, section breaks, a table of contents, column breaks, equations, page-number fields, a date in a format the API can only read, and a link chip to anything but a Drive file — plus a confirmLoss string. Ask the user before anything else — show them what would be lost and wait for a yes; never pass confirmLoss on your own. Only after their yes, call again with the same content and confirmLoss set to that string exactly. If the doc changed in between, the string no longer matches and the call is refused again with a fresh summary. A doc with several tabs needs a tab step (the refusal lists them); a doc with one tab means that tab. Nothing to lose, nothing to ask: an empty doc, tab, header or footer is written without the refusal. segment: "header" or "footer" writes the page header or footer of an existing doc instead of its body: a missing default one is created and written, an existing one with content is replaced after the same confirmLoss round-trip, and a missing first-page or even-page one (page: "first" / "even") is refused with the instruction to turn on Different first page in Docs. Replacing keeps the doc’s title, sharing and other tabs but the new paragraphs start unstyled, so anything not in the markdown (including indents) is gone; prefer edit_doc to change a document, which keeps everything its anchor does not cover. Style is CSS, in the spelling read_doc emits: a leading block sets the named styles (p, h1–h6, .title, .subtitle), / / style a paragraph, a run. Supported: text-align, line-height, margin-top/bottom/left/right, text-indent (pt; text-indent is relative to margin-left), and on spans/rules font-family, font-size, font-weight, font-style, text-decoration, color. Any other property fails the whole write before anything is sent, listing every offending line. Footnotes, dates, person chips, Drive link chips and dropdowns are written back as read_doc spells them ([^1] and a [^1]: note line; ; ; with its line); --- is written as an empty paragraph with a thin grey bottom border. A new column break, equation, page-number field, or link chip to anything but a Drive file (YouTube, Calendar, Maps, a web page) is refused before anything is sent: the API cannot make it, so write text for a link, or ask the user to insert the rest in Google Docs. A chip’s text is Google’s, so a chip given other words is refused. A page break is on a line of its own (also accepted: , break-before: page, break-after: page); any other or is refused. For long documents, pass contentFile instead of content so the server reads the body directly (retyping a long doc inline can silently drop text). Returns images ({src, objectId}) for pushed images. suggest: true sends the replace as suggestions for a person to accept or reject in Docs, and never asks for confirmLoss: nothing is lost until a person accepts, and rejecting brings back the text, images, tables and comments as they were. It needs a path that already names something (a new doc or tab cannot be a suggestion), refuses a table column width (Docs cannot suggest one) before anything is sent, and lists the suggestion ids in suggestions; use it when the user wants to review the rewrite or the doc is not theirs. It defaults to false: the replace is applied as live text.

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.

List the permissions on a Google Doc (people, groups, domain, anyone-with-link) with their roles. Each entry carries a subject naming who it covers — an email, " (domain)", or "anyone with the link" — since a domain or link grant has no email. For those, allowFileDiscovery: true means the file also surfaces in that audience's search, not merely that it opens with the link. Note a doc created under a Workspace domain may already carry a domain grant before you share it.

Grant access to a Google Doc. With email, share with that person as reader/commenter/writer (optionally sending a notification). Without email, set anyone-with-link access to that role, or role "none" to disable link sharing. (To revoke a specific person’s access, use unshare_doc.)

Revoke a grant on a Google Doc. Pass email for a person or a group. A grant with no email — a domain-wide grant, or anyone-with-link — has no email to pass, so address it by permissionId from list_permissions (run that first; it also tells you the role you are about to remove). Refuses to touch the owner. expectRole is REQUIRED — run list_permissions first and echo the role back; a permission change is recorded nowhere and cannot be restored from version history, so this is the only thing standing between a misaimed call and a silent, unrecoverable revocation. Note a doc created under a Workspace domain may carry a domain grant nobody explicitly added.