gdrive-mcp

A Model Context Protocol (MCP) server that provides access to Google Drive documents.

Features

• search_drive: Search for files and documents across all of Google Drive
• get_doc_contents: Retrieve the full text contents of a Google Doc by URL or document ID
• list_doc_comments: List all comment threads on a Google Doc with details
• create_doc_comment: Create unanchored comments on a Google Doc
• reply_to_comment: Reply to existing comment threads
• insert_doc_note: Insert auto-numbered styled note blocks ( NOTE 1:, NOTE 2:, etc.) into document content
• update_doc_note: Update the text of an existing note by its number
• remove_doc_note: Remove a note from the document by its number

Installation

No installation needed! Use bunx to run directly, or clone from source.

Option 1: Use with bunx (Recommended)

No installation required - bunx will download and cache the package automatically.

Option 2: Clone from Source

git clone https://github.com/benjamine/gdrive-mcp.git
cd gdrive-mcp
bun install

Quick Start

2. Create Google OAuth2 Credentials

You need to create your own OAuth2 credentials from Google Cloud Console.

See detailed instructions: docs/CREATE_OAUTH_CREDENTIALS.md

Quick version:

1. Go to Google Cloud Console
2. Create a project and enable Google Drive API + Google Docs API
3. Create OAuth 2.0 Desktop credentials
4. Copy your Client ID and Client Secret

3. Run the OAuth Setup

The setup script will open your browser and handle the OAuth2 flow:

With bunx (recommended):

bunx --bun -p gdrive-mcp gdrive-mcp-auth YOUR_CLIENT_ID YOUR_CLIENT_SECRET

If cloned from source:

bun run src/setup-auth.ts YOUR_CLIENT_ID YOUR_CLIENT_SECRET

This will:

1. Open your browser for Google authorization
2. Handle the OAuth2 callback automatically
3. Securely store credentials in your system keychain
4. Display configuration ready to copy

Example output:

 Setup Complete!

 Credentials stored securely in your system keychain
   (macOS Keychain / Linux libsecret / Windows Credential Manager)

Add this to your Claude Desktop config:
{
  "mcpServers": {
    "gdrive": {
      "command": "bunx",
      "args": ["--bun", "gdrive-mcp"]
    }
  }
}

 No need to store sensitive credentials in config files!

4. Configure MCP Client

Add the server to your MCP client configuration.

Note: Credentials are securely stored in your system keychain (macOS Keychain, Linux libsecret, or Windows Credential Manager) - no need to add them to config files!

OpenCode

Add to your opencode.jsonc:

With bunx (recommended):

{
  "mcp": {
    "gdrive": {
      "type": "local",
      "command": ["bunx", "--bun", "gdrive-mcp"]
    }
  }
}

If cloned from source:

{
  "mcp": {
    "gdrive": {
      "type": "local",
      "command": ["bun", "run", "/absolute/path/to/gdrive-mcp/src/index.ts"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

With bunx (recommended):

{
  "mcpServers": {
    "gdrive": {
      "command": "bunx",
      "args": ["--bun", "gdrive-mcp"]
    }
  }
}

If cloned from source:

{
  "mcpServers": {
    "gdrive": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gdrive-mcp/src/index.ts"]
    }
  }
}

Usage

Available Tools

search_drive

Search for files and documents across all of Google Drive using text queries.

Parameters:

• query (string): Search query text. Supports Google Drive search syntax:
  • Simple text: "quarterly report" - searches in file names and content
  • By name: name:report - searches only file names
  • By type: type:document - filters by file type
  • Combined: type:spreadsheet budget - combines filters
• max_results (number, optional): Maximum number of results to return (default: 10, max: 100)

Returns:

• File name, type, ID, modification date, owner, size, and view link for each matching file

Examples:

{
  "query": "quarterly report",
  "max_results": 20
}

{
  "query": "type:document name:meeting",
  "max_results": 10
}

get_doc_contents

Retrieves the full text contents of a Google Doc.

Parameters:

• doc_id_or_url (string): Either a full Google Docs URL or just the document ID

Examples:

• URL: https://docs.google.com/document/d/1a2b3c4d5e6f7g8h9i0j/edit
• Document ID: 1a2b3c4d5e6f7g8h9i0j

list_doc_comments

Lists all comment threads on a Google Doc, including quoted text, replies, and status.

Parameters:

• doc_id_or_url (string): Google Docs URL or document ID

create_doc_comment

Creates an unanchored comment on a Google Doc (appears in "All Comments" view).

Parameters:

• doc_id_or_url (string): Google Docs URL or document ID
• comment (string): The comment text to add

Note: Due to Google Drive API limitations, comments cannot be anchored to specific text selections.

reply_to_comment

Replies to an existing comment thread on a Google Doc.

Parameters:

• doc_id_or_url (string): Google Docs URL or document ID
• comment_id (string): The ID of the comment to reply to
• reply (string): The reply text

insert_doc_note

Inserts an auto-numbered styled note block directly into the document content. Notes are automatically numbered sequentially ( NOTE 1:, NOTE 2:, etc.). This is a workaround for the API's inability to create anchored comments or suggestions. The note appears as a visually distinctive block with:

• Auto-incrementing note numbers
• Colored background (light yellow/cream)
• Indentation and spacing
• Bold, colored header
• Normal text size for readability

Parameters:

• doc_id_or_url (string): Google Docs URL or documen…