# google-drive-comments-mcp

<!-- mcp-name: io.github.zayansalman/google-drive-comments-mcp -->

A focused [Model Context Protocol](https://modelcontextprotocol.io) server (and standalone CLI) for **reading comments** on Google Drive files — Docs, Sheets, and Slides. Two tools, read-only OAuth scope, no extra surface area.

Built because the hosted Google Drive connectors expose file **content** and search, but not the **comment threads** — the review discussion, the anchored quotes, the resolve/reopen history. This server fills that gap for any MCP client (Claude Code, Claude Desktop, Cursor, Cline, etc.), and also works as a plain CLI.

## Features

- **2 MCP tools** — `drive_search_files`, `drive_get_comments`. That's the whole API.
- **Reads full comment threads** — author, content, the **anchored quoted text**, resolved/open status, and every reply (with resolve/reopen actions).
- **Works across Docs, Sheets, and Slides** — the Drive comments API is uniform across file types.
- **Accepts URLs or IDs** — paste a `docs.google.com/document/d/…` link or a bare file ID.
- **Read-only OAuth scope** (`drive.readonly`).
- **Env-var-driven config** — `DRIVE_MCP_CREDENTIALS`, `DRIVE_MCP_TOKEN`, `DRIVE_MCP_SCOPES`.

## Install

```bash
pip install google-drive-comments-mcp
# or, with uv:
uv tool install google-drive-comments-mcp
```

## One-time setup (~10 minutes)

You need a Google Cloud OAuth client. The server runs entirely on your machine; nothing leaves it.

1. Sign in to [Google Cloud Console](https://console.cloud.google.com/) with the account whose Drive comments you want to read.
2. Create a project (or pick an existing one).
3. Enable the Drive API: [console.cloud.google.com/apis/library/drive.googleapis.com](https://console.cloud.google.com/apis/library/drive.googleapis.com).
4. Configure the OAuth consent screen under **APIs & Services → OAuth consent screen**:
   - **Google Workspace** users: User type = **Internal**. No app verification is needed even though `drive.readonly` is a restricted scope.
   - **Personal Gmail** users: User type = **External**, and add your own address under "Test users".
5. **APIs & Services → Credentials → + Create credentials → OAuth client ID**
   - Application type: **Desktop app**
   - Download the JSON.
6. Run setup:

```bash
google-drive-comments-mcp setup --import-credentials ~/Downloads/client_secret_*.json
```

A browser window opens for OAuth consent. The refresh token is cached at `~/.config/google-drive-comments-mcp/token.json`.

Verify:
```bash
google-drive-comments-mcp status
google-drive-comments-mcp comments "https://docs.google.com/document/d/YOUR_DOC_ID/edit"
```

## Use it from Claude Code

```bash
claude mcp add --scope user google-drive-comments google-drive-comments-mcp -- serve
```

Then:
> Read the open comments on this doc and summarize what reviewers are asking for: https://docs.google.com/document/d/…

## Use it from Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (Mac):

```json
{
  "mcpServers": {
    "google-drive-comments": {
      "command": "google-drive-comments-mcp",
      "args": ["serve"]
    }
  }
}
```

(Use the absolute path from `which google-drive-comments-mcp` if it isn't on Claude Desktop's `$PATH`.)

## Use it from the shell

```bash
# Find a doc
google-drive-comments-mcp search "Q3 strategy"

# Read all comments (open + resolved) on a doc by URL or ID
google-drive-comments-mcp comments "https://docs.google.com/document/d/abc123/edit"

# Only unresolved comments
google-drive-comments-mcp comments abc123 --open-only
```

## The 2 MCP tools

### `drive_search_files(query, max_results=10)`
Search Drive. Plain strings are auto-wrapped as a filename search; raw Drive query syntax passes through.

```json
[
  {
    "id": "1AbC…",
    "name": "Q3 Strategy",
    "mime_type": "application/vnd.google-apps.document",
    "modified": "2026-04-20T09:00:00.000Z",
    "owners": ["Jane Doe"],
    "web_view_link": "https://docs.google.com/document/d/1AbC…/edit"
  }
]
```

### `drive_get_comments(file, include_resolved=True)`
Read all comments on a file. `file` accepts a Docs/Sheets/Slides/Drive URL **or** a bare file ID.

```json
{
  "file": { "id": "1AbC…", "name": "Q3 Strategy", "mime_type": "…document", "web_view_link": "…", "owners": ["Jane Doe"] },
  "open_count": 2,
  "resolved_count": 1,
  "comments": [
    {
      "id": "AAAA…",
      "author": "Jane Doe",
      "content": "Can we add the unit-economics table here?",
      "quoted_text": "Our margins improved in Q3.",
      "resolved": false,
      "created": "2026-04-21T10:00:00Z",
      "modified": "2026-04-21T10:00:00Z",
      "replies": [
        { "author": "John Smith", "content": "Added.", "action": "", "created": "2026-04-21T11:00:00Z" }
      ]
    }
  ]
}
```

`quoted_text` is the document text the comment is anchored to — useful context for understanding what each comment refers to.

## Configuration

| Variable | Default | What |
|---|---|---|
| `DRIVE_MCP_CREDENTIALS` | `~/.config/google-drive-comments-mcp/credentials.json` | OAuth client secret JSON |
| `DRIVE_MCP_TOKEN` | `~/.config/google-drive-comments-mcp/token.json` | Cached refresh token |
| `DRIVE_MCP_SCOPES` | `https://www.googleapis.com/auth/drive.readonly` | OAuth scopes (comma-separated) |
| `XDG_CONFIG_HOME` | `~/.config` | Standard XDG override |

### Sharing one login with other Google MCP tools

If you also run a sibling tool (e.g. [`gmail-attachments-mcp`](https://github.com/zayansalman/gmail-attachments-mcp)) and want a single OAuth consent for both, point both tools at the same credential + token files (via the env vars above, or symlinks) and authorize once with the **combined** scopes:

```bash
DRIVE_MCP_SCOPES="https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/drive.readonly" \
  google-drive-comments-mcp setup --reauth
```

A token granted a superset of scopes satisfies each tool's narrower request.

## Security

- **Read-only**: the default scope is `drive.readonly`. It cannot edit, comment, or delete — only read file metadata, content, and comments.
- **Scope breadth**: `drive.readonly` grants read access to **all** your Drive files, not just the one you query. There is no per-file read scope that also exposes comments. Treat the cached token like a password (it's written `0600`).
- **No telemetry**: your OAuth client lives in your own Google Cloud project. Nothing leaves your machine.

## Troubleshooting

**`HttpError 403: Google Drive API has not been used in project … before or it is disabled`**
Enable the Drive API on the project that owns your OAuth client, then retry.

**`No valid Google token` from Claude Desktop / cron**
Run `google-drive-comments-mcp setup` once in a terminal where a browser can open. Subsequent runs reuse the cached token.

**Comments come back empty on a file you know has comments**
Confirm you authorized the account that can actually see the file, and that the file genuinely has comments (suggestions are not comments). Resolved comments are included unless you pass `--open-only` / `include_resolved=false`.

## Authentication — bring your own Google OAuth client

There are **no API keys and no shipped secrets**. The server authenticates to *your* Google account with an OAuth client *you* create, and caches a refresh token locally. The author has zero access to your data.

- **Why your own client?** Google's restricted scopes (here, `drive.readonly`) can't be redistributed in a shared app, and an unverified shared app is capped at 100 users. "Bring your own OAuth client" is the standard pattern for personal-data MCP servers.
- **What you need:** a free Google Cloud project, the Drive API enabled, an OAuth consent screen, and a Desktop OAuth client. Full walkthrough → [docs/setup-google-oauth.md](docs/setup-google-oauth.md).
- **Where your token lives:** `~/.config/google-drive-comments-mcp/token.json` (mode `0600`). Delete it to revoke locally; revoke fully at [myaccount.google.com/permissions](https://myaccount.google.com/permissions).
- **No hosted/SaaS option** — everything runs locally; your Drive data never touches a third-party server.

## More guides

- [docs/setup-google-oauth.md](docs/setup-google-oauth.md) — full OAuth walkthrough + common errors
- [docs/claude-code.md](docs/claude-code.md) · [docs/claude-desktop.md](docs/claude-desktop.md) · [docs/other-clients.md](docs/other-clients.md) — per-client setup (Cursor, Cline, Continue, …)
- [examples/](examples/) — runnable snippets

## Related tools

Part of a small family of focused, local MCP servers for Google Workspace data the hosted connectors don't expose:

- **[gmail-attachments-mcp](https://github.com/zayansalman/gmail-attachments-mcp)** — download Gmail attachment bytes to disk
- **google-drive-comments-mcp** — read comment threads on Docs/Sheets/Slides *(this repo)*
- **[google-drive-files-mcp](https://github.com/zayansalman/google-drive-files-mcp)** — move/organize Drive files

They can share one OAuth login or stay isolated — see each repo's setup.

## License

MIT. See [LICENSE](LICENSE).