io.github.mmedum/google-docs-mcp

Post a comment on a Google Doc. With a target (exact text, heading_id, handle or cell) the comment is pinned to that passage; if Google refuses the comments view for the document it quotes the text instead and the editor shows it unanchored, which the result says. Without a target it is a comment on the document as a whole. Nothing in the document text changes. To propose an edit as a comment, use edit_document with mode comment. On a Markdown file (.md) the comment is written into the file under the signed-in account's name, the way the Docs editor writes its own, and needs a target. dry_run resolves the target and stops before posting.

Create a new Google Doc in the signed-in account's Drive, optionally with initial content written as markdown (headings, formatting, lists, tables, images). Returns the id and URL. Initial content is written directly because a new document has nothing to suggest against. With kind markdown_file it makes a Markdown file (.md) instead, holding the content as written; such a file is edited as text. With from_file it makes a working copy of a Markdown file: a Google Doc holding its text, for working in together live with every write mode, which write_markdown_file writes back into the file.

Show what changed between two revisions of a Google Doc as a unified diff of Google's markdown (or plain text) export, with line counts per hunk. Pass from (older) and optionally to (newer, default current). Use list_revisions to pick ids.

Change the text of a Google Doc with one batch of operations. Address content by exact text (quoted from a read), by heading_id or heading (a whole section), by block handle, or by cell; never by position numbers. Ops: insert (at a location), append (end of body), replace (minimal diff, so untouched words keep their formatting and comments), delete, replace_all (find/replace in one tab, by text or regex), insert_break (page break), insert_footnote, create_header, create_footer, delete_header, delete_footer (target: tab and segment), and the named-range ops: create_named_range names a target so later calls can find it again after edits move it, where a handle is only valid for the revision it came from; replace_named_range writes plain text over it; delete_named_range forgets the name and leaves the text. Content is markdown. A table or image in it is placed by later batches once the text has landed, so a failure there leaves the text written and says so. mode chooses how the change lands: suggest = tracked change for a person to accept, direct = edit the text, comment = post each proposed change as a comment and change nothing. Direct edits refuse to delete ranges holding comments, suggestions, images or footnotes unless force is set. Use dry_run to preview the plan. Returns the new revision id, suggestion or comment ids, and a rendered preview of the edited region. On a Markdown file (.md) the ops are insert, append, replace, delete and replace_all, content is written as the file's own markdown, mode is direct or comment (no suggestions), the comments Docs keeps in the file are never touched, and the whole file is uploaded once per call, which makes an editor that has it open reload; the write waits for, then refuses, changes made there and not saved yet. To work in one together live, use a working copy (create_document from_file). On a Word file (.docx) the same ops write its body's text into the file, addressed as on a Google Doc, a suggestion as a tracked chang…

Create and change tables in a Google Doc. Ops: insert_table (rows, columns, optional data grid, at a location), set_cells (write cells by name or as a grid from start_cell; each cell is replaced by minimal diff), insert_rows, delete_rows, insert_columns, delete_columns, merge_cells, unmerge_cells, style_cells (background, vertical alignment, padding), style_columns (fixed width in points, or share the width evenly), style_rows (least height, keep a row off a page break), pin_header_rows (repeat the first n rows on every page). Tables are named by handle (tbl1) from a read with with_handles; cells as r2c3. Text inside cells can also be edited with edit_document (target cell) and styled with format_document. Same mode, dry_run, expect_revision and force semantics as edit_document; deleting rows or columns that hold comments or suggestions is refused in direct mode unless forced.

Export a Google Doc through Google's converters. md, txt and html come back inline (budgeted by max_chars); pdf, docx, odt, rtf and epub are written as new files under the server's export directory, never over a file already there, and the path is returned. The markdown export is Google's own rendering, useful for a faithful whole-document dump; read_document is better for working with sections.

Find text or a regular expression in a Google Doc and return every match with its block handle, offset and surrounding context. Use it to locate passages before targeting them with edit_document (quote the matched text as the target) and to check how many times a phrase occurs.

Change formatting in a Google Doc without changing its text: text_style (bold, italic, underline, strikethrough, small caps, font, size, color, highlight, link, superscript), paragraph_style (named style such as HEADING_2 or NORMAL_TEXT, alignment, line spacing, spacing, indents), bullets (bullet, numbered, checkbox, or none), and clear_formatting. Targets work as in edit_document. This styles the passages you target: to restyle every paragraph carrying a style at once, and everything written with it later, redefine the style itself with layout_document's named_style op. Same mode, dry_run and expect_revision semantics.

