@ibarcarty/mcp-server-google-drive

A Model Context Protocol (MCP) server for Google Drive, Google Docs, Google Sheets, and Google Slides with full read/write operations and rich markdown formatting. Search, read, create, edit, delete, move, copy files, edit documents with native formatting, manage spreadsheets, modify presentations, and control permissions — including shared drives.

Built with official Google APIs (googleapis) and the official MCP SDK (@modelcontextprotocol/sdk).

Features

• 27 tools for complete Google Drive, Docs, Sheets, and Slides management
• Rich markdown → Google Docs (docs_write_markdown): headings, bold, italic, strikethrough, inline code, code blocks, tables, lists, links, blockquotes — all as native Google Docs formatting
• Document theming (docs_apply_theme): apply a consistent visual theme (typography, colors, spacing, margins) to an entire document. Built-in corporate and minimal themes. Custom themes loadable from a JSON file via env var
• Corporate document templates (docs_apply_corporate_template): initialize a document with title, metadata, change log, classification badge, and footer — useful for standard corporate deliverables
• Google Docs editing: read, append, insert, find & replace, and write formatted markdown
• Google Sheets editing: read, write, append rows, and clear cell ranges
• Google Slides editing: read presentations, add slides, insert text, and find & replace
• File management: create, read, update, delete, move, copy files and folders
• Permissions: share files, list access, revoke permissions
• Shared drives supported by default in all operations
• Google Workspace export: Docs → Markdown, Sheets → CSV, Slides → text
• Two transport modes: local (stdio) and remote (Streamable HTTP for Cloud Run)
• OAuth2 with automatic token refresh
• TypeScript — fully typed, strict mode

Quick Start

1. Set up OAuth credentials

Follow the OAuth Setup Guide to create credentials in Google Cloud Console.

Important: You must enable these APIs in your GCP project:

• Google Drive API
• Google Docs API
• Google Sheets API
• Google Slides API

2. Install

From npm:

npx @ibarcarty/mcp-server-google-drive auth

From source:

git clone https://github.com/ibarcarty/mcp-server-google-drive.git
cd mcp-server-google-drive
npm install --ignore-scripts
npm run build
node dist/index.js auth

This opens your browser to authorize with your Google account. Tokens are saved locally.

3. Configure Claude Code / Claude Desktop

From npm:

{
  "mcpServers": {
    "google-drive": {
      "command": "npx",
      "args": ["-y", "@ibarcarty/mcp-server-google-drive"],
      "env": {
        "GDRIVE_MCP_OAUTH_PATH": "/path/to/your/oauth-credentials.json"
      }
    }
  }
}

From source:

{
  "mcpServers": {
    "google-drive": {
      "command": "node",
      "args": ["/path/to/mcp-server-google-drive/dist/index.js"],
      "env": {
        "GDRIVE_MCP_OAUTH_PATH": "/path/to/your/oauth-credentials.json"
      }
    }
  }
}

See Local Setup Guide for detailed instructions.

Tools

Drive — File Operations

Tool	Description
drive_list_files	List files/folders with filtering, pagination, and sorting
drive_search	Search by name or content (full-text search)
drive_read_file	Read file content. Auto-exports Workspace files
drive_create_file	Create a new file with optional content
drive_create_folder	Create a new folder
drive_update_file	Update file content or rename
drive_delete_file	Permanently delete a file or folder
drive_move_file	Move to a different folder
drive_copy_file	Copy a file, optionally to a different folder

Drive — Permissions

Tool	Description
drive_share	Share a file with a user (reader/writer/commenter)
drive_list_permissions	List who has access to a file
drive_remove_permission	Revoke access from a user

Google Docs — Document Editing

Tool	Description
docs_read	Read document content with structure (headings, indexes)
docs_append_text	Append plain text at the end of a document
docs_insert_text	Insert plain text at a specific position (by index)
docs_replace_text	Find and replace text throughout a document
docs_write_markdown	Write GitHub Flavored Markdown with native rich formatting (headings, bold, italic, strikethrough, inline code, code blocks, tables, lists, links, blockquotes)
docs_apply_theme	Apply a predefined visual theme (typography, colors, spacing, margins) to an entire document. Built-in: corporate, minimal. Custom themes loadable from JSON
docs_apply_corporate_template	Initialize a document with title, metadata, change log, classification badge, and footer

Markdown-to-Docs example

// Write rich markdown to an existing Google Doc
await mcp.callTool("docs_write_markdown", {
  documentId: "1abc...xyz",
  markdown: `
# Project Report

## Summary
This project delivers **three key features**:

- Feature A with *italic emphasis*
- Feature B using \`inline code\`
- Feature C — [see docs](https://example.com)

## Timeline

| Phase | Start | End |
|-------|-------|-----|
| Design | Jan | Feb |
| Build | Mar | May |
`,
  mode: "append",  // or "replace_all"
});

// Apply the built-in corporate theme
await mcp.callTool("docs_apply_theme", {
  documentId: "1abc...xyz",
  theme: "corporate",
});

Custom themes

Built-in themes (corporate, minimal) cover most cases. For custom branding, point GDRIVE_MCP_CUSTOM_THEMES_PATH to a JSON file:

