mcp-gdrive-enhanced-markov/README.md

MCP server for Google Drive and Sheets with write capabilities, AI-powered PDF analysis, SQLite document indexing, and advanced directory exploration tools

# Google Drive server

This MCP server integrates with Google Drive to allow listing, reading, and searching files, as well as the ability to read and write to Google Sheets. It also includes AI-powered PDF analysis capabilities using Gemini 2.5 Flash via OpenRouter.

This project includes code originally developed by Anthropic, PBC, licensed under the MIT License from [this repo](https://github.com/modelcontextprotocol/servers/tree/main/src/gdrive).

## Key Features

- 📝 **Full Google Drive access** - Read, write, search, and organize files
- 📊 **Advanced spreadsheet handling** - Read Excel and Google Sheets with formatted tables
- 🔍 **Smart search with filtering** - Filter by file type, date ranges, and content
- 🤖 **AI-powered PDF analysis** - Extract insights from PDFs using Gemini 2.5 Flash
- 📁 **Complete folder operations** - Create, explore, and visualize directory structures
- 🔄 **Automatic format conversion** - Google Docs to Markdown, Sheets to tables
- 🎯 **Production-ready workflows** - Real business scenarios supported
- 🚀 **High performance** - Parallel processing with rate limiting

## Quick Start - Install in Claude Code

### 1. First-time setup (one-time only)

```bash
# Set up environment variables
export CLIENT_ID="your-google-oauth-client-id"
export CLIENT_SECRET="your-google-oauth-client-secret"
export GDRIVE_CREDS_DIR="/path/to/credentials/directory"
export OPENROUTER_API_KEY="your-openrouter-api-key"

# Run authentication (opens browser)
npx mcp-gdrive-enhanced-markov
```

### 2. Add to Claude Code

```bash
claude mcp add gdrive-enhanced \
  -e CLIENT_ID="your-client-id" \
  -e CLIENT_SECRET="your-client-secret" \
  -e GDRIVE_CREDS_DIR="/path/to/creds" \
  -e OPENROUTER_API_KEY="your-openrouter-key" \
  -- npx -y mcp-gdrive-enhanced-markov
```

That's it! The server is now available in Claude Code.

## Components

### Tools

- **gdrive_search**

  - **Description**: Search for files in Google Drive with advanced filtering options.
  - **Input**:
    - `query` (string): Search query - can be file name or content search.
    - `fileType` (string, optional): Filter by file type: 'spreadsheet', 'document', 'presentation', 'pdf', 'image', 'video', 'audio', 'folder'.
    - `modifiedAfter` (string, optional): Only return files modified after this date (ISO format: YYYY-MM-DD).
    - `modifiedBefore` (string, optional): Only return files modified before this date (ISO format: YYYY-MM-DD).
    - `pageToken` (string, optional): Token for the next page of results.
    - `pageSize` (number, optional): Number of results per page (max 100).
  - **Output**: Returns file names, dates, sizes, and MIME types of matching files.

- **gdrive_read_file**

  - **Description**: Read contents of a file from Google Drive.
  - **Input**:
    - `fileId` (string): ID of the file to read.
  - **Output**: Returns the contents of the specified file.

- **gdrive_read_excel**

  - **Description**: Read Excel and Google Sheets files with proper formatting and table display.
  - **Input**:
    - `fileId` (string): The ID of the Excel or Google Sheets file to read.
    - `sheetName` (string, optional): Optional sheet name to read from (for multi-sheet files).
    - `range` (string, optional): Optional cell range in A1 notation (e.g., "A1:D10").
  - **Output**: Returns formatted markdown table with spreadsheet data.

- **gsheets_read**

  - **Description**: Read data from a Google Spreadsheet with flexible options for ranges and formatting.
  - **Input**:
    - `spreadsheetId` (string): The ID of the spreadsheet to read.
    - `ranges` (array of strings, optional): Optional array of A1 notation ranges (e.g., `['Sheet1!A1:B10']`). If not provided, reads the entire sheet.
    - `sheetId` (number, optional): Specific sheet ID to read. If not provided with ranges, reads the first sheet.
  - **Output**: Returns the specified data from the spreadsheet.

- **gsheets_update_cell**
  - **Description**: Update a cell value in a Google Spreadsheet.
  - **Input**:
    - `fileId` (string): ID of the spreadsheet.
    - `range` (string): Cell range in A1 notation (e.g., `'Sheet1!A1'`).
    - `value` (string): New cell value.
  - **Output**: Confirms the updated value in the specified cell.

- **gdrive_create_file**
  - **Description**: Create a new file in Google Drive.
  - **Input**:
    - `name` (string): Name of the file to create.
    - `content` (string): Content of the file.
    - `mimeType` (string, optional): MIME type of the file (default: text/plain).
    - `folderId` (string, optional): ID of the parent folder.
  - **Output**: Returns file details including ID and view link.

- **gdrive_update_file**
  - **Description**: Update the content of an existing file in Google Drive.
  - **Input**:
    - `fileId` (string): ID of the file to update.
    - `content` (string): New content for the file.
  - **Output**: Returns updated file details.

- **gsheets_create_spreadsheet**
  - **Description**: Create a new Google Spreadsheet.
  - **Input**:
    - `title` (string): Title of the spreadsheet.
    - `sheetNames` (array of strings, optional): Names of initial sheets.
  - **Output**: Returns spreadsheet ID and URL.

- **gsheets_update_range**
  - **Description**: Update multiple cells in a Google Spreadsheet at once.
  - **Input**:
    - `spreadsheetId` (string): ID of the spreadsheet.
    - `range` (string): Range in A1 notation (e.g., `'Sheet1!A1:C3'`).
    - `values` (array): 2D array of values to write.
  - **Output**: Returns count of updated cells, rows, and columns.

- **gdrive_create_folder**
  - **Description**: Create a new folder in Google Drive.
  - **Input**:
    - `name` (string): Name of the folder to create.
    - `parentId` (string, optional): ID of the parent folder.
  - **Output**: Returns folder ID and web link.

- **gdrive_move_file**
  - **Description**: Move a file to a different folder in Google Drive.
  - **Input**:
    - `fileId` (string): ID of the file to move.
    - `newParentId` (string): ID of the destination folder.
  - **Output**: Returns updated file details.

- **gdrive_analyze_pdf**
  - **Description**: Analyze PDF files from Google Drive using Gemini 2.5 Flash AI model.
  - **Input**:
    - `fileId` (string): ID of the PDF file in Google Drive.
    - `prompt` (string): Analysis instructions or questions.
    - `useThinking` (boolean, optional): Use thinking mode for complex analysis.
    - `maxReasoningTokens` (number, optional): Max tokens for reasoning (default: 5000).
  - **Output**: Returns AI-generated analysis of the PDF content.

- **local_analyze_pdf**
  - **Description**: Analyze local PDF files using Gemini 2.5 Flash AI model.
  - **Input**:
    - `filePath` (string): Absolute path to the local PDF file.
    - `prompt` (string): Analysis instructions or questions.
    - `useThinking` (boolean, optional): Use thinking mode for complex analysis.
    - `maxReasoningTokens` (number, optional): Max tokens for reasoning (default: 5000).
  - **Output**: Returns AI-generated analysis of the PDF content.

### Resources

The server provides access to Google Drive files:

- **Files** (`gdrive:///<file_id>`)
  - Supports all file types
  - Google Workspace files are automatically exported:
    - Docs → Markdown
    - Sheets → CSV
    - Presentations → Plain text
    - Drawings → PNG
  - Other files are provided in their native format

## Prerequisites

### 1. Google Cloud Setup

1. [Create a new Google Cloud project](https://console.cloud.google.com/projectcreate)
2. [Enable the Google Drive API](https://console.cloud.google.com/workspace-api/products)
3. [Configure an OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) ("internal" is fine for testing)
4. Add OAuth scopes `https://www.googleapis.com/auth/drive`, `https://www.googleapis.com/auth/spreadsheets`
5. Enable the [Google Sheets API](https://console.cloud.google.com/apis/api/sheets.googleapis.com/) and [Google Docs API](https://console.cloud.google.com/marketplace/product/google/docs.googleapis.com)
6. [Create an OAuth Client ID](https://console.cloud.google.com/apis/credentials/oauthclient) for application type "Desktop App"
7. Download the JSON file of your client's OAuth keys
8. Rename the key file to `gcp-oauth.keys.json` and place in your credentials directory (e.g., `/Users/username/.config/mcp-gdrive`)
9. Note your OAuth Client ID and Client Secret

### 2. OpenRouter Setup (for PDF analysis)

1. Sign up at [OpenRouter.ai](https://openrouter.ai)
2. Get your API key from the dashboard

## Installation for Claude Code Users

See the [Quick Start](#quick-start---install-in-claude-code) section at the top of this README for the fastest way to add this server to Claude Code.

## Development Setup

For local development or manual installation:

### 1. Clone and Build

```bash
git clone https://github.com/markov-kernel/google-drive-mcp.git
cd google-drive-mcp
npm install
npm run build
```

### 2. Configure Environment

Create a `.env` file in the project root:

```
GDRIVE_CREDS_DIR=/path/to/config/directory
CLIENT_ID=<CLIENT_ID>
CLIENT_SECRET=<CLIENT_SECRET>
OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>
```

### 3. Build the Server

Make sure to build the server with either `npm run build` or `npm run watch`.

### 4. Initial Authentication

Run the authentication flow:

```bash
node ./dist/index.js
```

This will open your browser for authentication. You must authenticate with an account in the same organization as your Google Cloud project.

Your OAuth token is saved in the directory specified by the `GDRIVE_CREDS_DIR` environment variable.

**Important**: If you previously authenticated with read-only access, you will need to delete your saved credentials and re-authenticate to enable write access. Delete the file `.gdrive-server-credentials.json` from your `GDRIVE_CREDS_DIR` and run the authentication step again.

![Authentication Prompt](https://i.imgur.com/TbyV6Yq.png)

### Alternative: Manual Configuration

If you prefer to manually configure, add the following to your Claude Code server configuration:

```json
{
  "mcpServers": {
    "gdrive": {
      "command": "npx",
      "args": ["-y", "mcp-gdrive-enhanced-markov"],
      "env": {
        "CLIENT_ID": "<CLIENT_ID>",
        "CLIENT_SECRET": "<CLIENT_SECRET>",
        "GDRIVE_CREDS_DIR": "/path/to/config/directory",
        "OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
      }
    }
  }
}
```


## License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.