Get metadata and structure counts for a Google Doc: title, tabs, the current revision id, owner, last modification, paragraph and word counts, pending suggestion count, and this server's capabilities (whether suggestion mode is available, the default write mode, read-only). Per tab it also reports what no read of the text shows: page setup, floating images, named ranges, and the named style definitions the tab's paragraphs carry (the font, size, color and spacing every heading or body paragraph inherits, with how many paragraphs of that tab carry each, headers and footnotes included; layout_document's named_style op redefines those definitions). kind says whether it is a Google Doc, a Markdown file (.md) that Docs opens in place, which is read and written as its own text, or a Word file (.docx), read like a Google Doc and written into the file itself. Cheap; call it first when handed a document id or URL. Then use get_outline for the heading tree and read_document for content.

Return the heading tree of a Google Doc per tab: each heading's stable heading_id, block handle, level, text, and the size of its section in blocks and words, plus per-tab counts of paragraphs, tables, headers, footers and footnotes. Use it to pick a section to read with read_document (pass heading_id) instead of reading a long document whole, and to learn block handles. Cheap.

Insert, replace or delete a non-text object in a Google Doc. action insert (default) adds an image from a public URL (optionally sized in points), a person chip (email), a rich-link chip to a Google resource (Drive file, Calendar event, YouTube video), or a date chip at a location; objects go inline in a paragraph, so use edit_document for the surrounding text. action replace swaps an existing image's source while it keeps its place and size (crop center-crops the new image instead of resizing the frame). action delete removes an object, including a floating image, which no text range covers and no edit_document delete can reach. Both name the object by the id a read shows, like kix.img1. Same mode, dry_run, expect_revision and force semantics as edit_document; deleting an inline object that also carries a comment or a suggestion is refused in direct mode unless forced. Suggestion mode tracks the insertion.

Change how a Google Doc is laid out rather than what it says. Ops: page (page size, margins, background color, landscape, where page numbering starts, whether the first and even pages get their own header and footer, pageless), section (the same for one section, plus 1-3 columns with an optional separating line and the gap between them), section_break (start a new section at a location, continuous or on the next page), and named_style (redefine NORMAL_TEXT, TITLE, SUBTITLE or HEADING_1 … HEADING_6 for the whole tab, which restyles every paragraph carrying that style and everything written with it later; get_document reports the definition of each style the tab's paragraphs currently carry, so read it first to see what one looks like today). Lengths are in points: 72 to the inch, so US Letter is 612×792 and A4 is 595×842. Use format_document instead to style one passage. Same mode, dry_run and expect_revision semantics as edit_document.

List the comment threads of a Google Doc with their full history: author, time, quoted text, the block handle the comment sits on, resolved state, who it is assigned to, and every reply (including resolve and reopen actions). Resolved threads are included unless hide_resolved is set; deleted ones only with include_deleted. Thread ids feed reply_comment and delete_comment. On a Markdown file (.md) the comments made in the Docs editor live in the file, the line they sit on is shown as [L12], and the id of one written by this server changes each time the file is written until a person saves it in the editor.

List a Google Doc's version history, newest first: revision id, time and who changed it. These ids feed diff_revisions and read_document's revision parameter; they are Drive revision ids, not the revision_id that reads and writes return for concurrency control. Drive may omit older revisions of busy documents.

List pending suggested edits (tracked changes) in a Google Doc: id, kind (insert, delete, replace, structure, format), the inserted, deleted and restyled text, the block handle, and, where Google includes them, the author and status, and the replies on its thread. A format suggestion changes only formatting and says what it restyles, as "text: bold" or "paragraph: alignment". Ids feed review_suggestion, and reply_comment with suggestion_id.

Add, rename or move a tab of a Google Doc. add takes a title, optional position, parent tab, emoji and initial markdown content; rename changes the title or emoji; move changes the position among siblings or nests the tab under a parent. Tab changes are always direct edits (the API cannot suggest them). Other tools address tabs by id, title or number; get_document lists them.

Read part or all of a Google Doc as markdown (default), plain text, or raw Docs API JSON. Scope it to one section with heading_id (from get_outline) or heading text, to a block range with from_handle/to_handle, to another tab with tab, or to a header, footer or footnote with segment; with no scope it reads the whole body of the first tab. Output is budgeted by max_chars (default 20000 characters); when truncated the result carries continue_from to pass back. Block handles ([p12]) and heading ids come with the text unless with_handles is false; with_styles adds formatting markdown cannot show, include_suggestions shows pending suggested edits inline as {++inserted++} / {--deleted--}, with a formatting-only suggestion as {==highlighted==} because it adds and removes nothing, and include_comments marks commented passages with {>>c:id<<} and lists those threads below. Empty paragraphs are kept so structure is faithful. Handles are valid for the revision_id returned. A Markdown file (.md) reads as its own text, without handles: scope it by heading_id or heading, and a truncated read continues from a line (continue_from L120).

Reply to a comment thread, resolve it, reopen it, or rewrite what it says. Resolving and reopening are reversible; both may carry a message. action edit replaces the text of the thread's own comment, or of one reply when reply_id names it; Google allows only the author of a comment to rewrite it. Thread and reply ids come from list_comments. With suggestion_id instead of comment_id it replies on a suggested edit's thread; accepting or rejecting one is review_suggestion. On a Markdown file (.md) a comment the Docs editor keeps takes replies only, written into the file; the person resolves it in the editor.

Accept, reject or discard pending suggested edits, each named by its id from list_suggestions. Accepting applies the suggested text; rejecting declines it, which any editor may do; discarding removes the suggestion outright, which Google allows only its author. Pass expect_revision to refuse if the document changed since the list was read. dry_run resolves the suggestions and stops before the write.

Locate Google Docs the signed-in account can open, by words in the title or the text, optionally limited by owner or modification date, newest first. Returns ids and URLs to pass to the other tools. With no filters it lists recently modified documents. Markdown files (.md) are found with kind markdown_file or any.

Write a working copy back into the Markdown file it was made from (create_document from_file makes one). Only what changed in the copy is carried over, block by block; the rest of the file keeps its own Markdown, its front matter and the comments Docs keeps in it. A change to a block that was also changed in the file since the copy was made is a conflict and is refused, unless force keeps the file's version of those and writes the rest. edit_document's guard applies, and a write waits for, then refuses, changes made in the Docs editor on the file and not saved yet, forced or not: that work is in no revision yet. dry_run shows the diff.