Skip to main content
Glama

verified-googledocs-mcp

CI Coverage Python 3.12+ License: MIT

An MCP server for Google Docs whose writes carry proof. Every mutating tool re-reads the affected content from the document after it writes and returns evidence of what actually changed: before/after excerpts, the match count, and the document revision before and after. A tool never reports success for an edit that did not land.

Status: all 20 tools are implemented, covered by an offline unit suite, and exercised against the real Google Docs and Drive APIs by the live test suite. The original fourteen passed the formal live acceptance gate; the gate is rerun before each release. Install with uvx verified-googledocs-mcp. See Status.

The problem

Driving Google Docs from an agent through a general Workspace MCP server tends to fail in quiet, expensive ways:

  • A findAndReplace meant for one tab silently edits every tab in the document.

  • A search returns "0 matches" because the document has curly quotes or a non-breaking space the query doesn't, with no hint why.

  • A replace meant for one occurrence hits a repeated sentence and collapses both.

  • A "resolve comment" call returns success while the comment stays open.

  • Listing comments misses suggested edits entirely.

  • A markdown merge injects garbled text that a human only catches days later.

Each of these has a procedural workaround: tell the agent to scope to a tab, retry with normalized quotes, re-read after every write, never trust a resolve result. Those instructions work until someone forgets one. This server moves the discipline into the protocol, where it is deterministic.

Related MCP server: LLM2Docs (Unofficial)

The verified-write contract

Every mutating tool runs the same pipeline: read the tab, locate the target, apply the edit under a revision precondition, read the tab again, and return evidence built from the second read. The return value is a claim about the document's state after the call, backed by a server-side re-read, not an echo of the API response.

// replace_text(doc_id, tab_id, find="teh", replace="the", expected_matches=1)
{
  "applied": true,
  "match_count": 1,
  "rung": "exact",                 // which normalization rung matched
  "before": "...±200 chars around the edit, pre-write...",
  "after":  "...the same span, re-read after the write...",
  "revision_before": "ALm37BX...",
  "revision_after":  "ALm37Cy...",
  "audit_logged": true
}

When something is wrong, the tool fails loud and diagnosed, with a typed error the agent can act on in one round trip rather than guessing:

{
  "error_code": "MATCH_COUNT_MISMATCH",
  "message": "expected 1 match(es) but found 3 at rung 'exact'",
  "diagnostics": { "expected": 1, "actual": 3, "spans": [ /* every location */ ] },
  "retryable": false
}

What backs the guarantee

  • Tab-scoped by default. Editing tools require an explicit tab_id. There is no whole-document replace, so a one-tab edit can never leak into a cover letter or an appendix tab.

  • Normalization ladder. A search tries exact match, then curly/straight quote equivalence, then non-breaking-space and whitespace-run equivalence, then soft-hyphen stripping, and reports which rung matched. A zero-match result includes the nearest near-miss span it found.

  • Match-count guard. expected_matches defaults to 1. If the real count differs, the tool makes no edit and returns every match location.

  • Revision preconditions. Writes carry writeControl.requiredRevisionId from the pre-read, so a document that changed underneath the operation is rejected by the API rather than edited blind. Section ranges from find_sections are stamped with the revision they were computed at and refuse to apply once stale.

  • UTF-16 correct. Match spans are mapped to the UTF-16 code units the Docs API indexes by, so emoji, combining marks, and other astral characters don't shift an edit onto the wrong text.

  • Audit trail. Every mutation appends a line to a local JSONL log. The append is best-effort: it never fails a write, and if it can't be written the evidence says so (audit_logged: false).

Evidence by family

The guarantee is not one universal payload — it is a per-family invariant. Each family re-reads the document after the write and proves the property that family is responsible for. Every mutating tool also carries revision_before, revision_after, and audit_logged.

Family

Tools

Proves

Text edit

replace_text

match_count equals expected_matches; rung names the normalization pass that matched; before/after are ±200-char excerpts of the edited span, the after re-read post-write

Style edit

format_text

runs_before/runs_after — the actual textRun style flags overlapping each matched span, not a text diff; content_mutated: false proven by compiled_request_kinds containing only updateTextStyle; style_mutated false on an idempotent re-run (no write is issued)

Markdown range

replace_range_markdown, replace_tab_markdown, append_markdown

structural_match (the written markdown round-trips — including list nesting depth, ordered-vs-unordered, and link targets), input_blocks vs post_blocks counts, and a structural_diff list naming any mismatch; every response also carries write_status (not_written / written_unverified / written_verified) and retry_safe

Structural

insert_image

inline_object_confirmed — a post-write scan found the inline object at the anchor paragraph

Comment state

add_anchored_comment, reply_to_comment, resolve_comment

the re-queried resolved flag, reply_count, content, quoted_text, and author — a resolve that didn't land returns COMMENT_STILL_OPEN, never success

Table

replace_table_row, insert_table

replace_table_row: row_before/row_after re-read with cells_match; insert_table: table_confirmed plus the confirmed dimensions and first_row

The read and sync tools (read_document, list_tabs, find_sections, list_open_items, get_comment_thread, diff_tab_vs_file, list_tables, get_table) make no changes and carry no applied/evidence payload. export_pdf is also a read/export tool in this sense — it returns file facts (bytes_written, sha256, page_count) rather than an applied key, since nothing in the document changes.

