Google Docs

Google Docs Workspace MCP Server

An MCP (Model Context Protocol) server that provides Google Docs integration for AI assistants. Supports both personal Google accounts (via OAuth2) and Google Workspace accounts (via service account with domain-wide delegation).

Features

• Read documents: Fetch full body or just the heading outline of a Google Doc, by document ID or shareable URL
• Create documents: Create new Google Docs with optional initial content
• Edit documents:
• Append text to the end of a document
• Insert text at a specific index
• Replace all occurrences of a string
• Apply raw documents.batchUpdate requests for full structural control
• Delete documents: Move to Drive trash by default, or permanently delete with an explicit flag
• Export documents: Export to Markdown, HTML, plain text, PDF, DOCX, ODT, RTF, or EPUB
• Share documents (gated): Grant read/comment/write access to a user, group, domain, or anyone with a link
• Two auth methods: OAuth2 for personal accounts, service account for Google Workspace
• Permission gating: Restrict tools by group via GOOGLE_DOCS_ENABLED_TOOLGROUPS

Installation

npm install google-docs-workspace-mcp-server

Or run directly with npx:

npx google-docs-workspace-mcp-server

Authentication

This server supports two authentication modes. Choose the one that matches your account type.

Option 1: OAuth2 (Personal Google Accounts)

Use this for personal @gmail.com accounts or any Google account without Workspace admin access.

Prerequisites

1. Go to Google Cloud Console
2. Create or select a project
3. Enable the Google Docs API and the Google Drive API
4. Configure the OAuth consent screen:

• Choose External user type
• Add yourself as a test user
• Publish the app (click "Publish" on the consent screen) to prevent refresh tokens from expiring every 7 days. No full Google verification is needed for personal use.

1. Create OAuth 2.0 credentials:

• Choose Desktop app as the application type
• Important: Create new credentials _after_ publishing the app

1. Copy the Client ID and Client Secret

Getting a Refresh Token

Run the built-in setup command:

npx google-docs-workspace-mcp-server oauth-setup <client_id> <client_secret>

You can also pass credentials via environment variables:

GOOGLE_DOCS_OAUTH_CLIENT_ID=... GOOGLE_DOCS_OAUTH_CLIENT_SECRET=... npx google-docs-workspace-mcp-server oauth-setup

Port conflict? If port 3000 is already in use, specify a different port:

PORT=3001 npx google-docs-workspace-mcp-server oauth-setup <client_id> <client_secret>

Desktop app credentials automatically allow http://localhost redirects on any port, so no additional Google Cloud Console configuration is needed.

This will open your browser for Google sign-in and print the refresh token. You only need to do this once — the refresh token does not expire (as long as the OAuth consent screen is published).

Environment Variables (OAuth2)

Claude Desktop Configuration (OAuth2)

{

"mcpServers": { "google-docs": { "command": "npx", "args": ["google-docs-workspace-mcp-server"], "env": { "GOOGLE_DOCS_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com", "GOOGLE_DOCS_OAUTH_CLIENT_SECRET": "your-client-secret", "GOOGLE_DOCS_OAUTH_REFRESH_TOKEN": "your-refresh-token" } } } }

Option 2: Service Account (Google Workspace)

Use this for Google Workspace organizations where a domain admin can grant domain-wide delegation.

Prerequisites

1. Go to Google Cloud Console
2. Create or select a project
3. Enable the Google Docs API and the Google Drive API
4. Create a service account with domain-wide delegation enabled
5. In Google Workspace Admin Console, grant the service account access to the following scopes:

• https://www.googleapis.com/auth/documents (read and edit documents)
• https://www.googleapis.com/auth/drive (full read/write access to the impersonated user's Drive — required to export, read comments on, and manage arbitrary existing docs, including files this app did not create)

1. Download the JSON key file

Environment Variables (Service Account)

You can find the client_email and private_key values in your service account JSON key file.

Claude Desktop Configuration (Service Account)

