google-documents-mcp

google-documents-mcp

MCP server for Google Docs - read and edit documents.

Use Cases

Document Q&A: "What does the contract say about termination clauses?" → reads the doc and pulls out the relevant section.

Meeting-to-doc workflow: After a call, reads the Gemini transcript plus follow-up Slack discussion, then updates your team charter with the decisions made.

Release announcement: "Draft a blog post about the new feature based on the GitHub PRs and Slack discussions in #proj-awesome" → synthesizes technical changes into user-facing content.

Daily planning with persistent context: Your AI assistant reads a "planning log" doc at the start of each day, asks about yesterday's progress, helps you identify today's priority, then updates the doc with your plan. Context carries over across sessions - it remembers what you said you'd do and can follow up.

(These are just examples - any workflow that needs document reading or editing can use this. Use in combination with google-drive-mcp for finding files, deleting, comments, and sharing permissions.)

Setup

1. Create Google OAuth credentials

• Go to Google Cloud Console
• Create a new project (or use existing)
• Enable the Google Docs API
• Go to APIs & Services → OAuth consent screen, set up consent screen
• Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
• Choose Web application
• Add http://localhost:3000/callback to Authorized redirect URIs
• Note your Client ID and Client Secret

2. Run the server

GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start

The server runs on http://localhost:3000 by default. Change with PORT=3001.

3. Add to your MCP client

claude mcp add --transport http google-documents-mcp http://localhost:3000/mcp

Architecture

This server acts as an OAuth proxy to Google:

graph LR
    A[MCP client] <--> B[google-documents-mcp] <--> C[Google OAuth/API]

• Server advertises itself as an OAuth authorization server via /.well-known/oauth-authorization-server
• /register returns the Google OAuth client credentials
• /authorize redirects to Google, encoding the client's callback URL in state
• /callback receives the code from Google and forwards to the client's callback
• /token proxies token requests to Google, injecting client credentials
• /mcp handles MCP requests, using the bearer token to call Google Docs API

The server holds no tokens or state - it just proxies OAuth to Google.

Tools

Tool	Description
document_get_raw	Get full raw JSON structure (all tabs, formatting, headers, footers, styles)
document_get_text	Get plain text content of all tabs
document_create	Create a new blank document
document_batch_update	Apply multiple edits atomically (insert, delete, format, etc.)
document_append	Append text to end of document
document_insert	Insert text at a specific index
document_replace	Find and replace text

batch_update Request Types

The document_batch_update tool supports these operations:

• insertText - Insert text at a location
• deleteContentRange - Delete a range of content
• replaceAllText - Find and replace all occurrences
• insertInlineImage - Insert an image
• insertTable - Create a table
• insertTableRow / insertTableColumn - Add rows/columns to tables
• deleteTableRow / deleteTableColumn - Remove rows/columns from tables
• insertPageBreak - Add a page break
• createNamedRange / deleteNamedRange - Manage named ranges
• createParagraphBullets / deleteParagraphBullets - Manage bullet lists

Google Docs API Scopes

• documents - Full access to read and edit documents

Contributing

Pull requests are welcomed on GitHub! To get started:

• Install Git and Node.js
• Clone the repository
• Install dependencies with npm install
• Run npm run test to run tests
• Build with npm run build

Releases

Versions follow the semantic versioning spec.

To release:

• Use npm version <major | minor | patch> to bump the version
• Run git push --follow-tags to push with tags
• Wait for GitHub Actions to publish to the NPM registry.