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 document ID
• search_text (string): Exact text to search for; note will be inserted after the paragraph containing this text
• note (string): The note text (the "📝 NOTE #:" prefix is added automatically)

Example:

{
  "doc_id_or_url": "https://docs.google.com/document/d/...",
  "search_text": "Email Template",
  "note": "Consider using a more modern email format with clear sections and bullet points."
}

This will insert a styled block with a yellow background that looks like:

📝 NOTE 1: Consider using a more modern email 
format with clear sections and bullet points.

(with indentation, yellow background, and spacing)

update_doc_note

Updates the text of an existing note by its number. The note number and formatting remain the same.

Parameters:

• doc_id_or_url (string): Google Docs URL or document ID
• note_number (number): The note number to update (e.g., 1 for 📝 NOTE 1:)
• new_text (string): The new note text (without the '📝 NOTE #:' prefix)

remove_doc_note

Removes a note from the document by its number. This completely deletes the note block including all formatting.

Parameters:

• doc_id_or_url (string): Google Docs URL or document ID
• note_number (number): The note number to remove (e.g., 1 for 📝 NOTE 1:)

Testing the Server

After running the OAuth setup, you can test the server directly:

bunx --bun gdrive-mcp

The server will load credentials from your system keychain automatically.

Troubleshooting

"Access blocked: Authorization Error - OAuth client was not found"

This error means you're using placeholder/invalid credentials. You need to:

1. Create your own OAuth2 credentials (see docs/CREATE_OAUTH_CREDENTIALS.md)
2. Run the setup script with YOUR credentials

"No refresh token received"

If you've authorized the app before:

1. Go to https://myaccount.google.com/permissions
2. Remove the "gdrive-mcp" app
3. Run setup again

Port 48127 already in use

Change the REDIRECT_PORT in src/setup-auth.ts to a different port.

Development

Linting and Formatting

This project uses Biome for linting and formatting:

# Check code
bun run check

# Format code
bun run format

# Lint and fix
bun run lint

How It Works

This MCP server uses OAuth2 with a browser-based consent flow, similar to popular tools like rclone:

1. Setup phase: Run src/setup-auth.ts which starts a local callback server and opens your browser
2. Authorization: You approve the app in Google's OAuth consent screen
3. Token exchange: The auth code is exchanged for a refresh token
4. Secure storage: Credentials are stored in your system keychain using Bun.secrets
5. Runtime: The MCP server loads credentials from the keychain and uses the refresh token to get temporary access tokens

Secure Credential Storage

Unlike other tools that store credentials in plaintext .env files, gdrive-mcp uses Bun's native secrets API to store credentials securely:

• macOS: Keychain Services
• Linux: libsecret (GNOME Keyring, KWallet, etc.)
• Windows: Windows Credential Manager

Your OAuth credentials are:

• ✅ Encrypted at rest by the operating system
• ✅ Protected with user-level access control
• ✅ Never stored in plaintext configuration files
• ✅ Automatically available to the MCP server without env vars

This is the most user-friendly and secure approach used by modern CLI tools.

License

MIT