{

"mcpServers": { "google-docs": { "command": "npx", "args": ["google-docs-workspace-mcp-server"], "env": { "GOOGLE_DOCS_SERVICE_ACCOUNT_CLIENT_EMAIL": "my-service-account@my-project.iam.gserviceaccount.com", "GOOGLE_DOCS_SERVICE_ACCOUNT_PRIVATE_KEY": "[PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก]", "GOOGLE_DOCS_IMPERSONATE_EMAIL": "user@yourdomain.com" } } } }

Note: For the private key, you can either:

1. Use the key directly with \n for newlines (as shown above)
2. Set the environment variable from a shell that preserves newlines

Tool Groups

The server supports three tool groups for permission-based access control:

By default, all tool groups are enabled. To restrict access, set the GOOGLE_DOCS_ENABLED_TOOLGROUPS environment variable:

# Read-only access (no writes or sharing)

GOOGLE_DOCS_ENABLED_TOOLGROUPS=readonly

Read and write, but no sharing

GOOGLE_DOCS_ENABLED_TOOLGROUPS=readwrite

Full access including sharing (default)

GOOGLE_DOCS_ENABLED_TOOLGROUPS=readwrite_external

Security Note: The share_document tool is in a separate readwrite_external group because it can grant access to users outside your organization, which carries higher risk than purely internal edits.

Available Tools

All tools that take a document_id accept either a raw Google Docs ID (e.g., 1AbCdEf...) or a shareable Docs URL (e.g., https://docs.google.com/document/d/1AbCdEf.../edit). The server extracts the ID automatically.

get_document

Fetch a Google Doc and return its title, outline, and full body.

Parameters:

• document_id (string, required): Google Docs ID or URL
• format (string, optional): text (default) for human-readable output, or json for the raw documents.get API resource

get_document_outline

Return only the heading structure of a document — useful for getting your bearings on a long doc without pulling the full body.

Parameters:

• document_id (string, required): Google Docs ID or URL

create_document

Create a new Google Doc.

Parameters:

• title (string, required): Document title
• initial_content (string, optional): Plain text inserted into the new document

update_document

Apply raw documents.batchUpdate requests. This is the escape hatch for any Docs API operation not covered by the more focused tools (e.g., applying paragraph styles, inserting tables, manipulating named ranges).

Parameters:

• document_id (string, required): Google Docs ID or URL
• requests (array, required): Array of documents.batchUpdate request objects (API reference)

Example:

{

"document_id": "1AbCdEf...", "requests": [ { "insertText": { "location": { "index": 1 }, "text": "Hello, world!\n" } }, { "updateParagraphStyle": { "range": { "startIndex": 1, "endIndex": 14 }, "paragraphStyle": { "namedStyleType": "HEADING_1" }, "fields": "namedStyleType" } } ] }

append_text

Append text to the end of a document. Resolves the end-of-body index for you.

Parameters:

• document_id (string, required): Google Docs ID or URL
• text (string, required): Text to append

insert_text

Insert text at a specific index.

Parameters:

• document_id (string, required): Google Docs ID or URL
• index (number, required): Insertion index (must be ≥ 1)
• text (string, required): Text to insert

replace_text

Find and replace text throughout a document. Reports the number of occurrences replaced.

Parameters:

• document_id (string, required): Google Docs ID or URL
• find (string, required): String to find
• replace (string, required): Replacement string
• match_case (boolean, optional): Whether matching is case-sensitive (default: false)

delete_document

Move a document to Drive trash by default, or permanently delete it.

Parameters:

• document_id (string, required): Google Docs ID or URL
• permanent (boolean, optional): When true, permanently delete instead of trashing (default: false)

export_document

Export a document in a different format.

Parameters:

• document_id (string, required): Google Docs ID or URL
• format (string, required): One of markdown, html, txt, pdf, docx, odt, rtf, epub

Text formats (markdown, html, txt) are returned inline. Binary formats (pdf, docx, odt, rtf, epub) are returned base64-encoded.

list_comments

List the comments on a document, including threaded replies and resolved state. Reads the Drive comments.list API and surfaces each comment's author, timestamps, resolved/open state, the anchored quoted text it refers to, the comment body, and any replies (including replies that resolved or reopened the thread).

Parameters:

• document_id (string, required): Google Docs ID or URL
• include_resolved (boolean, optional): Include resolved (closed) threads (default: true). Set false to see only open comments.
• `include_delet