mcp-gdocs

Русский | 中文

Why mcp-gdocs exists

MCP server for Google Docs, Google Drive, and Comments with flexible authentication.

Connect Cursor, Claude Desktop, or any MCP client to your Google Docs and Drive.

Start with a single command: npx -y mcp-gdocs.

Quick Start

1. Google Cloud Setup

1. Go to Google Cloud Console
2. Create or select a project
3. Enable Google Docs API and Google Drive API
4. Choose authentication method (see Authentication below)

2. Add to Cursor / MCP Client

Service Account — share documents with the SA email, then:

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

OAuth — run npx -y mcp-gdocs auth first, then:

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

The server starts automatically when the MCP client connects.

What Can It Do?

Most write operations accept an items array for bulk execution in a single call. All tools support an optional tabId parameter for multi-tab documents.

Google Docs

| Tool | Description | | --- | --- | | docs_read_document | Read as text, JSON, markdown, or summary; optional fields mask | | docs_get_document_info | Document metadata (title, ID, revision) | | docs_list_document_tabs | List all tabs in a multi-tab document | | docs_insert_text | Insert text at one or multiple positions | | docs_append_text | Append text to the end | | docs_delete_range | Remove content by index ranges | | docs_replace_all_text | Replace all occurrences of patterns | | docs_replace_document_content | Replace entire document content | | docs_insert_page_break | Insert page breaks | | docs_rename_tab | Rename a document tab | | docs_update_header | Update header content | | docs_update_footer | Update footer content | | docs_create_footnote | Create footnotes at a position | | docs_add_tab | Add a new document tab | | docs_apply_text_style | Bold, italic, underline, colors, font, links | | docs_apply_paragraph_style | Alignment, spacing, indentation | | docs_apply_heading_style | Heading styles (H1–H6) | | docs_format_by_text | Find text and apply formatting without knowing indices | | docs_insert_table_row | Add row to table | | docs_insert_table_column | Add column to table | | docs_delete_table_row | Delete row from table | | docs_delete_table_column | Delete column from table | | docs_update_table_cell_content | Update cell content | | docs_update_table_cell_style | Cell background color | | docs_insert_table_with_data | Create a table pre-filled with data | | docs_insert_image | Insert images from URL | | docs_insert_local_image | Insert images from local files (upload + insert) | | docs_replace_with_markdown_native | Replace from Markdown (native Google conversion) | | docs_replace_with_markdown_file_native | Replace from Markdown file (native conversion) | | docs_batch_update | Batch multiple operations in one API call (30 request types) | | docs_create_named_range | Create a named range | | docs_delete_named_range | Delete a named range | | docs_replace_named_range_content | Replace text inside a named range |

Comments

| Tool | Description | | --- | --- | | docs_list_comments | List all comments with author and date | | docs_get_comment | Get a specific comment with replies | | docs_add_comment | Create comments anchored to text | | docs_reply_to_comment | Reply to comments | | docs_resolve_comment | Mark comments as resolved | | docs_delete_comment | Remove comments |

Google Drive

| Tool | Description | | --- | --- | | drive_list_documents | List documents, optionally filtered | | drive_search_documents | Full-text search across documents | | drive_create_document | Create new documents | | drive_create_from_template | Create documents from a template | | drive_create_from_markdown | Create a new Doc from inline Markdown | | drive_create_from_markdown_file | Create a new Doc from a local .md file | | drive_create_folder | Create folders | | drive_list_folder_contents | List folder contents | | drive_get_folder_info | Get folder metadata | | drive_move_file | Move files to another folder | | drive_copy_file | Duplicate files | | drive_rename_file | Rename files | | drive_delete_file | Move files to trash | | docs_export_pdf | Export document as PDF (optional savePath) | | drive_export_file | Export to markdown, PDF, DOCX, and other MIME types | | drive_share_file | Share a file (user, group, domain, anyone) | | drive_list_permissions | List ACLs on a file | | drive_update_permission | Change role on an existing permission | | drive_remove_permission | Revoke a permission | | drive_list_revisions | List revision history | | drive_get_revision | Fetch metadata or content of one revision | | drive_list_shared_drives | List shared drives (Team Drives) |

Prompts