Dry run

Eight mutating tools (replace_text, format_text, replace_range_markdown, replace_tab_markdown, append_markdown, insert_image, replace_table_row, insert_table) accept dry_run=true. No API write is issued; the response carries applied: false, an empty revision_after (no write, so no new revision), audit_logged: false, and — for replace_text — a predicted after excerpt computed by splicing the replacement into the pre-read, or — for format_text — a predicted runs_after computed by overlaying the requested style onto the pre-read runs. format_text additionally never issues a write at all when the matched text already carries every requested style value, dry run or not — that's the tool's normal idempotent no-op path, not specific to dry_run. For replace_table_row and insert_table, dry_run is authoritative for index validity: the same assembled request list is index-simulated whether dry_run is true or false, so a passing dry run always means the real write will pass too. Use it to confirm a locate resolves to the right span before committing the edit.

For the three markdown tools, dry_run is also authoritative for structure prediction (issue #65): before any batchUpdate, the compiled requests' own predicted block structure — nesting, ordered-vs-unordered, headings, tables — is compared against the parsed input markdown, identically in dry_run and the real write. A mismatch refuses with STRUCTURE_PREDICTION_FAILED before the document is touched, rather than mutating it and only then discovering post-write verification would have failed. Every response from these three tools — dry run, refused, or written — carries write_status, one of not_written (dry run, or a pre-flight refusal: INDEX_SIMULATION_FAILED, STRUCTURE_PREDICTION_FAILED, or the structural-loss guardrail), written_unverified (a batchUpdate was sent and accepted, but the post-write re-read did not confirm it matched — VERIFICATION_FAILED), or written_verified (confirmed) — plus a retry_safe boolean (false only for written_unverified, since a caller that retries a call whose mutation status is unconfirmed risks a second mutation on top of an unconfirmed first one; there is no automatic rollback — Docs has no revision-restore endpoint, and a compensating markdown rewrite would itself be lossy, so needs_manual_restore: true still means restoring from Docs version history). write_status/retry_safe are additive: the pre-existing applied field keeps its documented meaning unchanged.

All eight require a suggestion-free target tab. Every mutating tool computes its write indices against a suggestionsViewMode=PREVIEW_WITHOUT_SUGGESTIONS read, but the actual write always lands in the document's real index space, which includes pending suggestions. If the target tab has a pending suggested insertion or deletion, those two index spaces diverge and a write would land at the wrong offset — so every mutating tool refuses with SUGGESTIONS_PRESENT instead (both in dry_run and live), rather than risking a silent, wrong-offset write (issue #56). Accept or reject the pending suggestion in the Docs UI first, then retry.

Tools

Twenty focused tools, each described by when to reach for it, replace the slice of a 150-tool Workspace server that document workflows actually use.

Reading and structure

Tool

What it does

read_document

Read a tab as markdown, as structured positions and style runs, or as a headings-only outline

list_tabs

List tab IDs, titles, and nesting

find_sections

Find headings and return their ranges, stamped with the document revision

list_tables

List every top-level table in a tab, with position, size, and preceding-heading context

get_table

Read one table's full cell grid

Editing (verified, tab-scoped)

Tool

What it does

replace_text

Find/replace within a tab, with the normalization ladder and match guard

format_text

Apply bold/italic/underline to a matched text span via updateTextStyle only — no content mutation, safe inside merged-cell tables

replace_range_markdown

Replace a section range with markdown

replace_tab_markdown

Replace a whole tab's content with markdown

append_markdown

Append markdown to a tab

insert_image

Insert an image at a quoted anchor or heading

replace_table_row

Overwrite one row of an existing table with plain-text cells, in place

insert_table

Insert a new table populated from rows, anchored like insert_image

Comments and suggestions

Tool

What it does

list_open_items

Open comments and pending suggested edits; pass tab_id or include_all_tabs=true

get_comment_thread

Read a comment's full reply chain

add_anchored_comment

Add a comment anchored to quoted text

reply_to_comment

Reply to a comment

resolve_comment

Resolve a comment, re-query it, and confirm it actually closed

Sync and export

Tool

What it does

diff_tab_vs_file

Diff a tab's markdown against a local file

export_pdf

Export the whole document as a PDF to a local path, with a best-effort render-measured page count

Status

Built incrementally; each tool ships with its verification and tests rather than as a stub.

Area

State

OAuth (verified-googledocs-mcp auth), token cache

done

read_document, list_tabs, find_sections

done

Verification kernel (locator, error envelope, audit)

done

replace_text (verified) + enforcement middleware

done

Comment tools + list_open_items

done

Markdown write tools + diff_tab_vs_file

done

Table tools (list_tables, get_table, replace_table_row, insert_table) + export_pdf

done; ships in 0.2.0

format_text (style-only verified edit)

done; ships in 0.2.0

Live acceptance gate

done for the initial release — report; rerun before release

PyPI packaging + publish workflow

done; first release v0.1.0

MCP registry listing

published with v0.1.0

Install

The server talks to Google with your own OAuth credentials, so setup is a one-time Google Cloud step, then registering the server with your MCP client.

1. Google Cloud project (OAuth credentials)

  1. Create a Google Cloud project and enable the Google Docs API and Google Drive API (APIs & Services → Library).

  2. Configure the OAuth consent screen: User type External, publishing status Testing, and add your own Google account under Test users. (Testing mode is the point — the app stays private to the test users you list; you never submit it for Google verification.)

  3. Create an OAuth client ID of type Desktop app and download the client secret JSON to ~/.config/verified-googledocs-mcp/credentials.json. (Override the location with VERIFIED_GOOGLEDOCS_MCP_CREDENTIALS.)

2. Authorize once, in a terminal

uvx verified-googledocs-mcp auth

This opens a browser and completes consent. Because the app is unverified and in Testing, Google shows a "Google hasn't verified this app" screen — click Advanced → Go to verified-googledocs-mcp (unsafe) and continue. This is expected for a personal Desktop client; you are granting access to your own app, running locally as you. It then caches a refreshable token at ~/.config/verified-googledocs-mcp/token.json. Auth runs only here, never inside the server, because MCP clients start the server headless.

3. Run it

uvx verified-googledocs-mcp           # downloads + runs in one step
# or: pip install verified-googledocs-mcp

Then register the server with your MCP client.

From source. To run from a local clone instead:

git clone https://github.com/michaelrobertsutton/verified-googledocs-mcp
cd verified-googledocs-mcp
uv run verified-googledocs-mcp

Claude Code

A project-local .mcp.json is included in the repo. Clone and open the project and Claude Code picks it up automatically — no manual config required:

git clone https://github.com/michaelrobertsutton/verified-googledocs-mcp
cd verified-googledocs-mcp
claude  # .mcp.json is loaded automatically

Use it across all your projects (user scope). Register it once at user scope:

claude mcp add verified-googledocs-mcp --scope user -- uvx verified-googledocs-mcp

This writes to ~/.claude.json and makes the server available in every Claude Code session on this machine. If uvx is not on Claude Code's PATH, use the full path (find it with which uvx).

Claude Desktop and other clients

Most clients use the standard mcpServers config block. Add the following to your client's config file:

{
  "mcpServers": {
    "verified-googledocs-mcp": {
      "command": "uvx",
      "args": ["verified-googledocs-mcp"]
    }
  }
}

PATH note for headless clients: Claude Desktop and similar clients launch the server as a subprocess with a minimal PATH that may not include Homebrew or user-local bins. If uvx is not found, use its full path ("command": "/opt/homebrew/bin/uvx"). Find it with which uvx. On Apple Silicon the Homebrew prefix is /opt/homebrew; on Intel Mac it is /usr/local.

Startup-timeout note. The first uvx launch downloads the package and its dependencies, which can exceed a client's MCP startup timeout and surface as a failed connection. Pre-warm the cache once in a terminal by running the auth command (uvx verified-googledocs-mcp auth) — you do this anyway, and it installs the package into the uvx cache so the client's launch is fast.

From source. If you prefer to run from a local clone instead of PyPI:

{
  "mcpServers": {
    "verified-googledocs-mcp": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "verified-googledocs-mcp"],
      "cwd": "/path/to/verified-googledocs-mcp"
    }
  }
}

