Google Docs Tools

Overview

When working with CLI agents like Claude Code on writing projects, the most natural generation format is Markdown. But iterating on those docs via Google Docs is painful — uploading a Markdown file to Google Drive with proper formatting requires multiple manual steps.

md2gdoc reduces this to one command. gdoc2md does the reverse.

Installation

These tools require additional dependencies. Install with the gdocs extra:

uv tool install 'claude-code-tools[gdocs]'

First-Time Google OAuth Setup

Go to Google Cloud Console
Create or select a project and enable the Google Drive API and the Google Docs API
Set up the OAuth consent screen:
- Go to APIs & Services > OAuth consent screen
- If prompted for user type, choose Internal (available for Google Workspace accounts) — this avoids needing Google verification
- Fill in the required fields (app name, support email) and save
- If your app is set to External, go to the Audience tab in the left sidebar and either click Publish app to make it available, or add your email under Test users
If you skip this step, the OAuth flow will show an error saying the app is “blocked” or “being evaluated”. Publishing the app (or switching to Internal) resolves this.
Go to APIs & Services > Credentials > Create Credentials > OAuth client ID
Choose Desktop app, then download the JSON file
Save it as .gdoc-credentials.json in your project directory
First run will open a browser for OAuth consent (one-time per project)

Upload Markdown files as native Google Docs:

# Upload to root of Drive
md2gdoc report.md

# Upload to a specific folder
md2gdoc report.md --folder "Perf/Reports"

# Upload with a custom name
md2gdoc report.md --name "Q4 Summary"

Conflict Handling

If a file with the same name already exists, --on-existing controls behavior:

ask (default) — prompt for action
version — auto-add suffix (report-1, report-2, etc.)
overwrite — replace existing file

md2gdoc report.md --on-existing overwrite

Formatting

By default, Google’s markdown converter picks the font, size, and spacing. Use these flags to override body text formatting after upload:

# 10pt Arial, double-spaced
md2gdoc report.md --font Arial --font-size 10 --line-spacing 2.0

# Just change the font
md2gdoc report.md --font "Times New Roman"

# 1.5x spacing, keep default font
md2gdoc report.md --line-spacing 1.5

--font — font family (e.g. Arial, "Times New Roman")
--font-size — size in points (e.g. 10, 12)
--line-spacing — multiplier (1.0 = single, 1.5, 2.0 = double)

All flags are optional and can be combined. Heading styles (H1, H2, etc.) and inline formatting (bold, italic, etc.) are preserved — only body text paragraphs get the font/size override.

Features

Native markdown conversion (same quality as manual upload + “Open in Docs”)
Image upload — local images referenced in markdown (e.g. ![alt](diagram.png)) are uploaded to Drive at full resolution, then inserted into the Google Doc with proper sizing
Formatting — optional --font, --font-size, and --line-spacing flags to control body text appearance (see above)
--max-image-width controls display width in inches (default: 6.5 = full page width)
--no-images skips image processing entirely
Follows Drive shortcuts to shared folders
Creates folders if they do not exist

Download Google Docs as Markdown files:

# Download from root
gdoc2md "My Document"

# Download from a specific folder
gdoc2md "My Document" --folder "PNL/Reports"

# Save with a custom name
gdoc2md "My Document" -o report.md

# List docs in a folder
gdoc2md --list --folder PNL

Image Handling

By default, embedded images are extracted to local files (e.g. report_001.png, report_002.png) alongside the markdown, with references rewritten to use local paths.

Default — extract images to files
--no-images — strip images to placeholders
--keep-base64 — keep base64 data inline