mcp-gmail-manager 0.1.0__tar.gz

mcp_gmail_manager-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+wheels/
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# OAuth credentials & runtime state — NEVER commit
+credentials.json
+token.json
+audit.jsonl
+config.json

mcp_gmail_manager-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Jhonathas Lima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_gmail_manager-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: mcp-gmail-manager
+Version: 0.1.0
+Summary: Gmail Model Context Protocol server with recipient allowlist and local audit log.
+Project-URL: Homepage, https://github.com/arthjhon/mcp-gmail-manager
+Project-URL: Issues, https://github.com/arthjhon/mcp-gmail-manager/issues
+Project-URL: Repository, https://github.com/arthjhon/mcp-gmail-manager
+Author-email: Arthur Jhonathas Lima <arthur.jhonathas@umj.edu.br>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: allowlist,audit,claude,email,gmail,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.10
+Requires-Dist: google-api-python-client>=2.0
+Requires-Dist: google-auth-oauthlib>=1.0
+Requires-Dist: google-auth>=2.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# mcp-gmail-manager
+
+> 🌐 **[Leia em português (pt-BR) →](README.pt-BR.md)**
+
+[![PyPI version](https://img.shields.io/pypi/v/mcp-gmail-manager.svg)](https://pypi.org/project/mcp-gmail-manager/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mcp-gmail-manager.svg)](https://pypi.org/project/mcp-gmail-manager/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
+[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blueviolet.svg)](https://modelcontextprotocol.io)
+
+A comprehensive Gmail [Model Context Protocol](https://modelcontextprotocol.io) server: **33 tools** covering send, reply, forward, drafts, search, read, attachments, trash, labels, filters, signature, and vacation responder.
+
+Two optional features that distinguish it from other Gmail MCPs:
+
+- **Local audit log** (on by default) — every write/send/modify/download appends a JSON line to `audit.jsonl`. Metadata only (no body content). Compliance trail without third-party services.
+- **Recipient allowlist** (off by default) — when enabled, every outbound operation (`send_email`, `create_draft`, `reply_to_message`, `forward_message`) checks recipients against configured domains and explicit addresses. Useful for institutional / compliance contexts. See [`examples/config.with-allowlist.json`](examples/config.with-allowlist.json) to enable.
+
+## Tools (33)
+
+| Group | Tools |
+|---|---|
+| Send / reply / forward | `send_email`, `reply_to_message`, `forward_message` |
+| Drafts | `create_draft`, `list_drafts`, `send_draft`, `update_draft`, `delete_draft` |
+| Read / profile | `get_profile`, `get_message`, `search_threads`, `get_thread` |
+| Attachments | `get_message_attachments`, `download_attachment` |
+| Trash | `trash_message`, `untrash_message`, `trash_thread`, `untrash_thread` |
+| Labels | `list_labels`, `create_label`, `update_label`, `delete_label`, `label_message`, `unlabel_message`, `label_thread`, `unlabel_thread` |
+| Filters | `list_filters`, `create_filter`, `delete_filter` |
+| Signature | `get_signature`, `update_signature` |
+| Vacation responder | `get_vacation_responder`, `set_vacation_responder` |
+
+OAuth scopes requested: `gmail.modify` + `gmail.settings.basic`. Does **not** request the `https://mail.google.com/` superuser scope — permanent delete is intentionally unsupported.
+
+## Requirements
+
+- Python ≥ 3.10
+- A Google Cloud project with the Gmail API enabled and an OAuth 2.0 client (Desktop type)
+- A way to forward `localhost:8765` to your auth host (typically `ssh -L 8765:localhost:8765 user@host`)
+
+## Install
+
+```bash
+pip install mcp-gmail-manager
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/arthjhon/mcp-gmail-manager.git
+cd mcp-gmail-manager
+pip install .
+```
+
+## Google Cloud setup (one-time, ~10 minutes)
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create a new project (or pick an existing one).
+2. Enable the **Gmail API** (not "Gmail MCP API" — that's Google's own remote MCP; not what we want).
+3. Configure the **OAuth consent screen**:
+   - User type: **Internal** if your account is part of a Google Workspace; otherwise **External** in Testing mode (limited to 100 users, tokens expire every 7 days — fine for individuals).
+   - Scopes: add `https://www.googleapis.com/auth/gmail.modify` and `https://www.googleapis.com/auth/gmail.settings.basic`. **Do not** add anything else.
+   - Test users (External only): add the Gmail address you'll authenticate with.
+4. Create an **OAuth Client ID**:
+   - Application type: **Desktop app**
+   - Download the JSON. Save it as `credentials.json`.
+
+## First-time auth
+
+Move your credentials into the config directory (default `~/.config/mcp-gmail-manager/`):
+
+```bash
+mkdir -p ~/.config/mcp-gmail-manager
+mv ~/Downloads/client_secret_*.json ~/.config/mcp-gmail-manager/credentials.json
+chmod 600 ~/.config/mcp-gmail-manager/credentials.json
+```
+
+Run the auth flow:
+
+```bash
+mcp-gmail-manager-auth
+```
+
+This binds to `localhost:8765` and prints a Google authorisation URL. Open it in a browser **on a machine that can reach `localhost:8765` on the auth host**:
+
+- **Local desktop**: the printed URL works directly.
+- **Remote / headless server**: forward the port from your laptop first:
+  ```bash
+  ssh -L 8765:localhost:8765 user@your-server
+  ```
+  Then run `mcp-gmail-manager-auth` inside that SSH session.
+
+Authorise with the Google account that will own outbound mail. On success the script writes `token.json` and exits.
+
+## Register with Claude Code
+
+```bash
+claude mcp add gmail-manager -- mcp-gmail-manager
+```
+
+Or, if you installed inside a virtualenv that isn't on `$PATH`:
+
+```bash
+claude mcp add gmail-manager -- /path/to/venv/bin/mcp-gmail-manager
+```
+
+Restart your Claude Code session so the new tool schemas load.
+
+## Configuration
+
+`~/.config/mcp-gmail-manager/config.json` is optional — if it doesn't exist, sensible defaults apply (no allowlist, audit log enabled). Two ready-to-copy examples are provided:
+
+- [`examples/config.example.json`](examples/config.example.json) — minimal, no allowlist (default behaviour). Use this if you want the MCP to send to any address.
+- [`examples/config.with-allowlist.json`](examples/config.with-allowlist.json) — institutional setup with allowlist enforced.
+
+Schema reference:
+
+```json
+{
+  "allowlist": {
+    "enabled": false,
+    "domains": [],
+    "emails": []
+  },
+  "audit_log": {
+    "enabled": true,
+    "path": null
+  },
+  "attachments": {
+    "max_total_bytes": 20971520
+  }
+}
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `allowlist.enabled` | `false` | When `false`, any recipient is accepted. Enable explicitly for institutional use. |
+| `allowlist.domains` | `[]` | Lower-case domain suffixes accepted as recipients. |
+| `allowlist.emails` | `[]` | Explicit lower-case email addresses accepted regardless of domain. |
+| `audit_log.enabled` | `true` | Append every write/modify/send to JSONL. |
+| `audit_log.path` | `null` | `null` → `<config_dir>/audit.jsonl`. Override to centralise logs. |
+| `attachments.max_total_bytes` | `20971520` (20 MB) | Combined size cap per send. Gmail's hard limit is 25 MB raw. |
+
+### Environment variable overrides
+
+| Variable | Default |
+|---|---|
+| `GMAIL_MCP_CONFIG_DIR` | `$XDG_CONFIG_HOME/mcp-gmail-manager` or `~/.config/mcp-gmail-manager` |
+| `GMAIL_MCP_CREDENTIALS` | `<config_dir>/credentials.json` |
+| `GMAIL_MCP_TOKEN` | `<config_dir>/token.json` |
+
+## Security notes
+
+- **Token storage**: `token.json` is written `chmod 600`. Treat it as a password — anyone with read access can act as your Gmail account.
+- **No remote attestation**: this server runs entirely on your machine. No telemetry, no third-party calls beyond `googleapis.com`.
+- **Allowlist is defence in depth, not perimeter security**: an attacker who compromises your machine can read `token.json` and call the Gmail API directly, bypassing the MCP entirely. The allowlist defends against the LLM being tricked or hallucinating malicious recipients, not against host compromise.
+- **OAuth scope is broad**: `gmail.modify` covers everything except permanent delete. If you only need to send, fork and replace the scope with `gmail.send`.
+- **Permanent delete intentionally unsupported**: we don't request `https://mail.google.com/`. Deletes go to Trash and can be undone with `untrash_*`.
+
+## Limitations
+
+- OAuth "Production" verification for `gmail.modify` requires a Google security assessment (paid, weeks of process). Stay in "Internal" (Workspace) or "Testing" (≤ 100 users, 7-day token refresh) modes to avoid this.
+- HTML email body composition is not exposed as a first-class field. Send via `create_draft` + manual HTML editing in the Gmail UI, or extend `_build_mime` in a fork.
+- Push notifications (Pub/Sub `watch`/`stop`) not implemented — out of scope.
+
+## Contributing
+
+Issues and PRs welcome. Keep changes scoped, document any new tool with a schema example, and add an audit-log entry for anything that mutates state.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_gmail_manager-0.1.0/README.md

@@ -0,0 +1,169 @@
+# mcp-gmail-manager
+
+> 🌐 **[Leia em português (pt-BR) →](README.pt-BR.md)**
+
+[![PyPI version](https://img.shields.io/pypi/v/mcp-gmail-manager.svg)](https://pypi.org/project/mcp-gmail-manager/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mcp-gmail-manager.svg)](https://pypi.org/project/mcp-gmail-manager/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
+[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blueviolet.svg)](https://modelcontextprotocol.io)
+
+A comprehensive Gmail [Model Context Protocol](https://modelcontextprotocol.io) server: **33 tools** covering send, reply, forward, drafts, search, read, attachments, trash, labels, filters, signature, and vacation responder.
+
+Two optional features that distinguish it from other Gmail MCPs:
+
+- **Local audit log** (on by default) — every write/send/modify/download appends a JSON line to `audit.jsonl`. Metadata only (no body content). Compliance trail without third-party services.
+- **Recipient allowlist** (off by default) — when enabled, every outbound operation (`send_email`, `create_draft`, `reply_to_message`, `forward_message`) checks recipients against configured domains and explicit addresses. Useful for institutional / compliance contexts. See [`examples/config.with-allowlist.json`](examples/config.with-allowlist.json) to enable.
+
+## Tools (33)
+
+| Group | Tools |
+|---|---|
+| Send / reply / forward | `send_email`, `reply_to_message`, `forward_message` |
+| Drafts | `create_draft`, `list_drafts`, `send_draft`, `update_draft`, `delete_draft` |
+| Read / profile | `get_profile`, `get_message`, `search_threads`, `get_thread` |
+| Attachments | `get_message_attachments`, `download_attachment` |
+| Trash | `trash_message`, `untrash_message`, `trash_thread`, `untrash_thread` |
+| Labels | `list_labels`, `create_label`, `update_label`, `delete_label`, `label_message`, `unlabel_message`, `label_thread`, `unlabel_thread` |
+| Filters | `list_filters`, `create_filter`, `delete_filter` |
+| Signature | `get_signature`, `update_signature` |
+| Vacation responder | `get_vacation_responder`, `set_vacation_responder` |
+
+OAuth scopes requested: `gmail.modify` + `gmail.settings.basic`. Does **not** request the `https://mail.google.com/` superuser scope — permanent delete is intentionally unsupported.
+
+## Requirements
+
+- Python ≥ 3.10
+- A Google Cloud project with the Gmail API enabled and an OAuth 2.0 client (Desktop type)
+- A way to forward `localhost:8765` to your auth host (typically `ssh -L 8765:localhost:8765 user@host`)
+
+## Install
+
+```bash
+pip install mcp-gmail-manager
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/arthjhon/mcp-gmail-manager.git
+cd mcp-gmail-manager
+pip install .
+```
+
+## Google Cloud setup (one-time, ~10 minutes)
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create a new project (or pick an existing one).
+2. Enable the **Gmail API** (not "Gmail MCP API" — that's Google's own remote MCP; not what we want).
+3. Configure the **OAuth consent screen**:
+   - User type: **Internal** if your account is part of a Google Workspace; otherwise **External** in Testing mode (limited to 100 users, tokens expire every 7 days — fine for individuals).
+   - Scopes: add `https://www.googleapis.com/auth/gmail.modify` and `https://www.googleapis.com/auth/gmail.settings.basic`. **Do not** add anything else.
+   - Test users (External only): add the Gmail address you'll authenticate with.
+4. Create an **OAuth Client ID**:
+   - Application type: **Desktop app**
+   - Download the JSON. Save it as `credentials.json`.
+
+## First-time auth
+
+Move your credentials into the config directory (default `~/.config/mcp-gmail-manager/`):
+
+```bash
+mkdir -p ~/.config/mcp-gmail-manager
+mv ~/Downloads/client_secret_*.json ~/.config/mcp-gmail-manager/credentials.json
+chmod 600 ~/.config/mcp-gmail-manager/credentials.json
+```
+
+Run the auth flow:
+
+```bash
+mcp-gmail-manager-auth
+```
+
+This binds to `localhost:8765` and prints a Google authorisation URL. Open it in a browser **on a machine that can reach `localhost:8765` on the auth host**:
+
+- **Local desktop**: the printed URL works directly.
+- **Remote / headless server**: forward the port from your laptop first:
+  ```bash
+  ssh -L 8765:localhost:8765 user@your-server
+  ```
+  Then run `mcp-gmail-manager-auth` inside that SSH session.
+
+Authorise with the Google account that will own outbound mail. On success the script writes `token.json` and exits.
+
+## Register with Claude Code
+
+```bash
+claude mcp add gmail-manager -- mcp-gmail-manager
+```
+
+Or, if you installed inside a virtualenv that isn't on `$PATH`:
+
+```bash
+claude mcp add gmail-manager -- /path/to/venv/bin/mcp-gmail-manager
+```
+
+Restart your Claude Code session so the new tool schemas load.
+
+## Configuration
+
+`~/.config/mcp-gmail-manager/config.json` is optional — if it doesn't exist, sensible defaults apply (no allowlist, audit log enabled). Two ready-to-copy examples are provided:
+
+- [`examples/config.example.json`](examples/config.example.json) — minimal, no allowlist (default behaviour). Use this if you want the MCP to send to any address.
+- [`examples/config.with-allowlist.json`](examples/config.with-allowlist.json) — institutional setup with allowlist enforced.
+
+Schema reference:
+
+```json
+{
+  "allowlist": {
+    "enabled": false,
+    "domains": [],
+    "emails": []
+  },
+  "audit_log": {
+    "enabled": true,
+    "path": null
+  },
+  "attachments": {
+    "max_total_bytes": 20971520
+  }
+}
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `allowlist.enabled` | `false` | When `false`, any recipient is accepted. Enable explicitly for institutional use. |
+| `allowlist.domains` | `[]` | Lower-case domain suffixes accepted as recipients. |
+| `allowlist.emails` | `[]` | Explicit lower-case email addresses accepted regardless of domain. |
+| `audit_log.enabled` | `true` | Append every write/modify/send to JSONL. |
+| `audit_log.path` | `null` | `null` → `<config_dir>/audit.jsonl`. Override to centralise logs. |
+| `attachments.max_total_bytes` | `20971520` (20 MB) | Combined size cap per send. Gmail's hard limit is 25 MB raw. |
+
+### Environment variable overrides
+
+| Variable | Default |
+|---|---|
+| `GMAIL_MCP_CONFIG_DIR` | `$XDG_CONFIG_HOME/mcp-gmail-manager` or `~/.config/mcp-gmail-manager` |
+| `GMAIL_MCP_CREDENTIALS` | `<config_dir>/credentials.json` |
+| `GMAIL_MCP_TOKEN` | `<config_dir>/token.json` |
+
+## Security notes
+
+- **Token storage**: `token.json` is written `chmod 600`. Treat it as a password — anyone with read access can act as your Gmail account.
+- **No remote attestation**: this server runs entirely on your machine. No telemetry, no third-party calls beyond `googleapis.com`.
+- **Allowlist is defence in depth, not perimeter security**: an attacker who compromises your machine can read `token.json` and call the Gmail API directly, bypassing the MCP entirely. The allowlist defends against the LLM being tricked or hallucinating malicious recipients, not against host compromise.
+- **OAuth scope is broad**: `gmail.modify` covers everything except permanent delete. If you only need to send, fork and replace the scope with `gmail.send`.
+- **Permanent delete intentionally unsupported**: we don't request `https://mail.google.com/`. Deletes go to Trash and can be undone with `untrash_*`.
+
+## Limitations
+
+- OAuth "Production" verification for `gmail.modify` requires a Google security assessment (paid, weeks of process). Stay in "Internal" (Workspace) or "Testing" (≤ 100 users, 7-day token refresh) modes to avoid this.
+- HTML email body composition is not exposed as a first-class field. Send via `create_draft` + manual HTML editing in the Gmail UI, or extend `_build_mime` in a fork.
+- Push notifications (Pub/Sub `watch`/`stop`) not implemented — out of scope.
+
+## Contributing
+
+Issues and PRs welcome. Keep changes scoped, document any new tool with a schema example, and add an audit-log entry for anything that mutates state.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_gmail_manager-0.1.0/README.pt-BR.md

@@ -0,0 +1,169 @@
+# mcp-gmail-manager
+
+> 🌐 **[Read in English →](README.md)**
+
+[![PyPI version](https://img.shields.io/pypi/v/mcp-gmail-manager.svg)](https://pypi.org/project/mcp-gmail-manager/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mcp-gmail-manager.svg)](https://pypi.org/project/mcp-gmail-manager/)
+[![Licença: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
+[![Compatível com MCP](https://img.shields.io/badge/MCP-compatible-blueviolet.svg)](https://modelcontextprotocol.io)
+
+Servidor [Model Context Protocol](https://modelcontextprotocol.io) abrangente para o Gmail: **33 ferramentas** cobrindo envio, resposta, encaminhamento, rascunhos, busca, leitura, anexos, lixeira, labels, filtros, assinatura e resposta automática de férias.
+
+Duas funcionalidades opcionais que diferenciam este MCP de outros para Gmail:
+
+- **Log de auditoria local** (ligado por padrão) — toda operação de escrita/envio/modificação/download grava uma linha JSON em `audit.jsonl`. Apenas metadados (sem conteúdo do corpo). Trilha de compliance sem dependência de terceiros.
+- **Allowlist de destinatários** (desligada por padrão) — quando habilitada, toda operação de envio (`send_email`, `create_draft`, `reply_to_message`, `forward_message`) confere os destinatários contra domínios e endereços explícitos configurados. Útil em contextos institucionais ou de compliance. Veja [`examples/config.with-allowlist.json`](examples/config.with-allowlist.json) para habilitar.
+
+## Ferramentas (33)
+
+| Grupo | Ferramentas |
+|---|---|
+| Envio / resposta / encaminhamento | `send_email`, `reply_to_message`, `forward_message` |
+| Rascunhos | `create_draft`, `list_drafts`, `send_draft`, `update_draft`, `delete_draft` |
+| Leitura / perfil | `get_profile`, `get_message`, `search_threads`, `get_thread` |
+| Anexos | `get_message_attachments`, `download_attachment` |
+| Lixeira | `trash_message`, `untrash_message`, `trash_thread`, `untrash_thread` |
+| Labels | `list_labels`, `create_label`, `update_label`, `delete_label`, `label_message`, `unlabel_message`, `label_thread`, `unlabel_thread` |
+| Filtros | `list_filters`, `create_filter`, `delete_filter` |
+| Assinatura | `get_signature`, `update_signature` |
+| Resposta automática | `get_vacation_responder`, `set_vacation_responder` |
+
+Escopos OAuth solicitados: `gmail.modify` + `gmail.settings.basic`. **Não** solicita o escopo superuser `https://mail.google.com/` — delete permanente não é suportado intencionalmente.
+
+## Requisitos
+
+- Python ≥ 3.10
+- Projeto no Google Cloud com a Gmail API habilitada e um OAuth Client 2.0 (tipo Desktop)
+- Forma de fazer forward de `localhost:8765` até o host onde o auth roda (geralmente `ssh -L 8765:localhost:8765 user@host`)
+
+## Instalação
+
+```bash
+pip install mcp-gmail-manager
+```
+
+Ou direto do código-fonte:
+
+```bash
+git clone https://github.com/arthjhon/mcp-gmail-manager.git
+cd mcp-gmail-manager
+pip install .
+```
+
+## Setup no Google Cloud (uma vez, ~10 minutos)
+
+1. Vá para o [Google Cloud Console](https://console.cloud.google.com/) e crie um novo projeto (ou use um existente).
+2. Habilite a **Gmail API** (não confunda com a "Gmail MCP API" — essa é o MCP gerenciado do próprio Google; não é o que queremos).
+3. Configure a **OAuth consent screen**:
+   - User type: **Internal** se a sua conta for parte de um Google Workspace; senão **External** em modo Testing (limite de 100 usuários, tokens expiram a cada 7 dias — funciona pra uso individual).
+   - Escopos: adicione `https://www.googleapis.com/auth/gmail.modify` e `https://www.googleapis.com/auth/gmail.settings.basic`. **Nada mais.**
+   - Test users (apenas External): adicione o endereço Gmail com o qual você vai autenticar.
+4. Crie um **OAuth Client ID**:
+   - Application type: **Desktop app**
+   - Baixe o JSON. Salve como `credentials.json`.
+
+## Primeira autenticação
+
+Mova as credentials para o diretório de config (padrão: `~/.config/mcp-gmail-manager/`):
+
+```bash
+mkdir -p ~/.config/mcp-gmail-manager
+mv ~/Downloads/client_secret_*.json ~/.config/mcp-gmail-manager/credentials.json
+chmod 600 ~/.config/mcp-gmail-manager/credentials.json
+```
+
+Rode o fluxo OAuth:
+
+```bash
+mcp-gmail-manager-auth
+```
+
+Isso abre um listener em `localhost:8765` e imprime uma URL de autorização do Google. Abra a URL num browser **em uma máquina que consiga chegar em `localhost:8765` no host de auth**:
+
+- **Desktop local**: a URL impressa funciona direto.
+- **Servidor remoto / headless**: faça forward da porta a partir do seu laptop primeiro:
+  ```bash
+  ssh -L 8765:localhost:8765 user@seu-servidor
+  ```
+  Aí roda o `mcp-gmail-manager-auth` dentro daquela sessão SSH.
+
+Autorize com a conta Google que vai assinar os emails enviados. Em caso de sucesso, o script grava `token.json` e encerra.
+
+## Registrar no Claude Code
+
+```bash
+claude mcp add gmail-manager -- mcp-gmail-manager
+```
+
+Ou, se você instalou num virtualenv que não está no `$PATH`:
+
+```bash
+claude mcp add gmail-manager -- /caminho/para/venv/bin/mcp-gmail-manager
+```
+
+Reinicie a sessão do Claude Code pra que as schemas das ferramentas novas sejam carregadas.
+
+## Configuração
+
+`~/.config/mcp-gmail-manager/config.json` é opcional — se não existir, valores padrão razoáveis são aplicados (sem allowlist, audit log ligado). Dois exemplos prontos pra copiar estão incluídos:
+
+- [`examples/config.example.json`](examples/config.example.json) — mínimo, sem allowlist (comportamento padrão). Use este se quer que o MCP envie pra qualquer endereço.
+- [`examples/config.with-allowlist.json`](examples/config.with-allowlist.json) — setup institucional com allowlist ativa.
+
+Referência de schema:
+
+```json
+{
+  "allowlist": {
+    "enabled": false,
+    "domains": [],
+    "emails": []
+  },
+  "audit_log": {
+    "enabled": true,
+    "path": null
+  },
+  "attachments": {
+    "max_total_bytes": 20971520
+  }
+}
+```
+
+| Campo | Padrão | Significado |
+|---|---|---|
+| `allowlist.enabled` | `false` | Quando `false`, qualquer destinatário é aceito. Habilite explicitamente pra uso institucional. |
+| `allowlist.domains` | `[]` | Sufixos de domínio (lower-case) aceitos como destinatário. |
+| `allowlist.emails` | `[]` | Endereços explícitos (lower-case) aceitos independente do domínio. |
+| `audit_log.enabled` | `true` | Anexa toda escrita/modificação/envio no JSONL. |
+| `audit_log.path` | `null` | `null` → `<config_dir>/audit.jsonl`. Sobrescreva pra centralizar logs. |
+| `attachments.max_total_bytes` | `20971520` (20 MB) | Limite combinado de tamanho por envio. Limite duro do Gmail é 25 MB raw. |
+
+### Sobrescritas via variável de ambiente
+
+| Variável | Padrão |
+|---|---|
+| `GMAIL_MCP_CONFIG_DIR` | `$XDG_CONFIG_HOME/mcp-gmail-manager` ou `~/.config/mcp-gmail-manager` |
+| `GMAIL_MCP_CREDENTIALS` | `<config_dir>/credentials.json` |
+| `GMAIL_MCP_TOKEN` | `<config_dir>/token.json` |
+
+## Notas de segurança
+
+- **Armazenamento do token**: `token.json` é gravado com `chmod 600`. Trate como senha — qualquer um com permissão de leitura consegue agir como sua conta Gmail.
+- **Sem telemetria remota**: o servidor roda inteiramente na sua máquina. Sem telemetria, sem chamadas a terceiros além de `googleapis.com`.
+- **Allowlist é defesa em profundidade, não perímetro de segurança**: um atacante que comprometa sua máquina pode ler `token.json` e chamar a Gmail API direto, contornando o MCP. A allowlist defende contra o LLM ser enganado ou alucinar destinatários maliciosos, não contra comprometimento do host.
+- **Escopo OAuth é amplo**: `gmail.modify` cobre tudo exceto delete permanente. Se você só precisa enviar, faça um fork e troque o escopo por `gmail.send`.
+- **Delete permanente é intencionalmente não suportado**: não solicitamos `https://mail.google.com/`. Deletes vão pra Lixeira e podem ser desfeitos com `untrash_*`.
+
+## Limitações
+
+- A verificação "Production" do OAuth pra `gmail.modify` requer um security assessment do Google (pago, semanas de processo). Fique em "Internal" (Workspace) ou "Testing" (≤ 100 usuários, refresh de 7 dias) pra evitar isso.
+- Composição de email com corpo HTML não está exposta como campo de primeira classe. Use `create_draft` + edição manual de HTML no UI do Gmail, ou estenda `_build_mime` num fork.
+- Notificações push (Pub/Sub `watch`/`stop`) não foram implementadas — fora do escopo.
+
+## Contribuindo
+
+Issues e PRs bem-vindos. Mantenha mudanças escopadas, documente qualquer ferramenta nova com exemplo de schema, e adicione uma entrada no audit log pra qualquer coisa que altere estado.
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).

mcp_gmail_manager-0.1.0/examples/config.example.json

@@ -0,0 +1,14 @@
+{
+  "allowlist": {
+    "enabled": false,
+    "domains": [],
+    "emails": []
+  },
+  "audit_log": {
+    "enabled": true,
+    "path": null
+  },
+  "attachments": {
+    "max_total_bytes": 20971520
+  }
+}

mcp_gmail_manager-0.1.0/examples/config.with-allowlist.json

@@ -0,0 +1,14 @@
+{
+  "allowlist": {
+    "enabled": true,
+    "domains": ["your-org.com"],
+    "emails": ["specific.outsider@gmail.com"]
+  },
+  "audit_log": {
+    "enabled": true,
+    "path": null
+  },
+  "attachments": {
+    "max_total_bytes": 20971520
+  }
+}

mcp_gmail_manager-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-gmail-manager"
+version = "0.1.0"
+description = "Gmail Model Context Protocol server with recipient allowlist and local audit log."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Arthur Jhonathas Lima", email = "arthur.jhonathas@umj.edu.br" }]
+keywords = ["mcp", "gmail", "claude", "model-context-protocol", "email", "allowlist", "audit"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Email",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "google-auth>=2.0",
+    "google-auth-oauthlib>=1.0",
+    "google-api-python-client>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/arthjhon/mcp-gmail-manager"
+Issues = "https://github.com/arthjhon/mcp-gmail-manager/issues"
+Repository = "https://github.com/arthjhon/mcp-gmail-manager"
+
+[project.scripts]
+mcp-gmail-manager = "mcp_gmail_manager.server:run"
+mcp-gmail-manager-auth = "mcp_gmail_manager.auth:run"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_gmail_manager"]

mcp_gmail_manager-0.1.0/src/mcp_gmail_manager/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-gmail-manager — Gmail MCP server with recipient allowlist and audit log."""
+
+__version__ = "0.1.0"