Logs / stderr. The server logs to stderr, which MCP clients capture rather than show inline. If a connection or a tool call fails, check the client's MCP logs — for Claude Desktop on macOS, ~/Library/Logs/Claude/mcp*.log. An AUTH_EXPIRED envelope there means the token is missing or expired; re-run the auth command.

The server uses the documents and drive scopes (comments require Drive). The credentials path is overridable with VERIFIED_GOOGLEDOCS_MCP_CREDENTIALS.

Security and permissions

This is a single-user, local server. It runs as you, over stdio, launched by your MCP client; there is no network listener, no hosted service, and no shared credentials. It acts entirely with your own Google authority.

  • Scopes. It requests documents and drive. The full drive scope is broader than editing alone needs, but the comment and suggestion tools (listing, replying to, and resolving comments on documents you already have) operate through the Drive API on arbitrary existing files, which the narrower drive.file scope cannot reach. drive is the minimum that covers the full tool set; if you don't need the comment tools, a fork could drop to a narrower scope.

  • Credentials at rest. The OAuth client secret lives at ~/.config/verified-googledocs-mcp/credentials.json; the cached token (including the refresh token) is written to ~/.config/verified-googledocs-mcp/token.json with owner-only permissions (0600, under a 0700 directory). Treat both as secrets: a leaked refresh token grants your full drive+documents access until you revoke it in your Google Account's security settings. Neither file is ever committed (both are gitignored).

  • Audit log. Every mutation appends to ~/.local/state/verified-googledocs-mcp/audit.jsonl (also 0600). Each line records the timestamp, document ID, tab ID, tool name, and the evidence payload — which includes before/after content excerpts. To log the metadata without the excerpts, set the environment variable VERIFIED_GOOGLEDOCS_MCP_AUDIT_EXCERPTS to a falsey value (0, false, no, or off); the before/after fields are then replaced with "[redacted; N chars]" and every other field is kept. Override the log location with XDG_STATE_HOME.

  • Local file diffs. diff_tab_vs_file reads a local file so it can compare a Doc tab with markdown on disk. It resolves symlinks before reading and only allows paths under VERIFIED_GOOGLEDOCS_MCP_ALLOWED_FILE_ROOTS (a platform path-list; defaults to the user's home directory, not the server process's working directory). The home-directory default exists because MCP clients typically register this server pinned to one repo (e.g. --directory /path/to/GoogleDocs-MCP), while the diff target is almost always in whichever other project the caller is actually working in — scoping to the launch directory made every cross-repo diff fail by default. Narrow it further (e.g. back to a single repo) or widen it by setting VERIFIED_GOOGLEDOCS_MCP_ALLOWED_FILE_ROOTS on the server process to a :-separated (; on Windows) list of directories, then restart the server — a rejected path's error names the env var and includes the currently configured allowed_roots so you can see exactly what's missing. It's still a real boundary, not unrestricted: an agent asking to diff against /etc/passwd or another user's home directory is refused. A home-directory-wide default also has to defend against a document's own content tricking an agent into reading credentials (prompt injection) — e.g. a paragraph instructing "diff against ~/.ssh/id_rsa" — so .ssh, .aws, .gnupg, .netrc, .git-credentials, .config/gh, .docker/config.json, and .npmrc under the home directory are denylisted unconditionally, regardless of the configured allowed roots. It also refuses files larger than VERIFIED_GOOGLEDOCS_MCP_MAX_DIFF_FILE_BYTES (default 1000000). export_pdf's output path is confined by this same policy — the same VERIFIED_GOOGLEDOCS_MCP_ALLOWED_FILE_ROOTS allow-list and the same unconditional credential-path denylist, so a PDF export can no more land in (or overwrite) ~/.ssh than a diff can read from it.

