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.

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.

When to use

Use this (agent GDrive tools) when	Use platform 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

cd Comet-Bridge/gdrive-mcp
npm install
npm run build

2. Register in Cursor MCP config

Add to ~/.cursor/mcp.json:

{
  "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

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.

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

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.

Related

• Comet Browser (Comet-Bridge) — Browser automation MCP server in the same repo
• Google Drive Sync — Platform Data Room sync feature (different from agent tools)
• Google Drive API Endpoints — Platform REST API for Data Room sync