DEV Community

Daksh Gargas
Daksh Gargas

Posted on

Google's Workspace CLI returns raw JSON. `gdocs-to-md-mcp` returns markdown. Here's why that matters.

#mcp #claude #markdown #developertools

The problem

The Problem

Google recently released a Workspace CLI with MCP support — so technically, your AI assistant can read a Google Doc now. But what it gets back is raw API JSON: a 500-line nested tree of StructuralElement objects, ParagraphElement arrays, and TextRun objects with style metadata buried three levels deep.

Your LLM can parse it. But it shouldn't have to.

Why Markdown Matters for LLMs

Think about what markdown gives an LLM that raw JSON doesn't:

  • # Heading tells it "this is a new section" — no need to infer structure from nested objects
  • `bold*`* signals emphasis — in JSON, that's a textStyle.bold: true property buried inside a TextRun object
  • | tables | stay readable inline — in JSON, that's a matrix of TableCell arrays inside TableRow arrays inside a Table object
  • - lists just work — in JSON, you're parsing bullet.nestingLevel and listProperties.nestingLevels[n].glyphType

An LLM can read markdown the way a human reads a document. JSON forces it to reconstruct the document from parts.

And the research backs this up. An arXiv study found up to 40% performance variance in LLM output depending on whether the input was plain text, Markdown, JSON, or YAML. A benchmark testing 11 table formats showed Markdown-KV hitting 60.7% accuracy — 16 points ahead of CSV and JSON alternatives. Markdown is also 10-15% more token-efficient than JSON for the same content, which adds up fast at scale.

Even the vendors agree: Anthropic recommends XML tags with markdown/plain text for document input. OpenAI recommends markdown formatting for code-related tasks. Google Gemini recommends markdown headings for structuring prompts.

The Solution

gdocs-to-md-mcp — a local MCP server that fetches Google Docs and converts them to clean markdown. Headings, bold, italic, tables, lists, links — all preserved.

One command to set up:

npx gdocs-to-md-mcp setup
Enter fullscreen mode Exit fullscreen mode

The interactive wizard walks you through everything — GCP project selection, OAuth credentials, API enablement, Google sign-in — with clickable links that take you to the exact right page. No hunting through Cloud Console. It even auto-configures Claude Code when it's done.

How It Looks

Once set up, just paste a Google Docs URL:

"Read this doc and summarize the key decisions: https://docs.google.com/document/d/1abc.../edit"

Claude calls read_google_doc, gets clean structured markdown, and actually understands the document — sections, emphasis, tables, all of it. Compare that to the raw \n\n-delimited text blob from the default Google Drive integration. Night and day.

Three tools, nothing more:

  • read_google_doc — URL or doc ID in, markdown out
  • search_google_docs — find docs by keyword
  • list_recent_docs — see what's been updated recently

No 80-tool mega-server. No Gmail. No Calendar. Just Google Docs to markdown, done right.

Install globally with npm install -g gdocs-to-md-mcp or just run it directly with npx — your call.

GitHub: github.com/D4G4/gdocs-to-md-mcp
npm: npmjs.com/package/gdocs-to-md-mcp

[Update]: Simon Willison recently wrote about the unreasonable effectiveness of HTML for LLMs, which might make you wonder — should this tool output HTML instead?

The key distinction: Simon's argument is about LLM output — when you ask an LLM to explain something back to you, HTML is richer (SVGs, interactive widgets, navigation). That's a presentation win.

Our tool solves the opposite direction — feeding content into the LLM. For input comprehension, the research still favors markdown: 40% better performance, 15% fewer tokens, and all three major vendors recommend it for document input.

tl;dr: Markdown for what goes in. HTML for what comes out. Different problems, different formats.

Sources: Why Markdown > JSON for LLM Document Comprehension

Top comments (0)