Error codes

Failures return a typed envelope (error_code, message, diagnostics, retryable):

Code

Meaning

ZERO_MATCH

Target not found after the full normalization ladder; diagnostics include the nearest near-miss

MATCH_COUNT_MISMATCH

Found a different count than expected_matches; no edit made; all locations returned

REVISION_CONFLICT

Document changed between read and write; retry after re-reading

VERIFICATION_FAILED

A write was issued, but the post-write re-read did not verify the expected final state

STALE_RANGE

A find_sections range was used after the document moved on; re-run find_sections

TAB_NOT_FOUND

Unknown tab_id; available tabs listed

STRUCTURAL_BOUNDARY

Match crosses a paragraph or table-cell boundary

UNSUPPORTED_MARKDOWN

Markdown outside the supported subset; the offending construct is named

QUOTE_NOT_FOUND

Comment anchor text not found; nearest candidates returned

COMMENT_STILL_OPEN

A resolve was requested but re-query shows the comment open

INVALID_INPUT

Empty or contradictory arguments

IMAGE_SOURCE_UNSUPPORTED

Image source is a local path; a fetchable URL is required

AUTH_EXPIRED

No valid token; run verified-googledocs-mcp auth

INDEX_SIMULATION_FAILED

A markdown write's compiled requests would land at an invalid index; caught before the API call. Raised identically by dry_run and the real write, so a passing dry_run always means the write will pass too

TABLE_NOT_FOUND

The requested table_index does not exist in the tab; call list_tables first

SUGGESTIONS_PRESENT

