gmail-attachments-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.
- gmail_attachments_mcp-0.1.0/.github/workflows/ci.yml +35 -0
- gmail_attachments_mcp-0.1.0/.github/workflows/release.yml +45 -0
- gmail_attachments_mcp-0.1.0/.gitignore +41 -0
- gmail_attachments_mcp-0.1.0/LICENSE +21 -0
- gmail_attachments_mcp-0.1.0/PKG-INFO +241 -0
- gmail_attachments_mcp-0.1.0/README.md +210 -0
- gmail_attachments_mcp-0.1.0/docs/claude-code.md +35 -0
- gmail_attachments_mcp-0.1.0/docs/claude-desktop.md +60 -0
- gmail_attachments_mcp-0.1.0/docs/other-clients.md +46 -0
- gmail_attachments_mcp-0.1.0/docs/setup-google-oauth.md +82 -0
- gmail_attachments_mcp-0.1.0/examples/cron-careers-inbox.sh +23 -0
- gmail_attachments_mcp-0.1.0/pyproject.toml +60 -0
- gmail_attachments_mcp-0.1.0/server.json +57 -0
- gmail_attachments_mcp-0.1.0/src/gmail_attachments_mcp/__init__.py +2 -0
- gmail_attachments_mcp-0.1.0/src/gmail_attachments_mcp/__main__.py +5 -0
- gmail_attachments_mcp-0.1.0/src/gmail_attachments_mcp/auth.py +84 -0
- gmail_attachments_mcp-0.1.0/src/gmail_attachments_mcp/cli.py +177 -0
- gmail_attachments_mcp-0.1.0/src/gmail_attachments_mcp/client.py +139 -0
- gmail_attachments_mcp-0.1.0/src/gmail_attachments_mcp/config.py +58 -0
- gmail_attachments_mcp-0.1.0/src/gmail_attachments_mcp/server.py +95 -0
- gmail_attachments_mcp-0.1.0/tests/__init__.py +0 -0
- gmail_attachments_mcp-0.1.0/tests/test_client.py +67 -0
- gmail_attachments_mcp-0.1.0/tests/test_config.py +60 -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/gmail-attachments-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,41 @@
|
|
|
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
|
+
.gmail-*-credentials.json
|
|
39
|
+
.gmail-*-token.json
|
|
40
|
+
*.pem
|
|
41
|
+
*.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,241 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: gmail-attachments-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A minimal MCP server and CLI for downloading Gmail attachments to disk.
|
|
5
|
+
Project-URL: Homepage, https://github.com/zayansalman/gmail-attachments-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/zayansalman/gmail-attachments-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/zayansalman/gmail-attachments-mcp/issues
|
|
8
|
+
Author: Zayan Khan
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: anthropic,attachments,claude,gmail,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 :: Communications :: Email
|
|
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
|
+
# gmail-attachments-mcp
|
|
33
|
+
|
|
34
|
+
<!-- mcp-name: io.github.zayansalman/gmail-attachments-mcp -->
|
|
35
|
+
|
|
36
|
+
A focused [Model Context Protocol](https://modelcontextprotocol.io) server (and standalone CLI) for downloading Gmail attachments to disk. Three tools, read-only OAuth scope, no extra surface area.
|
|
37
|
+
|
|
38
|
+
Built because the hosted `claude.ai Gmail` connector in Claude Desktop returns attachment **IDs and metadata only** — not the actual bytes. This server fills that gap for any MCP client (Claude Code, Claude Desktop, Cursor, Cline, etc.), and also works as a plain CLI for cron jobs and shell scripts.
|
|
39
|
+
|
|
40
|
+
If you used [`@GongRzhe/Gmail-MCP-Server`](https://github.com/GongRzhe/Gmail-MCP-Server) (1.1k★, archived 2026-03-03) for its attachment-download workflow, this is a minimal successor focused on that single capability.
|
|
41
|
+
|
|
42
|
+
## Features
|
|
43
|
+
|
|
44
|
+
- **3 MCP tools** — `gmail_search`, `gmail_download_thread_attachments`, `gmail_download_latest_matching`. That's the whole API.
|
|
45
|
+
- **Read-only OAuth scope** (`gmail.readonly`) — can't send, delete, or modify mail.
|
|
46
|
+
- **Works as both an MCP server and a standalone CLI** — same code, same auth token, both surfaces.
|
|
47
|
+
- **Env-var-driven config** — `GMAIL_MCP_CREDENTIALS`, `GMAIL_MCP_TOKEN`, `GMAIL_MCP_DEFAULT_DEST_DIR`.
|
|
48
|
+
- **Cron-friendly** — once authorized, the cached refresh token lets headless jobs run indefinitely.
|
|
49
|
+
|
|
50
|
+
## Install
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
pip install gmail-attachments-mcp
|
|
54
|
+
# or, with uv:
|
|
55
|
+
uv tool install gmail-attachments-mcp
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## One-time setup (~10 minutes)
|
|
59
|
+
|
|
60
|
+
You need a Google Cloud OAuth client. The server runs entirely on your machine; nothing leaves it.
|
|
61
|
+
|
|
62
|
+
1. Sign in to [Google Cloud Console](https://console.cloud.google.com/) with the Gmail account whose attachments you want to download.
|
|
63
|
+
2. Create a project (or pick an existing one).
|
|
64
|
+
3. Enable the Gmail API: [console.cloud.google.com/apis/library/gmail.googleapis.com](https://console.cloud.google.com/apis/library/gmail.googleapis.com).
|
|
65
|
+
4. Configure the OAuth consent screen under **APIs & Services → OAuth consent screen**:
|
|
66
|
+
- **Google Workspace** users: User type = **Internal** (no app verification needed).
|
|
67
|
+
- **Personal Gmail** users: User type = **External**. Add your own Gmail address as a test user under "Test users".
|
|
68
|
+
5. **APIs & Services → Credentials → + Create credentials → OAuth client ID**
|
|
69
|
+
- Application type: **Desktop app**
|
|
70
|
+
- Download the JSON.
|
|
71
|
+
6. Run setup:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
gmail-attachments-mcp setup --import-credentials ~/Downloads/client_secret_*.json
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
A browser window opens for OAuth consent. After consent, a refresh token is cached at `~/.config/gmail-attachments-mcp/token.json` (or `$XDG_CONFIG_HOME/gmail-attachments-mcp/`).
|
|
78
|
+
|
|
79
|
+
Verify:
|
|
80
|
+
```bash
|
|
81
|
+
gmail-attachments-mcp status
|
|
82
|
+
gmail-attachments-mcp search "has:attachment newer_than:7d" --max 3
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
See [docs/setup-google-oauth.md](docs/setup-google-oauth.md) for screenshots and troubleshooting.
|
|
86
|
+
|
|
87
|
+
## Use it from Claude Code
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
claude mcp add --scope user gmail-attachments gmail-attachments-mcp -- serve
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Then in any Claude Code session:
|
|
94
|
+
|
|
95
|
+
> Use the gmail-attachments MCP to download the latest CV from `careers@example.com` to `~/CVs`.
|
|
96
|
+
|
|
97
|
+
## Use it from Claude Desktop
|
|
98
|
+
|
|
99
|
+
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"mcpServers": {
|
|
104
|
+
"gmail-attachments": {
|
|
105
|
+
"command": "gmail-attachments-mcp",
|
|
106
|
+
"args": ["serve"]
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Restart Claude Desktop. See [docs/claude-desktop.md](docs/claude-desktop.md) for details.
|
|
113
|
+
|
|
114
|
+
## Use it from Cursor / Cline / Continue / others
|
|
115
|
+
|
|
116
|
+
Any MCP client that supports stdio servers. Point it at the same `gmail-attachments-mcp serve` command. See [docs/other-clients.md](docs/other-clients.md).
|
|
117
|
+
|
|
118
|
+
## Use it from the shell or cron
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
# Search
|
|
122
|
+
gmail-attachments-mcp search "from:noreply@stripe.com has:attachment newer_than:30d"
|
|
123
|
+
|
|
124
|
+
# Download every attachment from a specific thread
|
|
125
|
+
gmail-attachments-mcp thread 19db831fab15b507 --dest ~/Invoices
|
|
126
|
+
|
|
127
|
+
# Download from the latest match, only PDFs
|
|
128
|
+
gmail-attachments-mcp latest "from:hr@example.com has:attachment" --dest ~/CVs --ext .pdf,.docx
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Cron example — pull CV attachments hourly:
|
|
132
|
+
```cron
|
|
133
|
+
0 * * * * /usr/local/bin/gmail-attachments-mcp latest "to:careers@example.com has:attachment newer_than:2d" --dest ~/CVs --ext .pdf,.docx >> ~/.cache/gmail-attachments-mcp.log 2>&1
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## The 3 MCP tools
|
|
137
|
+
|
|
138
|
+
### `gmail_search(query, max_results=10)`
|
|
139
|
+
Returns thread summaries with attachment filenames. Use Gmail's standard query syntax.
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
[
|
|
143
|
+
{
|
|
144
|
+
"thread_id": "19db831fab15b507",
|
|
145
|
+
"subject": "Folon Q3 2026 Quarterly Product Recap",
|
|
146
|
+
"sender": "Manon Muhtasin Rahman <manon@example.com>",
|
|
147
|
+
"date": "Thu, 23 Apr 2026 08:35:00 +0600",
|
|
148
|
+
"snippet": "Hi everyone, Attached is...",
|
|
149
|
+
"message_count": 1,
|
|
150
|
+
"attachment_count": 1,
|
|
151
|
+
"attachment_filenames": ["Folon Quarterly Report Q3 2026.pdf"]
|
|
152
|
+
}
|
|
153
|
+
]
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### `gmail_download_thread_attachments(thread_id, dest_dir?, extensions?)`
|
|
157
|
+
Downloads every attachment in a thread to disk. Returns `path`, `size_bytes`, `mime_type`, `original_filename` per file.
|
|
158
|
+
|
|
159
|
+
### `gmail_download_latest_matching(query, dest_dir?, extensions?)`
|
|
160
|
+
Convenience: search + download from the single most recent match, in one call.
|
|
161
|
+
|
|
162
|
+
## Configuration
|
|
163
|
+
|
|
164
|
+
All paths can be overridden via environment variables.
|
|
165
|
+
|
|
166
|
+
| Variable | Default | What |
|
|
167
|
+
|---|---|---|
|
|
168
|
+
| `GMAIL_MCP_CREDENTIALS` | `~/.config/gmail-attachments-mcp/credentials.json` | OAuth client secret JSON |
|
|
169
|
+
| `GMAIL_MCP_TOKEN` | `~/.config/gmail-attachments-mcp/token.json` | Cached refresh token |
|
|
170
|
+
| `GMAIL_MCP_DEFAULT_DEST_DIR` | `~/Downloads` | Default download destination |
|
|
171
|
+
| `GMAIL_MCP_SCOPES` | `https://www.googleapis.com/auth/gmail.readonly` | OAuth scopes (comma-separated) |
|
|
172
|
+
| `XDG_CONFIG_HOME` | `~/.config` | Standard XDG override |
|
|
173
|
+
|
|
174
|
+
## Security
|
|
175
|
+
|
|
176
|
+
- **Token storage**: refresh token is written to `~/.config/gmail-attachments-mcp/token.json` with mode `0600`. Anyone with shell access to your account can read your Gmail. Treat the file like a password.
|
|
177
|
+
- **OAuth scope**: default is `gmail.readonly`. Cannot send, delete, or modify mail. If you change `$GMAIL_MCP_SCOPES`, you're on the hook for the consequences.
|
|
178
|
+
- **Credential file**: your OAuth client secret JSON is *not* a password — it identifies your app to Google. But never commit it. The included `.gitignore` blocks the common filenames.
|
|
179
|
+
- **OAuth client**: your client lives in *your* Google Cloud project. There's no central server, no telemetry, nothing leaves your machine.
|
|
180
|
+
|
|
181
|
+
## Troubleshooting
|
|
182
|
+
|
|
183
|
+
**`No valid Gmail token` when invoked from Claude Desktop / cron**
|
|
184
|
+
The first OAuth flow requires a browser. Run `gmail-attachments-mcp setup` once in a terminal where a browser can open. Subsequent runs use the cached refresh token.
|
|
185
|
+
|
|
186
|
+
**`Token has been expired or revoked`**
|
|
187
|
+
Refresh tokens stay valid as long as you use them at least every 6 months and don't revoke them at [myaccount.google.com/permissions](https://myaccount.google.com/permissions). Re-auth:
|
|
188
|
+
```bash
|
|
189
|
+
gmail-attachments-mcp setup --reauth
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
**`Access blocked: This app's request is invalid`**
|
|
193
|
+
On personal Gmail, your OAuth consent screen needs your address listed under **Test users**. Workspace users should select **Internal** audience to avoid this.
|
|
194
|
+
|
|
195
|
+
**`HttpError 403: Request had insufficient authentication scopes`**
|
|
196
|
+
You changed `$GMAIL_MCP_SCOPES` without re-authorizing. Run `gmail-attachments-mcp setup --reauth`.
|
|
197
|
+
|
|
198
|
+
## Comparison with other Gmail MCP servers
|
|
199
|
+
|
|
200
|
+
| Server | Scope | Tools | Maintenance |
|
|
201
|
+
|---|---|---|---|
|
|
202
|
+
| Anthropic hosted `claude.ai Gmail` | Read/write, hosted | many | Active, but **no attachment bytes** |
|
|
203
|
+
| [GongRzhe/Gmail-MCP-Server](https://github.com/GongRzhe/Gmail-MCP-Server) | Full mailbox | 19 | **Archived 2026-03-03** |
|
|
204
|
+
| [shinzo-labs/gmail-mcp](https://github.com/shinzo-labs/gmail-mcp) | Full mailbox | ~30 | Active |
|
|
205
|
+
| **gmail-attachments-mcp** (this) | **read-only** | **3** | Active |
|
|
206
|
+
|
|
207
|
+
Pick this one if you want a tiny, focused, read-only tool. Pick a fuller one if you also need to send mail, manage labels, drafts, threads, etc.
|
|
208
|
+
|
|
209
|
+
## Authentication — bring your own Google OAuth client
|
|
210
|
+
|
|
211
|
+
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.
|
|
212
|
+
|
|
213
|
+
- **Why your own client?** Google's restricted scopes (here, `gmail.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.
|
|
214
|
+
- **What you need:** a free Google Cloud project, the Gmail API enabled, an OAuth consent screen, and a Desktop OAuth client. Full walkthrough → [docs/setup-google-oauth.md](docs/setup-google-oauth.md).
|
|
215
|
+
- **Where your token lives:** `~/.config/gmail-attachments-mcp/token.json` (mode `0600`). Delete it to revoke locally; revoke fully at [myaccount.google.com/permissions](https://myaccount.google.com/permissions).
|
|
216
|
+
- **No hosted/SaaS option** — everything runs locally; your mail never touches a third-party server.
|
|
217
|
+
|
|
218
|
+
## Related tools
|
|
219
|
+
|
|
220
|
+
Part of a small family of focused, local MCP servers for Google Workspace data the hosted connectors don't expose:
|
|
221
|
+
|
|
222
|
+
- **gmail-attachments-mcp** — download Gmail attachment bytes to disk *(this repo)*
|
|
223
|
+
- **[google-drive-comments-mcp](https://github.com/zayansalman/google-drive-comments-mcp)** — read comment threads on Docs/Sheets/Slides
|
|
224
|
+
- **[google-drive-files-mcp](https://github.com/zayansalman/google-drive-files-mcp)** — move/organize Drive files
|
|
225
|
+
|
|
226
|
+
They can share one OAuth login or stay isolated — see each repo's setup.
|
|
227
|
+
|
|
228
|
+
## License
|
|
229
|
+
|
|
230
|
+
MIT. See [LICENSE](LICENSE).
|
|
231
|
+
|
|
232
|
+
## Contributing
|
|
233
|
+
|
|
234
|
+
Issues and PRs welcome. Run `pytest` and `ruff check src tests` before submitting.
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
git clone https://github.com/zayansalman/gmail-attachments-mcp
|
|
238
|
+
cd gmail-attachments-mcp
|
|
239
|
+
pip install -e ".[dev]"
|
|
240
|
+
pytest
|
|
241
|
+
```
|
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
# gmail-attachments-mcp
|
|
2
|
+
|
|
3
|
+
<!-- mcp-name: io.github.zayansalman/gmail-attachments-mcp -->
|
|
4
|
+
|
|
5
|
+
A focused [Model Context Protocol](https://modelcontextprotocol.io) server (and standalone CLI) for downloading Gmail attachments to disk. Three tools, read-only OAuth scope, no extra surface area.
|
|
6
|
+
|
|
7
|
+
Built because the hosted `claude.ai Gmail` connector in Claude Desktop returns attachment **IDs and metadata only** — not the actual bytes. This server fills that gap for any MCP client (Claude Code, Claude Desktop, Cursor, Cline, etc.), and also works as a plain CLI for cron jobs and shell scripts.
|
|
8
|
+
|
|
9
|
+
If you used [`@GongRzhe/Gmail-MCP-Server`](https://github.com/GongRzhe/Gmail-MCP-Server) (1.1k★, archived 2026-03-03) for its attachment-download workflow, this is a minimal successor focused on that single capability.
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
13
|
+
- **3 MCP tools** — `gmail_search`, `gmail_download_thread_attachments`, `gmail_download_latest_matching`. That's the whole API.
|
|
14
|
+
- **Read-only OAuth scope** (`gmail.readonly`) — can't send, delete, or modify mail.
|
|
15
|
+
- **Works as both an MCP server and a standalone CLI** — same code, same auth token, both surfaces.
|
|
16
|
+
- **Env-var-driven config** — `GMAIL_MCP_CREDENTIALS`, `GMAIL_MCP_TOKEN`, `GMAIL_MCP_DEFAULT_DEST_DIR`.
|
|
17
|
+
- **Cron-friendly** — once authorized, the cached refresh token lets headless jobs run indefinitely.
|
|
18
|
+
|
|
19
|
+
## Install
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pip install gmail-attachments-mcp
|
|
23
|
+
# or, with uv:
|
|
24
|
+
uv tool install gmail-attachments-mcp
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## One-time setup (~10 minutes)
|
|
28
|
+
|
|
29
|
+
You need a Google Cloud OAuth client. The server runs entirely on your machine; nothing leaves it.
|
|
30
|
+
|
|
31
|
+
1. Sign in to [Google Cloud Console](https://console.cloud.google.com/) with the Gmail account whose attachments you want to download.
|
|
32
|
+
2. Create a project (or pick an existing one).
|
|
33
|
+
3. Enable the Gmail API: [console.cloud.google.com/apis/library/gmail.googleapis.com](https://console.cloud.google.com/apis/library/gmail.googleapis.com).
|
|
34
|
+
4. Configure the OAuth consent screen under **APIs & Services → OAuth consent screen**:
|
|
35
|
+
- **Google Workspace** users: User type = **Internal** (no app verification needed).
|
|
36
|
+
- **Personal Gmail** users: User type = **External**. Add your own Gmail address as a test user under "Test users".
|
|
37
|
+
5. **APIs & Services → Credentials → + Create credentials → OAuth client ID**
|
|
38
|
+
- Application type: **Desktop app**
|
|
39
|
+
- Download the JSON.
|
|
40
|
+
6. Run setup:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
gmail-attachments-mcp setup --import-credentials ~/Downloads/client_secret_*.json
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
A browser window opens for OAuth consent. After consent, a refresh token is cached at `~/.config/gmail-attachments-mcp/token.json` (or `$XDG_CONFIG_HOME/gmail-attachments-mcp/`).
|
|
47
|
+
|
|
48
|
+
Verify:
|
|
49
|
+
```bash
|
|
50
|
+
gmail-attachments-mcp status
|
|
51
|
+
gmail-attachments-mcp search "has:attachment newer_than:7d" --max 3
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
See [docs/setup-google-oauth.md](docs/setup-google-oauth.md) for screenshots and troubleshooting.
|
|
55
|
+
|
|
56
|
+
## Use it from Claude Code
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
claude mcp add --scope user gmail-attachments gmail-attachments-mcp -- serve
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Then in any Claude Code session:
|
|
63
|
+
|
|
64
|
+
> Use the gmail-attachments MCP to download the latest CV from `careers@example.com` to `~/CVs`.
|
|
65
|
+
|
|
66
|
+
## Use it from Claude Desktop
|
|
67
|
+
|
|
68
|
+
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
|
|
69
|
+
|
|
70
|
+
```json
|
|
71
|
+
{
|
|
72
|
+
"mcpServers": {
|
|
73
|
+
"gmail-attachments": {
|
|
74
|
+
"command": "gmail-attachments-mcp",
|
|
75
|
+
"args": ["serve"]
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Restart Claude Desktop. See [docs/claude-desktop.md](docs/claude-desktop.md) for details.
|
|
82
|
+
|
|
83
|
+
## Use it from Cursor / Cline / Continue / others
|
|
84
|
+
|
|
85
|
+
Any MCP client that supports stdio servers. Point it at the same `gmail-attachments-mcp serve` command. See [docs/other-clients.md](docs/other-clients.md).
|
|
86
|
+
|
|
87
|
+
## Use it from the shell or cron
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
# Search
|
|
91
|
+
gmail-attachments-mcp search "from:noreply@stripe.com has:attachment newer_than:30d"
|
|
92
|
+
|
|
93
|
+
# Download every attachment from a specific thread
|
|
94
|
+
gmail-attachments-mcp thread 19db831fab15b507 --dest ~/Invoices
|
|
95
|
+
|
|
96
|
+
# Download from the latest match, only PDFs
|
|
97
|
+
gmail-attachments-mcp latest "from:hr@example.com has:attachment" --dest ~/CVs --ext .pdf,.docx
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Cron example — pull CV attachments hourly:
|
|
101
|
+
```cron
|
|
102
|
+
0 * * * * /usr/local/bin/gmail-attachments-mcp latest "to:careers@example.com has:attachment newer_than:2d" --dest ~/CVs --ext .pdf,.docx >> ~/.cache/gmail-attachments-mcp.log 2>&1
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## The 3 MCP tools
|
|
106
|
+
|
|
107
|
+
### `gmail_search(query, max_results=10)`
|
|
108
|
+
Returns thread summaries with attachment filenames. Use Gmail's standard query syntax.
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
[
|
|
112
|
+
{
|
|
113
|
+
"thread_id": "19db831fab15b507",
|
|
114
|
+
"subject": "Folon Q3 2026 Quarterly Product Recap",
|
|
115
|
+
"sender": "Manon Muhtasin Rahman <manon@example.com>",
|
|
116
|
+
"date": "Thu, 23 Apr 2026 08:35:00 +0600",
|
|
117
|
+
"snippet": "Hi everyone, Attached is...",
|
|
118
|
+
"message_count": 1,
|
|
119
|
+
"attachment_count": 1,
|
|
120
|
+
"attachment_filenames": ["Folon Quarterly Report Q3 2026.pdf"]
|
|
121
|
+
}
|
|
122
|
+
]
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### `gmail_download_thread_attachments(thread_id, dest_dir?, extensions?)`
|
|
126
|
+
Downloads every attachment in a thread to disk. Returns `path`, `size_bytes`, `mime_type`, `original_filename` per file.
|
|
127
|
+
|
|
128
|
+
### `gmail_download_latest_matching(query, dest_dir?, extensions?)`
|
|
129
|
+
Convenience: search + download from the single most recent match, in one call.
|
|
130
|
+
|
|
131
|
+
## Configuration
|
|
132
|
+
|
|
133
|
+
All paths can be overridden via environment variables.
|
|
134
|
+
|
|
135
|
+
| Variable | Default | What |
|
|
136
|
+
|---|---|---|
|
|
137
|
+
| `GMAIL_MCP_CREDENTIALS` | `~/.config/gmail-attachments-mcp/credentials.json` | OAuth client secret JSON |
|
|
138
|
+
| `GMAIL_MCP_TOKEN` | `~/.config/gmail-attachments-mcp/token.json` | Cached refresh token |
|
|
139
|
+
| `GMAIL_MCP_DEFAULT_DEST_DIR` | `~/Downloads` | Default download destination |
|
|
140
|
+
| `GMAIL_MCP_SCOPES` | `https://www.googleapis.com/auth/gmail.readonly` | OAuth scopes (comma-separated) |
|
|
141
|
+
| `XDG_CONFIG_HOME` | `~/.config` | Standard XDG override |
|
|
142
|
+
|
|
143
|
+
## Security
|
|
144
|
+
|
|
145
|
+
- **Token storage**: refresh token is written to `~/.config/gmail-attachments-mcp/token.json` with mode `0600`. Anyone with shell access to your account can read your Gmail. Treat the file like a password.
|
|
146
|
+
- **OAuth scope**: default is `gmail.readonly`. Cannot send, delete, or modify mail. If you change `$GMAIL_MCP_SCOPES`, you're on the hook for the consequences.
|
|
147
|
+
- **Credential file**: your OAuth client secret JSON is *not* a password — it identifies your app to Google. But never commit it. The included `.gitignore` blocks the common filenames.
|
|
148
|
+
- **OAuth client**: your client lives in *your* Google Cloud project. There's no central server, no telemetry, nothing leaves your machine.
|
|
149
|
+
|
|
150
|
+
## Troubleshooting
|
|
151
|
+
|
|
152
|
+
**`No valid Gmail token` when invoked from Claude Desktop / cron**
|
|
153
|
+
The first OAuth flow requires a browser. Run `gmail-attachments-mcp setup` once in a terminal where a browser can open. Subsequent runs use the cached refresh token.
|
|
154
|
+
|
|
155
|
+
**`Token has been expired or revoked`**
|
|
156
|
+
Refresh tokens stay valid as long as you use them at least every 6 months and don't revoke them at [myaccount.google.com/permissions](https://myaccount.google.com/permissions). Re-auth:
|
|
157
|
+
```bash
|
|
158
|
+
gmail-attachments-mcp setup --reauth
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
**`Access blocked: This app's request is invalid`**
|
|
162
|
+
On personal Gmail, your OAuth consent screen needs your address listed under **Test users**. Workspace users should select **Internal** audience to avoid this.
|
|
163
|
+
|
|
164
|
+
**`HttpError 403: Request had insufficient authentication scopes`**
|
|
165
|
+
You changed `$GMAIL_MCP_SCOPES` without re-authorizing. Run `gmail-attachments-mcp setup --reauth`.
|
|
166
|
+
|
|
167
|
+
## Comparison with other Gmail MCP servers
|
|
168
|
+
|
|
169
|
+
| Server | Scope | Tools | Maintenance |
|
|
170
|
+
|---|---|---|---|
|
|
171
|
+
| Anthropic hosted `claude.ai Gmail` | Read/write, hosted | many | Active, but **no attachment bytes** |
|
|
172
|
+
| [GongRzhe/Gmail-MCP-Server](https://github.com/GongRzhe/Gmail-MCP-Server) | Full mailbox | 19 | **Archived 2026-03-03** |
|
|
173
|
+
| [shinzo-labs/gmail-mcp](https://github.com/shinzo-labs/gmail-mcp) | Full mailbox | ~30 | Active |
|
|
174
|
+
| **gmail-attachments-mcp** (this) | **read-only** | **3** | Active |
|
|
175
|
+
|
|
176
|
+
Pick this one if you want a tiny, focused, read-only tool. Pick a fuller one if you also need to send mail, manage labels, drafts, threads, etc.
|
|
177
|
+
|
|
178
|
+
## Authentication — bring your own Google OAuth client
|
|
179
|
+
|
|
180
|
+
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.
|
|
181
|
+
|
|
182
|
+
- **Why your own client?** Google's restricted scopes (here, `gmail.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.
|
|
183
|
+
- **What you need:** a free Google Cloud project, the Gmail API enabled, an OAuth consent screen, and a Desktop OAuth client. Full walkthrough → [docs/setup-google-oauth.md](docs/setup-google-oauth.md).
|
|
184
|
+
- **Where your token lives:** `~/.config/gmail-attachments-mcp/token.json` (mode `0600`). Delete it to revoke locally; revoke fully at [myaccount.google.com/permissions](https://myaccount.google.com/permissions).
|
|
185
|
+
- **No hosted/SaaS option** — everything runs locally; your mail never touches a third-party server.
|
|
186
|
+
|
|
187
|
+
## Related tools
|
|
188
|
+
|
|
189
|
+
Part of a small family of focused, local MCP servers for Google Workspace data the hosted connectors don't expose:
|
|
190
|
+
|
|
191
|
+
- **gmail-attachments-mcp** — download Gmail attachment bytes to disk *(this repo)*
|
|
192
|
+
- **[google-drive-comments-mcp](https://github.com/zayansalman/google-drive-comments-mcp)** — read comment threads on Docs/Sheets/Slides
|
|
193
|
+
- **[google-drive-files-mcp](https://github.com/zayansalman/google-drive-files-mcp)** — move/organize Drive files
|
|
194
|
+
|
|
195
|
+
They can share one OAuth login or stay isolated — see each repo's setup.
|
|
196
|
+
|
|
197
|
+
## License
|
|
198
|
+
|
|
199
|
+
MIT. See [LICENSE](LICENSE).
|
|
200
|
+
|
|
201
|
+
## Contributing
|
|
202
|
+
|
|
203
|
+
Issues and PRs welcome. Run `pytest` and `ruff check src tests` before submitting.
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
git clone https://github.com/zayansalman/gmail-attachments-mcp
|
|
207
|
+
cd gmail-attachments-mcp
|
|
208
|
+
pip install -e ".[dev]"
|
|
209
|
+
pytest
|
|
210
|
+
```
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Claude Code integration
|
|
2
|
+
|
|
3
|
+
After installing the package and running `gmail-attachments-mcp setup`:
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
claude mcp add --scope user gmail-attachments gmail-attachments-mcp -- serve
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
`--scope user` makes it available across every Claude Code project (saved in `~/.claude.json`). Drop `--scope user` for a project-local registration only.
|
|
10
|
+
|
|
11
|
+
Verify:
|
|
12
|
+
```bash
|
|
13
|
+
claude mcp list | grep gmail
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
You should see `gmail-attachments: gmail-attachments-mcp serve - ✓ Connected`.
|
|
17
|
+
|
|
18
|
+
In a Claude Code session:
|
|
19
|
+
|
|
20
|
+
> Search Gmail for emails from `careers@example.com` with attachments newer than 7 days and download the latest PDF resume to `~/CVs`.
|
|
21
|
+
|
|
22
|
+
## Removing
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
claude mcp remove gmail-attachments
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Per-project scope only
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
cd path/to/project
|
|
32
|
+
claude mcp add gmail-attachments gmail-attachments-mcp -- serve
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
This adds a `.claude.json` entry at the project level. Useful when you want this tool available only inside one specific project.
|