# 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

```bash
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](docs/CREATE_OAUTH_CREDENTIALS.md)

**Quick version:**
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
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):**
```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!
```

### 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):**
```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

### 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:**
```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:)

### Testing the Server

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

### "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](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:

```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](https://rclone.org/drive/):

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](https://bun.sh/docs/runtime/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