gdoc-comments MCP server

An MCP server for reading/editing Google Docs content and managing comments (list, create, reply, resolve, reopen), backed by the Docs API and the Drive API's comments endpoints.

Why a custom server instead of an existing one

Claude Code already ships with a first-party Google Drive connector (mcp__claude_ai_Google_Drive__*), and there's no shortage of third-party "Google Docs MCP" projects on GitHub/npm. In practice neither covers actual comment management:

• The built-in Drive connector exposes 8 tools total — search_files, list_recent_files, get_file_metadata, get_file_permissions, read_file_content, download_file_content, create_file, copy_file. Only read_file_content touches comments at all, via an includeComments flag that inlines them as read-only text tags in the document body. There's no comment listing with structured IDs or resolved status, and no way to create a comment, reply to one, or resolve/reopen a thread.
• Third-party servers vary widely in whether they touch comments at all, and where they do, comments created through the Drive API generally aren't anchored to a text selection in the Docs UI (a Drive API limitation this server inherits too — see the note under "Tools exposed" below).

This server exists specifically to close that gap: full read/write comment lifecycle management (list, create, reply, resolve, reopen), not just read-only visibility into comments that already exist.

1. Google Cloud setup (one-time)

1. Create or pick a project at https://console.cloud.google.com/.
2. Enable two APIs for that project:
   • Google Docs API
   • Google Drive API
3. Configure the OAuth consent screen (External is fine; keep it in "Testing" mode) and add your own Google account under Test users.
4. Create an OAuth client ID: APIs & Services → Credentials → Create Credentials → OAuth client ID → Application type: Desktop app.
5. Download the client JSON and save it as credentials.json in this directory (already gitignored).

2. Install

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

3. Authenticate (one-time, interactive)

.venv/bin/python authenticate.py

This opens a browser for Google login/consent and caches a token to token.json (gitignored). Since the OAuth consent screen stays in "Testing" mode, click through the "unverified app" warning — that's expected for an app only you use. The MCP server itself never triggers this flow; it only reads and silently refreshes this cached token. Re-run this script if the token is ever revoked or deleted.

4. Wire it into Claude Code

The server's command always points at wherever this repo was cloned — the venv and server.py live here, not in whatever project you happen to be registering the tool for. Set that path once:

GDOC_MCP_DIR=/absolute/path/to/gdoc_comment_mcp   # wherever you cloned this repo

PYTHONPATH must point at $GDOC_MCP_DIR — server.py is launched directly (not via -m), so without it Python can't find the gdoc_mcp package it's part of, and the server crashes immediately on every connection attempt.

Local scope (private to you, this project only)

The default for claude mcp add. Run from anywhere, including a different project's directory — only $GDOC_MCP_DIR needs to be right, not your pwd:

claude mcp add gdoc-comments -e PYTHONPATH="$GDOC_MCP_DIR" -- "$GDOC_MCP_DIR/.venv/bin/python" "$GDOC_MCP_DIR/gdoc_mcp/server.py"

User scope (private to you, available in every project)

Add -s user so the server shows up regardless of which directory you launch claude from — no need to re-register it per project:

claude mcp add gdoc-comments -s user -e PYTHONPATH="$GDOC_MCP_DIR" -- "$GDOC_MCP_DIR/.venv/bin/python" "$GDOC_MCP_DIR/gdoc_mcp/server.py"

Project scope (shared with anyone who clones a given project)

Add -s project while standing inside that other project's directory — this writes a .mcp.json there (not in gdoc_comment_mcp), which you'd commit so teammates get the server automatically when they open that project in Claude Code:

cd /path/to/some/other/project
claude mcp add gdoc-comments -s project -e PYTHONPATH="$GDOC_MCP_DIR" -- "$GDOC_MCP_DIR/.venv/bin/python" "$GDOC_MCP_DIR/gdoc_mcp/server.py"

Each teammate still needs to complete their own Google Cloud setup and authenticate locally — .mcp.json only wires up the server command, not credentials.

Tools exposed

• read_google_doc(document_id) — title + flattened text content
• insert_text_in_doc(document_id, index, text)
• append_text_to_doc(document_id, text)
• replace_text_in_doc(document_id, find_text, replace_text, match_case)
• list_doc_comments(document_id, include_resolved)
• get_doc_comment(document_id, comment_id)
• create_doc_comment(document_id, content, quoted_text)
• reply_to_doc_comment(document_id, comment_id, content)
• resolve_doc_comment(document_id, comment_id, content)
• reopen_doc_comment(document_id, comment_id, content)

document_id accepts either a bare document ID or a full https://docs.google.com/document/d/... URL.

Note: new comments created via the API are not anchored to a specific text selection — the Drive API doesn't expose that. quoted_text is shown as context alongside the comment but won't highlight a range in the doc.

Tests

.venv/bin/python -m pytest tests/