| Prompt | Description | | --- | --- | | pretty-format | Create or reformat a Doc from Markdown; cleanup batch for rules, spacing, tables | | gost-format | Document structure and styles aligned with GOST 19.106-78 | | template-fill | Fill a template using placeholders / named ranges | | export-to-markdown | Export a Google Doc to Markdown via Drive API | | format-table | Pin headers, column widths, and cell styles for a Doc table | | share-document | List permissions, then share with a user |

Resources

| URI | Description | | --- | --- | | gdocs://documents/recent | JSON list of recently modified Google Docs |

Batch Operations

docs_batch_update combines multiple heterogeneous operations into a single API request (30 request types). Large arrays are automatically split into chunks. Rate limiting uses a shared API semaphore.

Authentication

The server supports multiple authentication methods. If several variables are set, the first found is used: OAuth → SERVICE_ACCOUNT_PATH → CREDENTIALS_CONFIG → GOOGLE_APPLICATION_CREDENTIALS.

| Criteria | Service Account | OAuth | | --- | --- | --- | | Document access | Only shared with SA | All your documents | | Drive operations | Only in shared folders | Full access to your Drive | | Best for | CI/CD, servers, automation | Personal use, Cursor, Claude Desktop | | Setup | Download JSON key, share documents | OAuth flow in browser | | Google Workspace | Impersonation — full access as user | Not needed |

Enterprise (Google Workspace): with domain-wide delegation, SA can act on behalf of any domain user via GOOGLE_IMPERSONATE_USER.

Recommendation: use OAuth for personal work in Cursor/Claude Desktop. Use Service Account with impersonation for enterprise automation.

Method A: Service Account

Headless, secure, ideal for server environments.

Steps:

1. GCP Console → IAM & Admin → Service Accounts → Create
2. Download JSON key
3. Share documents/folders with SA email (Editor)

Three ways to provide credentials:

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/service-account-key.json",
        "GOOGLE_IMPERSONATE_USER": "[email protected]"
      }
    }
  }
}

base64 -w 0 service-account.json   # Linux
base64 -i service-account.json | tr -d '\n'   # macOS

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIs..."
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

Method B: OAuth 2.0

For personal use with interactive browser login.

1. Google Cloud Console → APIs & Services → Credentials
2. Create OAuth client ID → Desktop app
3. Copy Client ID and Client Secret
4. OAuth consent screen → add your email as Test User
5. Authorize: GOOGLE_CLIENT_ID="..." GOOGLE_CLIENT_SECRET="..." npx -y mcp-gdocs auth

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

OAuth refresh tokens are stored in ~/.config/mcp-gdocs/token.json (respects XDG_CONFIG_HOME). To re-authorize, delete the token file and run auth again.

Multiple Google Accounts

GOOGLE_MCP_PROFILE isolates token storage per profile:

~/.config/mcp-gdocs/
├── token.json              # default (no profile)
├── work/token.json         # GOOGLE_MCP_PROFILE=work
└── personal/token.json     # GOOGLE_MCP_PROFILE=personal

Environment Variables

| Variable | Method | Description | | --- | --- | --- | | SERVICE_ACCOUNT_PATH | SA | Path to SA JSON key (+ impersonation support) | | GOOGLE_IMPERSONATE_USER | SA | Email for impersonation (optional) | | CREDENTIALS_CONFIG | SA | Base64-encoded SA JSON (Docker/CI) | | GOOGLE_APPLICATION_CREDENTIALS | SA | Path to SA JSON key (standard Google variable) | | GOOGLE_CLIENT_ID | OAuth | OAuth client ID | | GOOGLE_CLIENT_SECRET | OAuth | OAuth client secret | | GOOGLE_MCP_PROFILE | OAuth | Profile name for isolated token storage |

Known Limitations

• SA without Workspace: Service account without Google Workspace license has Drive quota = 0 and cannot create files. Use OAuth or impersonation.
• Comment anchoring: Programmatically created comments may not be anchored to text in Google Docs UI (Drive API limitation).
• Deeply nested lists: Lists with 3+ nesting levels may have formatting artifacts when converting Markdown.
• Paragraph style safe range: paragraph and heading style tools automatically adjust ranges to prevent styles from bleeding into adjacent paragraphs.

Troubleshooting

• Server won't start: check that environment variables are set in the MCP config env block.
• Authorization errors: make sure Docs and Drive APIs are enabled in Google Cloud Console. For OAuth — check that your email is added as Test User.
• Re-authorization: delete ~/.config/mcp-gdocs/token.json and run npx -y mcp-gdocs auth again.

Changelog · License