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.

$3

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

$3

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

Quick Start

$3

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

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

With bunx (recommended):
`bash
bunx --bun -p gdrive-mcp gdrive-mcp-auth YOUR_CLIENT_ID YOUR_CLIENT_SECRET
`

If cloned from source:
`bash
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!
`

$3

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):
`json
{
"mcp": {
"gdrive": {
"type": "local",
"command": ["bunx", "--bun", "gdrive-mcp"]
}
}
}
`

If cloned from source:
`json
{
"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):
`json
{
"mcpServers": {
"gdrive": {
"command": "bunx",
"args": ["--bun", "gdrive-mcp"]
}
}
}
`

If cloned from source:
`json
{
"mcpServers": {
"gdrive": {
"command": "bun",
"args": ["run", "/absolute/path/to/gdrive-mcp/src/index.ts"]
}
}
}
`

Usage

$3

#### 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:
`json
{
"query": "quarterly report",
"max_results": 20
}
`

`json
{
"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:
`json
{
"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:)

$3

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

`bash
bunx --bun gdrive-mcp
`

The server will load credentials from your system keychain automatically.

Troubleshooting

$3

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

$3

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

$3

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

Development

$3

This project uses Biome for linting and formatting:

`bash


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

$3

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