> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Gdrive

# Google Drive MCP

The Google Drive MCP server (`gdrive-mcp`) gives agents direct access to Google Drive for file operations. It exposes 6 tools: list, search, info, mkdir, upload, and download.

<Note>
  This page documents **agent-level Google Drive tools** for file operations via MCP. For the Equa platform's Data Room Google Drive sync feature, see [Google Drive Sync](/guides/google-drive-sync).
</Note>

## When to use

| Use this (agent GDrive tools) when                                            | Use [platform Google Drive Sync](/guides/google-drive-sync) when |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Agents need to create folders, upload files, or search Drive programmatically | Users want to sync a Google Drive folder into an Equa Data Room  |
| Task thread automation needs GDrive folder creation                           | Ongoing automatic file synchronization is needed                 |
| You need file metadata (owners, sharing status, web links)                    | Read-only Data Room mirroring is sufficient                      |

## Prerequisites

| Requirement                      | How to verify                                                               |
| -------------------------------- | --------------------------------------------------------------------------- |
| **Node.js 18+**                  | `node --version`                                                            |
| **Google Workspace OAuth token** | File exists at `~/.config/google-workspace/token.json` with `refresh_token` |
| **Comet-Bridge repo**            | `gdrive-mcp/` directory exists at `Comet-Bridge/gdrive-mcp/`                |
| **Built server**                 | `npm run build` in `Comet-Bridge/gdrive-mcp/` produces `dist/index.js`      |

## Setup

### 1. Build the server

```bash theme={null}
cd Comet-Bridge/gdrive-mcp
npm install
npm run build
```

### 2. Register in Cursor MCP config

Add to `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/path/to/Comet-Bridge/gdrive-mcp/dist/index.js"]
    }
  }
}
```

Restart Cursor to pick up the new server. The 6 `gdrive_*` tools will appear in the MCP tool list.

### 3. Authentication

The server reuses the existing Google Workspace OAuth token at `~/.config/google-workspace/token.json`. No new OAuth flow is required. The token is shared with the Python Google Workspace skill scripts; both systems read and write the same file.

When the access token expires, the server refreshes it automatically and writes the updated token back in a format compatible with both Node.js and Python.

## Tools

### gdrive\_list

List files and folders in Google Drive.

| Parameter   | Type   | Required | Description                                |
| ----------- | ------ | -------- | ------------------------------------------ |
| `folderId`  | string | No       | Folder ID to list. Omit for root.          |
| `limit`     | number | No       | Max files to return (default 20).          |
| `pageToken` | string | No       | Pagination token from a previous response. |

Returns an array of file objects with `id`, `name`, `mimeType`, `size`, `modifiedTime`, and `webViewLink`. Includes `nextPageToken` when more results are available.

### gdrive\_search

Full-text search across Google Drive files.

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `query`   | string | Yes      | Search query text.        |
| `limit`   | number | No       | Max results (default 20). |

### gdrive\_info

Get detailed metadata for a file.

| Parameter | Type   | Required | Description           |
| --------- | ------ | -------- | --------------------- |
| `fileId`  | string | Yes      | Google Drive file ID. |

Returns: `id`, `name`, `mimeType`, `size`, `modifiedTime`, `createdTime`, `webViewLink`, `owners`, `shared`, `parents`.

### gdrive\_mkdir

Create a new folder.

| Parameter  | Type   | Required | Description                      |
| ---------- | ------ | -------- | -------------------------------- |
| `name`     | string | Yes      | Folder name.                     |
| `parentId` | string | No       | Parent folder ID. Omit for root. |

Returns: `id`, `name`, `webViewLink`.

### gdrive\_upload

Upload a local file to Google Drive.

| Parameter   | Type   | Required | Description                                  |
| ----------- | ------ | -------- | -------------------------------------------- |
| `localPath` | string | Yes      | Absolute path to the local file.             |
| `folderId`  | string | No       | Destination folder ID. Omit for root.        |
| `name`      | string | No       | Remote filename. Defaults to local filename. |

Returns: `id`, `name`, `webViewLink`.

### gdrive\_download

Download a file from Google Drive. Google Docs, Sheets, and Slides are automatically exported to Office formats (DOCX, XLSX, PPTX).

| Parameter    | Type   | Required | Description                                                             |
| ------------ | ------ | -------- | ----------------------------------------------------------------------- |
| `fileId`     | string | Yes      | Google Drive file ID.                                                   |
| `outputPath` | string | No       | Local path to save. Defaults to the file name in the current directory. |

Returns: `downloaded` (file path) and `size` (bytes).

## Architecture

```
Cursor Agent
  │
  └─ MCP tools (gdrive_list, gdrive_search, gdrive_info, ...)
        └─ gdrive-mcp stdio server
              ├─ google-auth-library (OAuth2Client)
              │     └─ ~/.config/google-workspace/token.json
              └─ googleapis (Drive v3 API)
                    └─ Google Drive REST API
```

The server lives at `Comet-Bridge/gdrive-mcp/` alongside the `comet-mcp` browser automation server. Both use the `@modelcontextprotocol/sdk` with `StdioServerTransport`.

## Token management

The OAuth token at `~/.config/google-workspace/token.json` is shared between:

* **gdrive-mcp** (this Node.js MCP server)
* **Python Google Workspace scripts** (`equabot/skills/google-workspace/scripts/`)

Both systems can read and refresh the token. When gdrive-mcp refreshes an expired token, it writes back in the exact Python `google-auth` format (field name `token` instead of `access_token`, ISO 8601 `expiry` string) using atomic write (tmp file + rename) to prevent corruption from concurrent access.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tools not appearing in Cursor">
    Verify the `gdrive` entry in `~/.cursor/mcp.json` points to the correct `dist/index.js` path. Restart Cursor after editing `mcp.json`.
  </Accordion>

  <Accordion title="Authentication error (401)">
    The token may have been revoked. Re-run the Python auth script to generate a fresh token: `python equabot/skills/google-workspace/scripts/google_auth.py`
  </Accordion>

  <Accordion title="Token refresh not persisting">
    Check that the MCP server process has write permission to `~/.config/google-workspace/token.json`. The atomic write creates a temporary file in the same directory before renaming.
  </Accordion>
</AccordionGroup>

## Related

* [Comet Browser (Comet-Bridge)](/tools/comet-browser) -- Browser automation MCP server in the same repo
* [Google Drive Sync](/guides/google-drive-sync) -- Platform Data Room sync feature (different from agent tools)
* [Google Drive API Endpoints](/api/endpoints/google-drive-endpoints) -- Platform REST API for Data Room sync