google-docs-mcp
CLAUDE.md680 starsChanged 24 days agoMITView on GitHub
FastMCP server with 129 tools for Google Docs, Sheets, Drive, Gmail, Calendar, and Apps Script. appendTableRows is registered in both Docs and Sheets variants under the same name. The server supports Google Shared Drives. All Drive file operations (files.list, files.get, files.create, files.update, files.copy, files.delete, permissions.create) use supportsAllDrives: true and includeItemsFromAllDrives: true (for list operations), enabling agents to query, create, and update documents in shared drives.
The file
We split this claude.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 38
Text targeting: Use textToFind + matchInstance OR startIndex/endIndex
- Very specific: line 48
Retrieve: Use readGoogleDoc with format='markdown' to get document content as markdown
- Very specific: line 50
Apply: Use replaceDocumentWithMarkdown or appendMarkdownToGoogleDoc to write changes back
≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Google Docs MCP Server
FastMCP server with 129 tools for Google Docs, Sheets, Drive, Gmail, Calendar, and Apps Script.
Tool Categories
| Category | Count | Examples |
| Docs | 42 | readDocument, insertText, modifyText, applyTextStyle, insertTable, listComments, listSuggestions, manageSuggestions, ... |
| Drive | 19 | createDocument, searchDriveFiles, moveFile, createMarkdownFile, readMarkdownFile, updateMarkdownFile, ... |
| Sheets | 44 | readSpreadsheet, writeSpreadsheet, createTable, protectRange, addConditionalFormatting, insertChart, ... |
| Gmail | 13 | listMessages, getMessage, sendEmail, trashMessage, modifyMessageLabels, listLabels, createDraft, listDrafts, triageInbox |
| Calendar | 5 | listEvents, createEvent, updateEvent, deleteEvent, quickAddEvent |
| Apps Script | 3 | createAppsScriptProject, getAppsScriptContent, updateAppsScriptContent |
| Utils | 3 | appendMarkdown, replaceDocumentWithMarkdown, replaceRangeWithMarkdown |
appendTableRows is registered in both Docs and Sheets variants under the same name.
Shared Drives Support
The server supports Google Shared Drives. All Drive file operations (files.list, files.get, files.create, files.update, files.copy, files.delete, permissions.create) use supportsAllDrives: true and includeItemsFromAllDrives: true (for list operations), enabling agents to query, create, and update documents in shared drives.
Known Limitations
- Comment anchoring: Programmatically created comments appear in "All Comments" but aren't visibly anchored to text in the UI
- Resolved status: May not persist in Google Docs UI (Drive API limitation)
- fixListFormatting: Experimental, may not work reliably
- Gmail hard delete:
trashMessageonly moves to Trash (reversible). Permanent deletion requires the fullhttps://mail.google.com/scope, which is not requested. - Gmail attachments:
getMessageexposes attachment metadata only — no download of attachment bytes yet. - Gmail draft attachments:
createDraftandupdateDraftattach local files only from the directories inGMAIL_ATTACHMENT_ROOTS. Unset means every attachment is refused. - Gmail send format:
sendEmailis plain-text only. HTML bodies are delivered as literal text. - Calendar scope:
calendar.eventscovers event CRUD only. Cannot create or delete entire calendars. - Calendar recurring events:
updateEventanddeleteEventoperate on the entire series unless you target a specific instance ID fromlistEventswithsingleEvents=true.
Parameter Patterns
- Document ID: Extract from URL:
docs.google.com/document/d/DOCUMENT_ID/edit - Text targeting: Use
textToFind+matchInstanceORstartIndex/endIndex - Colors: Hex format
#RRGGBBor#RGB - Alignment:
START,END,CENTER,JUSTIFIED(not LEFT/RIGHT) - Indices: 1-based, ranges are [start, end)
- Tabs: Optional
tabIdparameter (defaults to first tab)
Markdown Support
Workflow
- Retrieve: Use
readGoogleDocwithformat='markdown'to get document content as markdown - Edit: Modify markdown locally using your preferred editor
- Apply: Use
replaceDocumentWithMarkdownorappendMarkdownToGoogleDocto write changes back
Supported Markdown Features
- Headings:
# H1through###### H6 - Bold:
**bold**or__bold__ - Italic:
*italic*or_italic_ - Strikethrough:
~~strikethrough~~ - Links:
[text](url) - Lists: Bullet (
-,*) and numbered (1.,2.) - Code blocks: Fenced code blocks (
```) rendered as styled 1x1 tables (matching Google Docs' native Code Block building block) - Inline code: Backtick code rendered with monospace font + green color + gray background
- Nested formatting:
***bold italic***,**bold [link](url)**
Markdown Tools
replaceDocumentWithMarkdown
Replaces entire document content with markdown-formatted content.
Parameters:
documentId: The document IDmarkdown: The markdown content to applypreserveTitle(optional): If true, preserves the first heading/titlefirstHeadingAsTitle(optional, default: false): If true, the first# H1is styled as a Google Docs Title instead of Heading 1tabId(optional): Target a specific tab
Example:
# My Document
This is **bold** text with a [link](https://example.com).
- List item 1
- List item 2
- Nested item
## Section 2
More content with _italic_ and ~~strikethrough~~.appendMarkdownToGoogleDoc
Appends markdown content to the end of a document with full formatting.
Parameters:
documentId: The document IDmarkdown: The markdown content to appendaddNewlineIfNeeded(optional, default: true): Add spacing before appended contentfirstHeadingAsTitle(optional, default: false): If true, the first# H1is styled as a Google Docs Title instead of Heading 1tabId(optional): Target a specific tab
Known Limitations for Markdown
- Tables not yet supported in markdown-to-docs conversion
- Images not yet supported in markdown-to-docs conversion
- Complex nested lists (3+ levels) may have formatting quirks
- Maximum practical document size: ~10,000 words (due to Google Docs API batch limits)
Source Files (for implementation details)
| File | Contains |
src/types.ts | Zod schemas, hex color validation, style parameter definitions |
src/googleDocsApiHelpers.ts | findTextRange, executeBatchUpdate, executeBatchUpdateWithSplitting, style request builders |
src/googleSheetsApiHelpers.ts | A1 notation parsing, range/format operations, protected-range helpers, table helpers |
src/markdown-transformer/markdownToDocs.ts | Markdown-to-Google-Docs conversion logic |
src/markdown-transformer/docsToMarkdown.ts | Google-Docs-to-Markdown conversion logic |
src/markdown-transformer/index.ts | Markdown-it configuration and public API |
src/index.ts | Entry point, CLI handling, and MCP server startup |
See Also
README.md- Setup instructions and usage examplesSAMPLE_TASKS.md- 15 example workflows
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