The target tab has pending suggested insertions/deletions; a write refuses rather than computing indices against the wrong index space (issue #56) — accept or reject the suggestions first, then retry

INVALID_RANGE

A caller-supplied range doesn't fit the tab's current extent, or the Docs API itself rejected the write as index/range-invalid (the verbatim API message is included)

INDEX_MODEL_DIVERGENCE

A text run's computed UTF-16 length disagrees with the Docs API's reported endIndex; offsets from that read cannot be trusted

STRUCTURE_PREDICTION_FAILED

A markdown write's compiled requests would not produce the input's block structure (nesting, ordered-vs-unordered, headings, tables) — caught before the API call by predicting the requests' own effect and comparing it against the parsed input (issue #65). Raised identically by dry_run and the real write, so a passing dry_run always means the write will verify too

Development

uv run --extra dev pytest                 # unit tests (offline) + coverage
uv run --extra dev ruff check src tests   # lint
uv run --extra dev ruff format src tests  # format
uv run --extra dev mypy src               # type check

Unit tests run against synthetic Docs API fixtures and an in-memory MCP client, so the full suite is offline (it never runs the live tests). The live acceptance suite (under tests/live/) runs with pytest tests/live --run-live against a real scratch document and needs OAuth credentials; it is the pre-release gate and never runs in CI — see docs/acceptance-report.md.

See docs/architecture.md for the module map and the verification pipeline, PRD.md for the full specification, docs/cutover.md to migrate off a general Workspace MCP server, and CONTRIBUTING.md to build on it.

Limitations

  • Accepting or rejecting suggested edits is not possible through the generally-available Google Docs API. This server makes suggestions visible alongside comments; acting on them stays a manual step in the Docs UI. As of July 2026 Google documents accept/reject/delete suggestion requests — but only under the Workspace Developer Preview Program; the stable v1 surface rejects them (verified 2026-07-17). Verified accept_suggestion/reject_suggestion tools become buildable when that reaches GA.

  • Single user, local. stdio transport, one cached token, no hosted or multi-user mode.

  • Docs only. Gmail, Calendar, and Sheets are out of scope by design.

  • Markdown is a fixed subset (headings, bold/italic, lists, tables, links). Anything outside it is rejected with a clear error rather than approximated.

License

MIT, © 2026 Michael Sutton.

Available Tools

20 tools
add_anchored_commentA

Add a comment to a document, validated against a quoted passage.

Use this tool when you need to create a comment on specific text in a document tab. The quote must exist in the tab — the tool locates it via the same normalization ladder as replace_text and returns QUOTE_NOT_FOUND with nearest candidate anchors if the quote is absent.

NOTE: The Drive API may render the created comment as document-level even when quotedFileContent is supplied. This behaviour is pending confirmation from a live anchoring spike; for now the comment is created with the quote embedded in its content and the tool returns comment-state evidence.

Returns comment-state evidence: applied, comment_id, resolved, reply_count, content, quoted_text, audit_logged.

Errors: QUOTE_NOT_FOUND – quote not found in the tab; nearest candidates listed INVALID_INPUT – empty body or quote TAB_NOT_FOUND – tab_id not in document

Inputs: body (required), quote (required), doc_id (required), tab_id (required). Returns: object

append_markdownA

Append compiled markdown at the end of a document tab.

Use this tool when you need to add new content at the end of a tab without disturbing existing content. Inserts before the final trailing newline.

Set dry_run=true to validate and preview without writing.

The returned payload (applied, revisions, structural_match, input_blocks/ post_blocks) is itself the confirmation the write landed — it already re-read the document and diffed it against the input. A follow-up read_document to double-check is a redundant round-trip; only re-read if you need the content for a subsequent step.

Errors: UNSUPPORTED_MARKDOWN – markdown contains an unsupported construct TAB_NOT_FOUND – tab_id not in document REVISION_CONFLICT – document changed mid-call; re-read and retry

Inputs: doc_id (required), tab_id (required), markdown (required), dry_run. Returns: object

diff_tab_vs_fileA

Export a document tab as markdown and diff against a local file.

Use this tool when you need to compare a Google Doc tab against a local markdown file. The server reads the file directly (it runs locally). Returns a structured diff with tagged hunks (equal/insert/delete/replace) and a unified diff string.

This is a read-only tool — it makes no changes to the document or file.

Returns: doc_id, tab_id, file_path, revision_id, identical (bool), hunks (list of tagged diff blocks), unified_diff (unified diff string)

Errors: TAB_NOT_FOUND – tab_id not in document INVALID_INPUT – file not found at file_path

Inputs: doc_id (required), tab_id (required), file_path (required). Returns: object

export_pdfA

Export the whole document as a PDF to a local path.

Use this tool when a caller needs a render-measured page count to check against a page limit, or simply needs a PDF copy on disk. Drive's export is doc-level, not tab-scoped, so this exports every tab in the document, not just one.

output_path must fall inside VERIFIED_GOOGLEDOCS_MCP_ALLOWED_FILE_ROOTS (defaults to the user's home directory) and must never resolve to a credential path; its parent directory must already exist. page_count is best-effort and is None when the PDF hides its page markers inside a compressed stream — never a guessed number. Drive refuses exports whose PDF would exceed roughly 10 MB.

This is a read/export tool: nothing in the document changes, so the return value has no "applied" key. Returns doc_id, output_path, bytes_written, sha256, page_count, existed_before, audit_logged.

Errors: INVALID_INPUT – a bad output_path (missing parent directory, outside the allowed roots, a denylisted credential path, or an existing target that isn't a regular file), or Drive refused the export (not found, permission denied, or the size limit) AUTH_EXPIRED – no valid token

Inputs: doc_id (required), output_path (required). Returns: object

find_sectionsA

Find headings in a document tab and return their document ranges.

Use this tool when you need to locate a section by its heading text before performing a targeted edit on that section. The returned ranges carry a computed_at_revision stamp; range-editing tools in later milestones will refuse stale ranges (ranges computed against an older document revision). Call find_sections immediately before editing — do not cache returned ranges across separate edits.

Matching is case-insensitive and substring-based: a query of "intro" will match a heading "Introduction".

Inputs: doc_id (required), tab_id (required), heading (required). Returns: object

format_textA

Apply character styling (bold/italic/underline) to a matched text span.

Use this tool when you need to style existing text in place — bold a phrase, un-bold it, italicize it — without touching its content. Unlike replace_text (which deletes and reinserts text and cannot express styling), this tool compiles ONLY updateTextStyle requests, so it is safe to use inside a table cell even when the table has hand-merged cells: no delete/insert/merge request is ever compiled, and the response reports every compiled_request_kinds entry so that claim is checked, not just asserted.

Call list_tabs first to get the tab_id, then read_document to confirm the text you want to style is present as-is. style maps any of bold/italic/underline to true or false — e.g. {"bold": true} to bold, {"bold": false} to un-bold. At least one key is required.

Matching uses the same normalization ladder and match-count guard as replace_text (exact → curly/straight quote equivalence → NBSP/whitespace collapse → soft-hyphen strip; refuses unless the match count equals expected_matches). If the matched text already carries every requested style value, the call is a no-op: it returns applied: true, style_mutated: false, and issues no write at all (so an idempotent re-run does not create a new document revision).

The response includes, per matched span, the actual textRun style flags before and after (runs_before/runs_after) — not a markdown or plain-text diff, since genuine bold and a literal **word** both render identically as text. content_mutated is always false, proven by compiled_request_kinds containing only updateTextStyle. Style reflects textRun.textStyle only: a heading rendered bold by its named/paragraph style rather than an explicit run style will not show bold: true here, matching every other style read in this server. A pending style-only suggestion on the target span is allowed through (see SUGGESTIONS_PRESENT below) and evidence reflects the base, non-suggested style, same as every read in this server.

Set dry_run=True to preview the operation without writing; the response carries applied: false and a predicted runs_after (the requested fields overlaid on the current runs) but makes no API call.

Errors are returned as typed envelopes with error_code, message, diagnostics, and retryable so the caller can act on them precisely: ZERO_MATCH – find string not found; near-miss span included MATCH_COUNT_MISMATCH – wrong number of matches; all locations listed STRUCTURAL_BOUNDARY – match crosses a paragraph or table-cell boundary REVISION_CONFLICT – document changed mid-call; re-read and retry VERIFICATION_FAILED – the write landed but could not be confirmed on re-read; check diagnostics before assuming a manual restore is needed — a concurrent edit near the target text is a common, benign cause INVALID_INPUT – empty find, or style is empty/unknown-key/non-bool TAB_NOT_FOUND – tab_id not in document; available tabs listed SUGGESTIONS_PRESENT – tab has a pending suggested insertion/deletion (not a style suggestion); accept/reject it in the Docs UI first, then retry

Inputs: find (required), style (required), doc_id (required), tab_id (required), +2 more. Returns: object

get_comment_threadA

Retrieve the full reply chain for a comment.

Use this tool when you need to read a comment thread in full before deciding on a response or resolution. Returns the comment content, all replies, quoted text, resolved status, and author.

Requires both the doc_id (the Google Doc's file ID) and the comment_id from the Drive API.

Inputs: doc_id (required), comment_id (required). Returns: object

get_tableA

Read one table's full cell grid.

Use this tool to read every cell of a specific table — identified by the table_index returned from list_tables — before editing a row with replace_table_row.

Returns doc_id, tab_id, revision_id, table_index, rows, columns, cells (the row-major cell grid, list[list[str]]), and has_merged_cells.

Errors: TAB_NOT_FOUND – tab_id not in document TABLE_NOT_FOUND – table_index does not exist in the tab AUTH_EXPIRED – no valid token

Inputs: doc_id (required), tab_id (required), table_index (required). Returns: object

insert_imageA

Insert an inline image after the paragraph containing anchor text.

Use this tool when you need to add an image to a specific location in a document tab. The anchor resolves via the same normalization ladder as replace_text (exact → curly/straight quotes → NBSP/whitespace → soft-hyphen). The image is inserted as an inline object in a new paragraph immediately after the paragraph containing the resolved anchor.

source must be a publicly fetchable URL (http/https). Local file paths are rejected with IMAGE_SOURCE_UNSUPPORTED — the Docs API fetches the image from the URL directly and cannot access local files.

Set dry_run=true to preview the resolved anchor position without writing.

Returns structural evidence: applied, revision_before/after, inline_object_confirmed (whether the post-read confirms an inline object near the anchor paragraph), audit_logged.

Errors: QUOTE_NOT_FOUND – anchor not found; nearest candidates listed IMAGE_SOURCE_UNSUPPORTED – source is a local path, not a URL INVALID_INPUT – anchor is inside a table (anchor must be body text) TAB_NOT_FOUND – tab_id not in document REVISION_CONFLICT – document changed mid-call; re-read and retry SUGGESTIONS_PRESENT – tab has pending suggested edits; accept/reject them in the Docs UI first, then retry

Inputs: anchor (required), doc_id (required), source (required), tab_id (required), +1 more. Returns: object

insert_tableA

Create a new table populated from rows, inserted after an anchor.

Use this tool to add a brand-new table to a document tab. rows is a list of rows of plain strings — no markdown, no bolding applied — with the first row treated as the header positionally. anchor must be exact text present in the tab; the table is inserted after the paragraph containing it, the same anchoring insert_image uses.

Set dry_run=true to preview without writing. dry_run is authoritative for index validity: the same assembled request list is index-simulated whether dry_run is true or false, and the suggestion guard below runs identically on both paths, so a passing dry_run means the real write will pass too — provided nothing about the document changes in between (a new suggestion, a concurrent edit) before the real write is issued.

Returns evidence: applied, table_index (use it for follow-up replace_table_row calls), rows, columns, first_row, table_confirmed, revision_before, revision_after, audit_logged.

Errors: TAB_NOT_FOUND – tab_id not in document QUOTE_NOT_FOUND – anchor not found; nearest candidates listed INVALID_INPUT – empty or ragged rows, a non-string cell, or an anchor that falls inside a table REVISION_CONFLICT – document changed mid-call; re-read and retry SUGGESTIONS_PRESENT – tab has pending suggested edits; accept/reject them in the Docs UI first, then retry VERIFICATION_FAILED – post-write re-read did not confirm the inserted table at the expected location INDEX_SIMULATION_FAILED – compiled requests would land at an invalid index; caught before the API call AUTH_EXPIRED – no valid token

Inputs: rows (required), anchor (required), doc_id (required), tab_id (required), +1 more. Returns: object

list_open_itemsA

List all open comments and pending suggested edits on a document.

Use this tool when you need a single unified view of all open review items on a document. Returns both Drive-level comments (labeled scope='document') and per-tab suggested edits in one response.

Comments come from the Drive API and cannot be attributed to a specific tab — Drive comment anchors are opaque. If tab_id is provided it filters the suggestions returned to that tab only. To include suggestions from every tab, set include_all_tabs=true. Comments are always returned document-wide regardless of tab_id.

Suggestions are extracted from the raw Docs JSON (suggestedInsertionIds / suggestedDeletionIds / suggestedTextStyleChanges) and are per-tab. The document is fetched with suggestionsViewMode=SUGGESTIONS_INLINE so that suggestion fields are populated.

Inputs: doc_id (required), tab_id, include_all_tabs. Returns: object

list_tablesA

List every top-level table in a document tab.

Use this tool to discover and address the tables in a tab before calling get_table or replace_table_row — both require a table_index, which this tool assigns in document order.

Returns tables: a list of table_index, rows, columns, start_index, end_index, preceding_heading (the nearest heading above the table, or null if none), first_row, and has_merged_cells — plus doc_id, tab_id, and revision_id.

Errors: TAB_NOT_FOUND – tab_id not in document AUTH_EXPIRED – no valid token

Inputs: doc_id (required), tab_id (required). Returns: object

list_tabsA

List the tabs in a Google Doc.

Use this tool first when you need to read or edit a document but do not yet know its tab structure. Returns tab IDs, titles, nesting level, and index. Required before calling read_document or find_sections because every tool in this server requires an explicit tab_id.

For documents created before Google's tabbed-docs feature, returns a single synthetic tab with id "_body" that covers the whole document.

Inputs: doc_id (required). Returns: object

read_documentA

Read the content of a specific tab in a Google Doc.

Use this tool when you need to read the text, headings, tables, or structure of a document tab. Call list_tabs first to get the tab_id.

format="markdown" (default): returns markdown text. Out-of-subset elements (images, smart chips, footnotes) appear as stable placeholder tokens and are listed in lossy_elements.

format="structured": returns paragraph positions and style runs from the raw Docs JSON, suitable for computing exact edit ranges.

format="outline": returns only the tab's headings (level, text, start_index, end_index), in document order. Use this when you only need geometry — e.g. to see the tab's section structure before deciding where to write — without pulling the whole tab as markdown. If you already know which heading you want to target, find_sections is the lighter tool: it filters to matches and returns section (not just heading) ranges.

Drive's files.export cannot scope to a single tab, which is why this server uses its own Docs JSON converter for markdown output.

Inputs: doc_id (required), tab_id (required), format. Returns: object

replace_range_markdownA

Replace a document range with compiled markdown.

Use this tool when you need to replace a section of a document with new markdown content. Obtain start_index, end_index, and computed_at_revision from find_sections. The range stamp is validated against the current document revision — a stale stamp raises STALE_RANGE ("re-run find_sections").

The structural guardrail inventories tables, images, chips, and footnotes inside the target range before writing. If the replacement markdown does not account for them the write is refused unless allow_structural_loss=true. A blast-radius check compares structural element counts outside the edited range pre/post; any change there is a hard failure.

Set dry_run=true to validate and preview without writing.

The returned payload (applied, revisions, structural_match, input_blocks/ post_blocks) is itself the confirmation the write landed — it already re-read the document and diffed it against the input. A follow-up read_document to double-check is a redundant round-trip; only re-read if you need the content for a subsequent step.

Errors: STALE_RANGE – range stamp is outdated; re-run find_sections UNSUPPORTED_MARKDOWN – markdown contains an unsupported construct INVALID_INPUT – structural guardrail refused or blast-radius violation INVALID_RANGE – start_index/end_index don't fit the tab's current extent, or the Docs API rejected the write as index-invalid TAB_NOT_FOUND – tab_id not in document REVISION_CONFLICT – document changed mid-call; re-read and retry SUGGESTIONS_PRESENT – tab has pending suggested edits; accept/reject them in the Docs UI first, then retry

Inputs: doc_id (required), tab_id (required), markdown (required), end_index (required), +4 more. Returns: object

replace_table_rowA

Replace every cell in one row of an existing table with plain text.

Use this tool — the workhorse for updating existing tables in place — to overwrite one row's cells after locating the table and row with list_tables and get_table. cells are PLAIN STRINGS, not markdown, and the list length must equal the row's column count. Each cell's pre-existing bold/italic/underline style is preserved on the replacement text. The tool refuses tables that contain merged cells and rows where a cell contains a nested table.

Set dry_run=true to preview without writing. dry_run is authoritative for index validity: the same assembled request list is index-simulated whether dry_run is true or false, and the suggestion guard below runs identically on both paths, so a passing dry_run means the real write will pass too — provided nothing about the document changes in between (a new suggestion, a concurrent edit) before the real write is issued.

Returns evidence: applied, table_index, row_index, row_before, row_after, cells_match, revision_before, revision_after, audit_logged. In dry-run mode row_after_preview and planned_requests replace row_after and cells_match.

Errors: TAB_NOT_FOUND – tab_id not in document TABLE_NOT_FOUND – table_index does not exist in the tab INVALID_INPUT – merged cells, a nested table in a target cell, a wrong cell count, or a bad row_index REVISION_CONFLICT – document changed mid-call; re-read and retry SUGGESTIONS_PRESENT – tab has pending suggested edits; accept/reject them in the Docs UI first, then retry VERIFICATION_FAILED – post-write re-read does not match the requested cells INDEX_SIMULATION_FAILED – compiled requests would land at an invalid index; caught before the API call AUTH_EXPIRED – no valid token

Inputs: cells (required), doc_id (required), tab_id (required), row_index (required), +2 more. Returns: object

replace_tab_markdownA

Replace the entire content of a document tab with compiled markdown.

Use this tool when you need to completely replace a tab's content with new markdown. tab_id is required and must identify an existing tab.

The structural guardrail refuses writes that would silently lose tables, images, chips, or footnotes unless allow_structural_loss=true.

Set dry_run=true to validate and preview without writing.

The returned payload (applied, revisions, structural_match, input_blocks/ post_blocks) is itself the confirmation the write landed — it already re-read the document and diffed it against the input. A follow-up read_document to double-check is a redundant round-trip; only re-read if you need the content for a subsequent step.

Errors: UNSUPPORTED_MARKDOWN – markdown contains an unsupported construct INVALID_INPUT – structural guardrail refused TAB_NOT_FOUND – tab_id missing or not in document REVISION_CONFLICT – document changed mid-call; re-read and retry SUGGESTIONS_PRESENT – tab has pending suggested edits; accept/reject them in the Docs UI first, then retry

Inputs: doc_id (required), tab_id (required), markdown (required), dry_run, +1 more. Returns: object

replace_textA

Replace occurrences of a text string in a Google Doc tab.

Use this tool when you need to make an exact-text substitution in a document tab. Call list_tabs first to get the tab_id, then read_document to confirm the text you want to replace is present as-is.

The tool locates every occurrence of find using a normalization ladder (exact → curly/straight quote equivalence → NBSP/whitespace collapse → soft-hyphen strip) and refuses the write if the match count does not equal expected_matches. This prevents accidental multi-replacement and duplicate-sentence collapse.

Set dry_run=True to preview the operation without writing; the response carries applied: false and the matched span information but makes no API call.

On success the response carries before/after excerpts (±200 chars), the normalization rung used, pre/post revision IDs, and audit_logged.

Errors are returned as typed envelopes with error_code, message, diagnostics, and retryable so the caller can act on them precisely: ZERO_MATCH – find string not found; near-miss span included MATCH_COUNT_MISMATCH – wrong number of matches; all locations listed REVISION_CONFLICT – document changed mid-call; re-read and retry STRUCTURAL_BOUNDARY – match crosses a paragraph boundary INVALID_INPUT – empty find, or find equals replace TAB_NOT_FOUND – tab_id not in document; available tabs listed SUGGESTIONS_PRESENT – tab has pending suggested edits; accept/reject them in the Docs UI first, then retry (a pending suggestion makes the write's computed indices unsafe — see verified writes, below)

Inputs: find (required), doc_id (required), tab_id (required), replace (required), +2 more. Returns: object

reply_to_commentA

Add a reply to an existing comment thread.

Use this tool when you need to respond to a reviewer comment without resolving it. The reply is added to the thread and the tool re-queries the comment to return post-state evidence.

Returns comment-state evidence: applied, comment_id, resolved, reply_count, content, quoted_text, audit_logged.

Errors: INVALID_INPUT – empty body or comment not found

Inputs: body (required), doc_id (required), comment_id (required). Returns: object

resolve_commentA

Resolve a comment on a document and verify the resolution landed.

Use this tool when you need to mark a reviewer comment as resolved. Resolves via Drive replies.create(action='resolve') — the only mechanism that actually resolves comments in Drive API v3. Using comments.update with resolved=true is silently ignored (resolved is a read-only field), which is the incumbent server's bug.

After issuing the resolve the tool re-queries the comment and returns the actual final state. A comment that is still open after the resolve attempt is reported as COMMENT_STILL_OPEN — never as success.

Returns comment-state evidence: applied, comment_id, resolved, reply_count, content, quoted_text, audit_logged.

Errors: COMMENT_STILL_OPEN – comment did not resolve; post-state included INVALID_INPUT – comment not found

Inputs: doc_id (required), comment_id (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 20 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: reading, writing, styling, commenting, tables, and export are separated cleanly. A few pairs could be confused—read_document with format='outline' overlaps find_sections, and replace_text vs replace_range_markdown both replace content—but the descriptions provide enough guidance to disambiguate.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun (or verb_preposition) pattern in snake_case: list_tabs, read_document, replace_text, append_markdown, resolve_comment, insert_table. The naming style is uniform and predictable across all 20 tools, with no mixed conventions or vague verbs.

    Tool Count4/5

    20 tools is slightly above the typical well-scoped range, but the server covers several distinct sub-domains—document reading, text editing, comments, tables, and export—so the count is reasonable. It is not bloated; each tool addresses a concrete operation, though a few could be consolidated without much loss.

    Completeness4/5

    The toolset covers the core document lifecycle well: read tabs, find sections, replace and append content, style text, manage comments, handle tables, and export PDFs. Minor gaps exist—no delete-section or delete-table operations, no arbitrary insertion of plain text without replacement, and no tab creation/renaming—but these are not critical dead ends for typical editing workflows.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers