google-drive-comments-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- google_drive_comments_mcp-0.1.0/.github/workflows/ci.yml +35 -0
- google_drive_comments_mcp-0.1.0/.github/workflows/release.yml +45 -0
- google_drive_comments_mcp-0.1.0/.gitignore +39 -0
- google_drive_comments_mcp-0.1.0/LICENSE +21 -0
- google_drive_comments_mcp-0.1.0/PKG-INFO +232 -0
- google_drive_comments_mcp-0.1.0/README.md +201 -0
- google_drive_comments_mcp-0.1.0/docs/claude-code.md +23 -0
- google_drive_comments_mcp-0.1.0/docs/claude-desktop.md +43 -0
- google_drive_comments_mcp-0.1.0/docs/other-clients.md +32 -0
- google_drive_comments_mcp-0.1.0/docs/setup-google-oauth.md +52 -0
- google_drive_comments_mcp-0.1.0/examples/dump-open-comments.sh +16 -0
- google_drive_comments_mcp-0.1.0/pyproject.toml +60 -0
- google_drive_comments_mcp-0.1.0/server.json +50 -0
- google_drive_comments_mcp-0.1.0/src/google_drive_comments_mcp/__init__.py +2 -0
- google_drive_comments_mcp-0.1.0/src/google_drive_comments_mcp/__main__.py +5 -0
- google_drive_comments_mcp-0.1.0/src/google_drive_comments_mcp/auth.py +84 -0
- google_drive_comments_mcp-0.1.0/src/google_drive_comments_mcp/cli.py +158 -0
- google_drive_comments_mcp-0.1.0/src/google_drive_comments_mcp/client.py +162 -0
- google_drive_comments_mcp-0.1.0/src/google_drive_comments_mcp/config.py +49 -0
- google_drive_comments_mcp-0.1.0/src/google_drive_comments_mcp/server.py +67 -0
- google_drive_comments_mcp-0.1.0/tests/__init__.py +0 -0
- google_drive_comments_mcp-0.1.0/tests/test_client.py +94 -0
- google_drive_comments_mcp-0.1.0/tests/test_config.py +51 -0
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ${{ matrix.os }}
|
|
12
|
+
strategy:
|
|
13
|
+
fail-fast: false
|
|
14
|
+
matrix:
|
|
15
|
+
os: [ubuntu-latest, macos-latest]
|
|
16
|
+
python-version: ["3.10", "3.11", "3.12", "3.13"]
|
|
17
|
+
|
|
18
|
+
steps:
|
|
19
|
+
- uses: actions/checkout@v4
|
|
20
|
+
|
|
21
|
+
- name: Set up Python ${{ matrix.python-version }}
|
|
22
|
+
uses: actions/setup-python@v5
|
|
23
|
+
with:
|
|
24
|
+
python-version: ${{ matrix.python-version }}
|
|
25
|
+
|
|
26
|
+
- name: Install
|
|
27
|
+
run: |
|
|
28
|
+
python -m pip install --upgrade pip
|
|
29
|
+
pip install -e ".[dev]"
|
|
30
|
+
|
|
31
|
+
- name: Lint
|
|
32
|
+
run: ruff check src tests
|
|
33
|
+
|
|
34
|
+
- name: Test
|
|
35
|
+
run: pytest -v
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
name: Release to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags:
|
|
6
|
+
- "v*"
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
build:
|
|
10
|
+
name: Build distributions
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
steps:
|
|
13
|
+
- uses: actions/checkout@v4
|
|
14
|
+
|
|
15
|
+
- uses: actions/setup-python@v5
|
|
16
|
+
with:
|
|
17
|
+
python-version: "3.12"
|
|
18
|
+
|
|
19
|
+
- name: Install build tool
|
|
20
|
+
run: python -m pip install --upgrade build
|
|
21
|
+
|
|
22
|
+
- name: Build sdist + wheel
|
|
23
|
+
run: python -m build
|
|
24
|
+
|
|
25
|
+
- uses: actions/upload-artifact@v4
|
|
26
|
+
with:
|
|
27
|
+
name: dist
|
|
28
|
+
path: dist/
|
|
29
|
+
|
|
30
|
+
publish:
|
|
31
|
+
name: Publish to PyPI
|
|
32
|
+
needs: build
|
|
33
|
+
runs-on: ubuntu-latest
|
|
34
|
+
environment:
|
|
35
|
+
name: pypi
|
|
36
|
+
url: https://pypi.org/project/google-drive-comments-mcp/
|
|
37
|
+
permissions:
|
|
38
|
+
id-token: write # OIDC for PyPI Trusted Publishing — no long-lived token needed
|
|
39
|
+
steps:
|
|
40
|
+
- uses: actions/download-artifact@v4
|
|
41
|
+
with:
|
|
42
|
+
name: dist
|
|
43
|
+
path: dist/
|
|
44
|
+
|
|
45
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
.Python
|
|
7
|
+
*.egg-info/
|
|
8
|
+
*.egg
|
|
9
|
+
dist/
|
|
10
|
+
build/
|
|
11
|
+
.eggs/
|
|
12
|
+
|
|
13
|
+
# Virtual envs
|
|
14
|
+
.venv/
|
|
15
|
+
venv/
|
|
16
|
+
env/
|
|
17
|
+
.env
|
|
18
|
+
|
|
19
|
+
# Tooling
|
|
20
|
+
.pytest_cache/
|
|
21
|
+
.ruff_cache/
|
|
22
|
+
.mypy_cache/
|
|
23
|
+
.coverage
|
|
24
|
+
htmlcov/
|
|
25
|
+
.tox/
|
|
26
|
+
|
|
27
|
+
# Editors / OS
|
|
28
|
+
.vscode/
|
|
29
|
+
.idea/
|
|
30
|
+
*.swp
|
|
31
|
+
.DS_Store
|
|
32
|
+
Thumbs.db
|
|
33
|
+
|
|
34
|
+
# Credentials — NEVER commit
|
|
35
|
+
credentials.json
|
|
36
|
+
token.json
|
|
37
|
+
client_secret*.json
|
|
38
|
+
*.pem
|
|
39
|
+
*.key
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Zayan Khan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: google-drive-comments-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A minimal MCP server and CLI for reading comments on Google Drive files (Docs, Sheets, Slides).
|
|
5
|
+
Project-URL: Homepage, https://github.com/zayansalman/google-drive-comments-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/zayansalman/google-drive-comments-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/zayansalman/google-drive-comments-mcp/issues
|
|
8
|
+
Author: Zayan Khan
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: anthropic,claude,comments,google-docs,google-drive,mcp,model-context-protocol
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Office/Business
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: google-api-python-client>=2.100.0
|
|
24
|
+
Requires-Dist: google-auth-httplib2>=0.2.0
|
|
25
|
+
Requires-Dist: google-auth-oauthlib>=1.0.0
|
|
26
|
+
Requires-Dist: mcp>=1.0.0
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
29
|
+
Requires-Dist: ruff>=0.1; extra == 'dev'
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# google-drive-comments-mcp
|
|
33
|
+
|
|
34
|
+
<!-- mcp-name: io.github.zayansalman/google-drive-comments-mcp -->
|
|
35
|
+
|
|
36
|
+
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.
|
|
37
|
+
|
|
38
|
+
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.
|
|
39
|
+
|
|
40
|
+
## Features
|
|
41
|
+
|
|
42
|
+
- **2 MCP tools** — `drive_search_files`, `drive_get_comments`. That's the whole API.
|
|
43
|
+
- **Reads full comment threads** — author, content, the **anchored quoted text**, resolved/open status, and every reply (with resolve/reopen actions).
|
|
44
|
+
- **Works across Docs, Sheets, and Slides** — the Drive comments API is uniform across file types.
|
|
45
|
+
- **Accepts URLs or IDs** — paste a `docs.google.com/document/d/…` link or a bare file ID.
|
|
46
|
+
- **Read-only OAuth scope** (`drive.readonly`).
|
|
47
|
+
- **Env-var-driven config** — `DRIVE_MCP_CREDENTIALS`, `DRIVE_MCP_TOKEN`, `DRIVE_MCP_SCOPES`.
|
|
48
|
+
|
|
49
|
+
## Install
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
pip install google-drive-comments-mcp
|
|
53
|
+
# or, with uv:
|
|
54
|
+
uv tool install google-drive-comments-mcp
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## One-time setup (~10 minutes)
|
|
58
|
+
|
|
59
|
+
You need a Google Cloud OAuth client. The server runs entirely on your machine; nothing leaves it.
|
|
60
|
+
|
|
61
|
+
1. Sign in to [Google Cloud Console](https://console.cloud.google.com/) with the account whose Drive comments you want to read.
|
|
62
|
+
2. Create a project (or pick an existing one).
|
|
63
|
+
3. Enable the Drive API: [console.cloud.google.com/apis/library/drive.googleapis.com](https://console.cloud.google.com/apis/library/drive.googleapis.com).
|
|
64
|
+
4. Configure the OAuth consent screen under **APIs & Services → OAuth consent screen**:
|
|
65
|
+
- **Google Workspace** users: User type = **Internal**. No app verification is needed even though `drive.readonly` is a restricted scope.
|
|
66
|
+
- **Personal Gmail** users: User type = **External**, and add your own address under "Test users".
|
|
67
|
+
5. **APIs & Services → Credentials → + Create credentials → OAuth client ID**
|
|
68
|
+
- Application type: **Desktop app**
|
|
69
|
+
- Download the JSON.
|
|
70
|
+
6. Run setup:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
google-drive-comments-mcp setup --import-credentials ~/Downloads/client_secret_*.json
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
A browser window opens for OAuth consent. The refresh token is cached at `~/.config/google-drive-comments-mcp/token.json`.
|
|
77
|
+
|
|
78
|
+
Verify:
|
|
79
|
+
```bash
|
|
80
|
+
google-drive-comments-mcp status
|
|
81
|
+
google-drive-comments-mcp comments "https://docs.google.com/document/d/YOUR_DOC_ID/edit"
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Use it from Claude Code
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
claude mcp add --scope user google-drive-comments google-drive-comments-mcp -- serve
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Then:
|
|
91
|
+
> Read the open comments on this doc and summarize what reviewers are asking for: https://docs.google.com/document/d/…
|
|
92
|
+
|
|
93
|
+
## Use it from Claude Desktop
|
|
94
|
+
|
|
95
|
+
`~/Library/Application Support/Claude/claude_desktop_config.json` (Mac):
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"mcpServers": {
|
|
100
|
+
"google-drive-comments": {
|
|
101
|
+
"command": "google-drive-comments-mcp",
|
|
102
|
+
"args": ["serve"]
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
(Use the absolute path from `which google-drive-comments-mcp` if it isn't on Claude Desktop's `$PATH`.)
|
|
109
|
+
|
|
110
|
+
## Use it from the shell
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
# Find a doc
|
|
114
|
+
google-drive-comments-mcp search "Q3 strategy"
|
|
115
|
+
|
|
116
|
+
# Read all comments (open + resolved) on a doc by URL or ID
|
|
117
|
+
google-drive-comments-mcp comments "https://docs.google.com/document/d/abc123/edit"
|
|
118
|
+
|
|
119
|
+
# Only unresolved comments
|
|
120
|
+
google-drive-comments-mcp comments abc123 --open-only
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## The 2 MCP tools
|
|
124
|
+
|
|
125
|
+
### `drive_search_files(query, max_results=10)`
|
|
126
|
+
Search Drive. Plain strings are auto-wrapped as a filename search; raw Drive query syntax passes through.
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
[
|
|
130
|
+
{
|
|
131
|
+
"id": "1AbC…",
|
|
132
|
+
"name": "Q3 Strategy",
|
|
133
|
+
"mime_type": "application/vnd.google-apps.document",
|
|
134
|
+
"modified": "2026-04-20T09:00:00.000Z",
|
|
135
|
+
"owners": ["Jane Doe"],
|
|
136
|
+
"web_view_link": "https://docs.google.com/document/d/1AbC…/edit"
|
|
137
|
+
}
|
|
138
|
+
]
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### `drive_get_comments(file, include_resolved=True)`
|
|
142
|
+
Read all comments on a file. `file` accepts a Docs/Sheets/Slides/Drive URL **or** a bare file ID.
|
|
143
|
+
|
|
144
|
+
```json
|
|
145
|
+
{
|
|
146
|
+
"file": { "id": "1AbC…", "name": "Q3 Strategy", "mime_type": "…document", "web_view_link": "…", "owners": ["Jane Doe"] },
|
|
147
|
+
"open_count": 2,
|
|
148
|
+
"resolved_count": 1,
|
|
149
|
+
"comments": [
|
|
150
|
+
{
|
|
151
|
+
"id": "AAAA…",
|
|
152
|
+
"author": "Jane Doe",
|
|
153
|
+
"content": "Can we add the unit-economics table here?",
|
|
154
|
+
"quoted_text": "Our margins improved in Q3.",
|
|
155
|
+
"resolved": false,
|
|
156
|
+
"created": "2026-04-21T10:00:00Z",
|
|
157
|
+
"modified": "2026-04-21T10:00:00Z",
|
|
158
|
+
"replies": [
|
|
159
|
+
{ "author": "John Smith", "content": "Added.", "action": "", "created": "2026-04-21T11:00:00Z" }
|
|
160
|
+
]
|
|
161
|
+
}
|
|
162
|
+
]
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
`quoted_text` is the document text the comment is anchored to — useful context for understanding what each comment refers to.
|
|
167
|
+
|
|
168
|
+
## Configuration
|
|
169
|
+
|
|
170
|
+
| Variable | Default | What |
|
|
171
|
+
|---|---|---|
|
|
172
|
+
| `DRIVE_MCP_CREDENTIALS` | `~/.config/google-drive-comments-mcp/credentials.json` | OAuth client secret JSON |
|
|
173
|
+
| `DRIVE_MCP_TOKEN` | `~/.config/google-drive-comments-mcp/token.json` | Cached refresh token |
|
|
174
|
+
| `DRIVE_MCP_SCOPES` | `https://www.googleapis.com/auth/drive.readonly` | OAuth scopes (comma-separated) |
|
|
175
|
+
| `XDG_CONFIG_HOME` | `~/.config` | Standard XDG override |
|
|
176
|
+
|
|
177
|
+
### Sharing one login with other Google MCP tools
|
|
178
|
+
|
|
179
|
+
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:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
DRIVE_MCP_SCOPES="https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/drive.readonly" \
|
|
183
|
+
google-drive-comments-mcp setup --reauth
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
A token granted a superset of scopes satisfies each tool's narrower request.
|
|
187
|
+
|
|
188
|
+
## Security
|
|
189
|
+
|
|
190
|
+
- **Read-only**: the default scope is `drive.readonly`. It cannot edit, comment, or delete — only read file metadata, content, and comments.
|
|
191
|
+
- **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`).
|
|
192
|
+
- **No telemetry**: your OAuth client lives in your own Google Cloud project. Nothing leaves your machine.
|
|
193
|
+
|
|
194
|
+
## Troubleshooting
|
|
195
|
+
|
|
196
|
+
**`HttpError 403: Google Drive API has not been used in project … before or it is disabled`**
|
|
197
|
+
Enable the Drive API on the project that owns your OAuth client, then retry.
|
|
198
|
+
|
|
199
|
+
**`No valid Google token` from Claude Desktop / cron**
|
|
200
|
+
Run `google-drive-comments-mcp setup` once in a terminal where a browser can open. Subsequent runs reuse the cached token.
|
|
201
|
+
|
|
202
|
+
**Comments come back empty on a file you know has comments**
|
|
203
|
+
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`.
|
|
204
|
+
|
|
205
|
+
## Authentication — bring your own Google OAuth client
|
|
206
|
+
|
|
207
|
+
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.
|
|
208
|
+
|
|
209
|
+
- **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.
|
|
210
|
+
- **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).
|
|
211
|
+
- **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).
|
|
212
|
+
- **No hosted/SaaS option** — everything runs locally; your Drive data never touches a third-party server.
|
|
213
|
+
|
|
214
|
+
## More guides
|
|
215
|
+
|
|
216
|
+
- [docs/setup-google-oauth.md](docs/setup-google-oauth.md) — full OAuth walkthrough + common errors
|
|
217
|
+
- [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, …)
|
|
218
|
+
- [examples/](examples/) — runnable snippets
|
|
219
|
+
|
|
220
|
+
## Related tools
|
|
221
|
+
|
|
222
|
+
Part of a small family of focused, local MCP servers for Google Workspace data the hosted connectors don't expose:
|
|
223
|
+
|
|
224
|
+
- **[gmail-attachments-mcp](https://github.com/zayansalman/gmail-attachments-mcp)** — download Gmail attachment bytes to disk
|
|
225
|
+
- **google-drive-comments-mcp** — read comment threads on Docs/Sheets/Slides *(this repo)*
|
|
226
|
+
- **[google-drive-files-mcp](https://github.com/zayansalman/google-drive-files-mcp)** — move/organize Drive files
|
|
227
|
+
|
|
228
|
+
They can share one OAuth login or stay isolated — see each repo's setup.
|
|
229
|
+
|
|
230
|
+
## License
|
|
231
|
+
|
|
232
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
# google-drive-comments-mcp
|
|
2
|
+
|
|
3
|
+
<!-- mcp-name: io.github.zayansalman/google-drive-comments-mcp -->
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- **2 MCP tools** — `drive_search_files`, `drive_get_comments`. That's the whole API.
|
|
12
|
+
- **Reads full comment threads** — author, content, the **anchored quoted text**, resolved/open status, and every reply (with resolve/reopen actions).
|
|
13
|
+
- **Works across Docs, Sheets, and Slides** — the Drive comments API is uniform across file types.
|
|
14
|
+
- **Accepts URLs or IDs** — paste a `docs.google.com/document/d/…` link or a bare file ID.
|
|
15
|
+
- **Read-only OAuth scope** (`drive.readonly`).
|
|
16
|
+
- **Env-var-driven config** — `DRIVE_MCP_CREDENTIALS`, `DRIVE_MCP_TOKEN`, `DRIVE_MCP_SCOPES`.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pip install google-drive-comments-mcp
|
|
22
|
+
# or, with uv:
|
|
23
|
+
uv tool install google-drive-comments-mcp
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## One-time setup (~10 minutes)
|
|
27
|
+
|
|
28
|
+
You need a Google Cloud OAuth client. The server runs entirely on your machine; nothing leaves it.
|
|
29
|
+
|
|
30
|
+
1. Sign in to [Google Cloud Console](https://console.cloud.google.com/) with the account whose Drive comments you want to read.
|
|
31
|
+
2. Create a project (or pick an existing one).
|
|
32
|
+
3. Enable the Drive API: [console.cloud.google.com/apis/library/drive.googleapis.com](https://console.cloud.google.com/apis/library/drive.googleapis.com).
|
|
33
|
+
4. Configure the OAuth consent screen under **APIs & Services → OAuth consent screen**:
|
|
34
|
+
- **Google Workspace** users: User type = **Internal**. No app verification is needed even though `drive.readonly` is a restricted scope.
|
|
35
|
+
- **Personal Gmail** users: User type = **External**, and add your own address under "Test users".
|
|
36
|
+
5. **APIs & Services → Credentials → + Create credentials → OAuth client ID**
|
|
37
|
+
- Application type: **Desktop app**
|
|
38
|
+
- Download the JSON.
|
|
39
|
+
6. Run setup:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
google-drive-comments-mcp setup --import-credentials ~/Downloads/client_secret_*.json
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
A browser window opens for OAuth consent. The refresh token is cached at `~/.config/google-drive-comments-mcp/token.json`.
|
|
46
|
+
|
|
47
|
+
Verify:
|
|
48
|
+
```bash
|
|
49
|
+
google-drive-comments-mcp status
|
|
50
|
+
google-drive-comments-mcp comments "https://docs.google.com/document/d/YOUR_DOC_ID/edit"
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Use it from Claude Code
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
claude mcp add --scope user google-drive-comments google-drive-comments-mcp -- serve
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Then:
|
|
60
|
+
> Read the open comments on this doc and summarize what reviewers are asking for: https://docs.google.com/document/d/…
|
|
61
|
+
|
|
62
|
+
## Use it from Claude Desktop
|
|
63
|
+
|
|
64
|
+
`~/Library/Application Support/Claude/claude_desktop_config.json` (Mac):
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"mcpServers": {
|
|
69
|
+
"google-drive-comments": {
|
|
70
|
+
"command": "google-drive-comments-mcp",
|
|
71
|
+
"args": ["serve"]
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
(Use the absolute path from `which google-drive-comments-mcp` if it isn't on Claude Desktop's `$PATH`.)
|
|
78
|
+
|
|
79
|
+
## Use it from the shell
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
# Find a doc
|
|
83
|
+
google-drive-comments-mcp search "Q3 strategy"
|
|
84
|
+
|
|
85
|
+
# Read all comments (open + resolved) on a doc by URL or ID
|
|
86
|
+
google-drive-comments-mcp comments "https://docs.google.com/document/d/abc123/edit"
|
|
87
|
+
|
|
88
|
+
# Only unresolved comments
|
|
89
|
+
google-drive-comments-mcp comments abc123 --open-only
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## The 2 MCP tools
|
|
93
|
+
|
|
94
|
+
### `drive_search_files(query, max_results=10)`
|
|
95
|
+
Search Drive. Plain strings are auto-wrapped as a filename search; raw Drive query syntax passes through.
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
[
|
|
99
|
+
{
|
|
100
|
+
"id": "1AbC…",
|
|
101
|
+
"name": "Q3 Strategy",
|
|
102
|
+
"mime_type": "application/vnd.google-apps.document",
|
|
103
|
+
"modified": "2026-04-20T09:00:00.000Z",
|
|
104
|
+
"owners": ["Jane Doe"],
|
|
105
|
+
"web_view_link": "https://docs.google.com/document/d/1AbC…/edit"
|
|
106
|
+
}
|
|
107
|
+
]
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### `drive_get_comments(file, include_resolved=True)`
|
|
111
|
+
Read all comments on a file. `file` accepts a Docs/Sheets/Slides/Drive URL **or** a bare file ID.
|
|
112
|
+
|
|
113
|
+
```json
|
|
114
|
+
{
|
|
115
|
+
"file": { "id": "1AbC…", "name": "Q3 Strategy", "mime_type": "…document", "web_view_link": "…", "owners": ["Jane Doe"] },
|
|
116
|
+
"open_count": 2,
|
|
117
|
+
"resolved_count": 1,
|
|
118
|
+
"comments": [
|
|
119
|
+
{
|
|
120
|
+
"id": "AAAA…",
|
|
121
|
+
"author": "Jane Doe",
|
|
122
|
+
"content": "Can we add the unit-economics table here?",
|
|
123
|
+
"quoted_text": "Our margins improved in Q3.",
|
|
124
|
+
"resolved": false,
|
|
125
|
+
"created": "2026-04-21T10:00:00Z",
|
|
126
|
+
"modified": "2026-04-21T10:00:00Z",
|
|
127
|
+
"replies": [
|
|
128
|
+
{ "author": "John Smith", "content": "Added.", "action": "", "created": "2026-04-21T11:00:00Z" }
|
|
129
|
+
]
|
|
130
|
+
}
|
|
131
|
+
]
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
`quoted_text` is the document text the comment is anchored to — useful context for understanding what each comment refers to.
|
|
136
|
+
|
|
137
|
+
## Configuration
|
|
138
|
+
|
|
139
|
+
| Variable | Default | What |
|
|
140
|
+
|---|---|---|
|
|
141
|
+
| `DRIVE_MCP_CREDENTIALS` | `~/.config/google-drive-comments-mcp/credentials.json` | OAuth client secret JSON |
|
|
142
|
+
| `DRIVE_MCP_TOKEN` | `~/.config/google-drive-comments-mcp/token.json` | Cached refresh token |
|
|
143
|
+
| `DRIVE_MCP_SCOPES` | `https://www.googleapis.com/auth/drive.readonly` | OAuth scopes (comma-separated) |
|
|
144
|
+
| `XDG_CONFIG_HOME` | `~/.config` | Standard XDG override |
|
|
145
|
+
|
|
146
|
+
### Sharing one login with other Google MCP tools
|
|
147
|
+
|
|
148
|
+
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:
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
DRIVE_MCP_SCOPES="https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/drive.readonly" \
|
|
152
|
+
google-drive-comments-mcp setup --reauth
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
A token granted a superset of scopes satisfies each tool's narrower request.
|
|
156
|
+
|
|
157
|
+
## Security
|
|
158
|
+
|
|
159
|
+
- **Read-only**: the default scope is `drive.readonly`. It cannot edit, comment, or delete — only read file metadata, content, and comments.
|
|
160
|
+
- **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`).
|
|
161
|
+
- **No telemetry**: your OAuth client lives in your own Google Cloud project. Nothing leaves your machine.
|
|
162
|
+
|
|
163
|
+
## Troubleshooting
|
|
164
|
+
|
|
165
|
+
**`HttpError 403: Google Drive API has not been used in project … before or it is disabled`**
|
|
166
|
+
Enable the Drive API on the project that owns your OAuth client, then retry.
|
|
167
|
+
|
|
168
|
+
**`No valid Google token` from Claude Desktop / cron**
|
|
169
|
+
Run `google-drive-comments-mcp setup` once in a terminal where a browser can open. Subsequent runs reuse the cached token.
|
|
170
|
+
|
|
171
|
+
**Comments come back empty on a file you know has comments**
|
|
172
|
+
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`.
|
|
173
|
+
|
|
174
|
+
## Authentication — bring your own Google OAuth client
|
|
175
|
+
|
|
176
|
+
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.
|
|
177
|
+
|
|
178
|
+
- **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.
|
|
179
|
+
- **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).
|
|
180
|
+
- **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).
|
|
181
|
+
- **No hosted/SaaS option** — everything runs locally; your Drive data never touches a third-party server.
|
|
182
|
+
|
|
183
|
+
## More guides
|
|
184
|
+
|
|
185
|
+
- [docs/setup-google-oauth.md](docs/setup-google-oauth.md) — full OAuth walkthrough + common errors
|
|
186
|
+
- [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, …)
|
|
187
|
+
- [examples/](examples/) — runnable snippets
|
|
188
|
+
|
|
189
|
+
## Related tools
|
|
190
|
+
|
|
191
|
+
Part of a small family of focused, local MCP servers for Google Workspace data the hosted connectors don't expose:
|
|
192
|
+
|
|
193
|
+
- **[gmail-attachments-mcp](https://github.com/zayansalman/gmail-attachments-mcp)** — download Gmail attachment bytes to disk
|
|
194
|
+
- **google-drive-comments-mcp** — read comment threads on Docs/Sheets/Slides *(this repo)*
|
|
195
|
+
- **[google-drive-files-mcp](https://github.com/zayansalman/google-drive-files-mcp)** — move/organize Drive files
|
|
196
|
+
|
|
197
|
+
They can share one OAuth login or stay isolated — see each repo's setup.
|
|
198
|
+
|
|
199
|
+
## License
|
|
200
|
+
|
|
201
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Claude Code integration
|
|
2
|
+
|
|
3
|
+
After `pip install google-drive-comments-mcp` and `google-drive-comments-mcp setup`:
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
claude mcp add --scope user google-drive-comments google-drive-comments-mcp -- serve
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
`--scope user` makes it available in every project (saved in `~/.claude.json`). Drop it for a project-local registration.
|
|
10
|
+
|
|
11
|
+
Verify:
|
|
12
|
+
```bash
|
|
13
|
+
claude mcp list | grep google-drive-comments
|
|
14
|
+
# google-drive-comments: google-drive-comments-mcp serve - ✓ Connected
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
In a session:
|
|
18
|
+
> Read the open comments on this doc and summarize what reviewers are asking for: https://docs.google.com/document/d/…
|
|
19
|
+
|
|
20
|
+
## Remove
|
|
21
|
+
```bash
|
|
22
|
+
claude mcp remove google-drive-comments
|
|
23
|
+
```
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Claude Desktop integration
|
|
2
|
+
|
|
3
|
+
After installing and running `google-drive-comments-mcp setup`, edit Claude Desktop's MCP config:
|
|
4
|
+
|
|
5
|
+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
6
|
+
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
7
|
+
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"mcpServers": {
|
|
12
|
+
"google-drive-comments": {
|
|
13
|
+
"command": "google-drive-comments-mcp",
|
|
14
|
+
"args": ["serve"]
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
If the command isn't on Claude Desktop's `$PATH`, use the absolute path from `which google-drive-comments-mcp`:
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{
|
|
24
|
+
"mcpServers": {
|
|
25
|
+
"google-drive-comments": {
|
|
26
|
+
"command": "/Users/you/.local/bin/google-drive-comments-mcp",
|
|
27
|
+
"args": ["serve"]
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Fully quit (Cmd-Q) and relaunch.
|
|
34
|
+
|
|
35
|
+
## Newer Claude Desktop / Cowork builds
|
|
36
|
+
Some builds read MCP config from the unified `~/.claude.json` (shared with Claude Code) rather than `claude_desktop_config.json`. If editing the JSON has no effect after a restart, register via the CLI instead and relaunch:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
claude mcp add --scope user google-drive-comments google-drive-comments-mcp -- serve
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Verify
|
|
43
|
+
> List the comments on this doc — use the google-drive-comments tool: https://docs.google.com/document/d/…
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Other MCP clients
|
|
2
|
+
|
|
3
|
+
Any client that supports stdio-transport MCP servers can use `google-drive-comments-mcp`. The pattern is universal:
|
|
4
|
+
|
|
5
|
+
- **Transport**: stdio
|
|
6
|
+
- **Command**: `google-drive-comments-mcp` (or the absolute path)
|
|
7
|
+
- **Args**: `["serve"]`
|
|
8
|
+
- **Env** (optional): `DRIVE_MCP_CREDENTIALS`, `DRIVE_MCP_TOKEN`, `DRIVE_MCP_SCOPES`
|
|
9
|
+
|
|
10
|
+
## Cursor — `~/.cursor/mcp.json`
|
|
11
|
+
```json
|
|
12
|
+
{
|
|
13
|
+
"mcpServers": {
|
|
14
|
+
"google-drive-comments": { "command": "google-drive-comments-mcp", "args": ["serve"] }
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Cline (VS Code)
|
|
20
|
+
MCP settings UI → **Add MCP server** → stdio. Command `google-drive-comments-mcp`, args `serve`. Or edit `~/.cline/mcp.json` with the same shape.
|
|
21
|
+
|
|
22
|
+
## Continue.dev — `~/.continue/config.yaml`
|
|
23
|
+
```yaml
|
|
24
|
+
mcpServers:
|
|
25
|
+
- name: google-drive-comments
|
|
26
|
+
command: google-drive-comments-mcp
|
|
27
|
+
args:
|
|
28
|
+
- serve
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## One-time auth per machine
|
|
32
|
+
Once `google-drive-comments-mcp setup` has cached a token at `~/.config/google-drive-comments-mcp/token.json`, every client on that machine/user reuses it — no per-client re-authentication.
|