{
  "my-brand": {
    "name": "my-brand",
    "fontFamily": "Arial",
    "lineSpacing": 115,
    "margins": { "top": 71, "bottom": 71, "left": 71, "right": 71 },
    "styles": {
      "TITLE":       { "fontSize": 26, "bold": true, "color": { "red": 0.0,  "green": 0.32, "blue": 0.53 }, "spaceAbove": 0,  "spaceBelow": 12 },
      "SUBTITLE":    { "fontSize": 16,                "color": { "red": 0.18, "green": 0.18, "blue": 0.18 }, "spaceAbove": 0,  "spaceBelow": 12 },
      "HEADING_1":   { "fontSize": 20, "bold": true, "color": { "red": 0.0,  "green": 0.32, "blue": 0.53 }, "spaceAbove": 16, "spaceBelow": 6 },
      "HEADING_2":   { "fontSize": 16, "bold": true, "color": { "red": 0.30, "green": 0.51, "blue": 0.74 }, "spaceAbove": 12, "spaceBelow": 4 },
      "HEADING_3":   { "fontSize": 13, "bold": true, "color": { "red": 0.30, "green": 0.51, "blue": 0.74 }, "spaceAbove": 10, "spaceBelow": 4 },
      "HEADING_4":   { "fontSize": 12, "bold": true, "color": { "red": 0.18, "green": 0.18, "blue": 0.18 }, "spaceAbove": 8,  "spaceBelow": 2 },
      "HEADING_5":   { "fontSize": 11, "bold": true, "color": { "red": 0.18, "green": 0.18, "blue": 0.18 }, "spaceAbove": 6,  "spaceBelow": 2 },
      "HEADING_6":   { "fontSize": 10, "bold": true, "color": { "red": 0.18, "green": 0.18, "blue": 0.18 }, "spaceAbove": 6,  "spaceBelow": 2 },
      "NORMAL_TEXT": { "fontSize": 11,                "color": { "red": 0.18, "green": 0.18, "blue": 0.18 }, "spaceAbove": 0,  "spaceBelow": 4 }
    }
  }
}

Then apply it by name: { theme: "my-brand" }.

The markdown is parsed with remark + remark-gfm (CommonMark + GFM extensions) and converted to native Google Docs batchUpdate requests (insertText, updateTextStyle, updateParagraphStyle, insertTable, createParagraphBullets, updateTableCellStyle). No markdown characters remain in the document — it becomes native Google Docs formatting.

Google Sheets — Spreadsheet Editing

Tool	Description
sheets_read_range	Read cell values from a range (A1 notation)
sheets_write_range	Write values to a range of cells
sheets_append_rows	Append rows after the last row with data
sheets_clear_range	Clear values in a range (formatting preserved)

Google Slides — Presentation Editing

Tool	Description
slides_read	Read all slides with text content and element IDs
slides_add_slide	Add a new slide to the presentation
slides_add_text	Insert text into a specific shape/placeholder
slides_replace_text	Find and replace text across all slides

Configuration

All configuration is via environment variables. All are optional with sensible defaults.

Variable	Default	Description
GDRIVE_MCP_OAUTH_PATH	~/.config/mcp-server-google-drive/oauth-credentials.json	OAuth client credentials file
GDRIVE_MCP_TOKEN_PATH	~/.config/mcp-server-google-drive/tokens.json	Saved tokens file
GDRIVE_MCP_SCOPES	https://www.googleapis.com/auth/drive	OAuth scopes
GDRIVE_MCP_TRANSPORT	stdio	Transport: stdio or http
GDRIVE_MCP_PORT	8080	HTTP port (for http transport)
GDRIVE_MCP_HOST	0.0.0.0	HTTP bind address
GDRIVE_MCP_CUSTOM_THEMES_PATH	(unset)	Optional path to a JSON file with custom theme specifications

On Windows, the default config directory is %APPDATA%/mcp-server-google-drive/.

Deployment

Local (recommended for personal use)

Uses stdio transport. See Local Setup Guide.

Google Cloud Run (for teams)

Uses Streamable HTTP transport. See Cloud Run Deployment Guide.

Development

git clone https://github.com/ibarcarty/mcp-server-google-drive.git
cd mcp-server-google-drive
npm install --ignore-scripts
npm run build

OAuth Scopes

This server uses https://www.googleapis.com/auth/drive (full Drive access) by default. This scope also covers Google Docs, Google Sheets, and Google Slides APIs.

If you only need access to files created by this app, you can use the more restrictive drive.file scope:

GDRIVE_MCP_SCOPES=https://www.googleapis.com/auth/drive.file npx @ibarcarty/mcp-server-google-drive auth

Note: The drive scope requires Google verification for apps with 100+ users. For personal use or small teams (< 100 users), testing mode works without verification.

Limitations

• docs_write_markdown covers CommonMark + GFM (headings, emphasis, lists, links, code blocks, blockquotes, tables, strikethrough). Images, footnotes, and task lists with interactive checkboxes are rendered as plain text or placeholders.
• Google Slides editing supports text operations and adding slides. Complex layout operations (positioning shapes, animations) require using the raw Slides API.
• Export of Workspace files has a 10MB limit (Google API limitation).
• Binary file uploads are limited to text content passed as strings. For large binary files, use Google Drive directly.

Changelog

v1.1.1

• Maintenance: harden build script to clean dist/ before compiling (prevents stale artifacts from previous compilations being published). Users should upgrade from v1.1.0 to this version.
• No functional changes vs v1.1.0.

v1.1.0

• NEW docs_write_markdown: convert GitHub Flavored Markdown to native Google Docs formatting (headings, bold, italic, strikethrough, inline code, code blocks, tables, lists, links, blockquotes).
• NEW docs_apply_theme: apply a consistent visual theme across a document. Built-in themes: corporate (Arial, corporate blue), minimal (Inter, neutral). Custom themes can be loaded from a JSON file via GDRIVE_MCP_CUSTOM_THEMES_PATH.
• NEW docs_apply_corporate_template: initialize a document with a standard corporate structure (title, metadata, change log, classification badge, footer).
• Parser powered by unified + remark-parse + remark-gfm (industry standard).
• Zero extra token cost vs raw text — model sends markdown, server handles the conversion.

v1.0.1

• Initial public release with 24 tools across Drive, Docs, Sheets, Slides.

License

MIT