# mcp_gmail_autosend

Serveur [MCP](https://modelcontextprotocol.io) (Model Context Protocol) qui permet à un client MCP (Claude Desktop, Claude Code, etc.) d'envoyer des emails via l'API Gmail, avec pièce jointe PDF optionnelle, suivi des réponses de thread, et journalisation locale dans SQLite.

## Fonctionnalités

Le serveur expose 3 outils MCP :

| Outil | Description |
|---|---|
| `send_email(to, subject, body, pdf_path="")` | Envoie un email via l'API Gmail, avec pièce jointe PDF optionnelle. |
| `check_reply(thread_id)` | Vérifie si un thread Gmail a reçu une réponse. |
| `list_sent_emails(limit=20)` | Liste les derniers emails envoyés, depuis le log SQLite local. |

Chaque envoi est journalisé dans `mail_log.db` (créé automatiquement au premier lancement) : destinataire, sujet, date, statut, `thread_id`, `message_id`.

## Prérequis

- Python 3.10+
- Un compte Google avec accès à [Google Cloud Console](https://console.cloud.google.com/)
- Un client MCP (Claude Desktop, Claude Code...)

## Installation

### 1. Cloner le dépôt

```bash
git clone https://github.com/<votre-utilisateur>/mcp_gmail_autosend.git
cd mcp_gmail_autosend
```

### 2. Installer les dépendances

```bash
python3 -m venv venv
source venv/bin/activate  # Windows : venv\Scripts\activate
pip install -r requirements.txt
```

### 3. Créer les identifiants OAuth Google

1. Rendez-vous sur [Google Cloud Console](https://console.cloud.google.com/).
2. Créez un projet (ou réutilisez-en un existant).
3. Activez l'**API Gmail** : *APIs & Services → Library → Gmail API → Enable*.
4. Configurez l'écran de consentement OAuth (*OAuth consent screen*) en mode **External** (ou **Internal** si vous avez un Workspace), type d'utilisateur test suffisant pour un usage personnel.
5. Créez des identifiants : *APIs & Services → Credentials → Create Credentials → OAuth client ID → Application type: Desktop app*.
6. Téléchargez le fichier JSON généré, renommez-le `credentials.json` et placez-le à la racine du projet.

> ⚠️ `credentials.json` contient un `client_secret`. Il est listé dans `.gitignore` et ne doit **jamais** être commité ni partagé.

### 4. Générer le token d'accès

```bash
python setup_oauth.py
```

Cela ouvre une fenêtre de navigateur pour vous authentifier avec votre compte Google et autoriser les scopes demandés (`gmail.send`, `gmail.readonly`). Un fichier `token.json` est créé à la racine — il contient votre token d'accès et votre refresh token, il ne doit **jamais** être commité non plus (déjà exclu via `.gitignore`).

Le token se rafraîchit automatiquement lors des appels suivants, tant que le refresh token reste valide.

### 5. Configurer votre client MCP

Copiez l'exemple fourni et adaptez le chemin :

```bash
cp claude_desktop_config.example.json claude_desktop_config.json
```

Éditez `claude_desktop_config.json` et remplacez le chemin par le chemin absolu réel vers `server.py` sur votre machine :

```json
{
  "mcpServers": {
    "gmail-mcp": {
      "command": "python",
      "args": ["/chemin/absolu/vers/mcp_gmail_autosend/server.py"],
      "env": {}
    }
  }
}
```

Puis fusionnez ce bloc `mcpServers` dans le fichier de config de votre client :

- **Claude Desktop** : `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows) ou `~/.config/Claude/claude_desktop_config.json` (Linux).
- **Claude Code** : `claude mcp add gmail-mcp -- python /chemin/absolu/vers/server.py`

Redémarrez votre client MCP.

## Utilisation

Une fois le serveur connecté, demandez simplement à Claude :

- « Envoie un email à alice@example.com avec pour sujet "Compte-rendu" et joins le PDF `/home/user/rapport.pdf` »
- « Est-ce que j'ai reçu une réponse sur le thread `<thread_id>` ? »
- « Liste mes 10 derniers emails envoyés »

## Structure du projet

```
mcp_gmail_autosend/
├── server.py                          # Serveur MCP (outils send_email, check_reply, list_sent_emails)
├── setup_oauth.py                     # Script à lancer une fois pour générer token.json
├── requirements.txt                   # Dépendances Python
├── claude_desktop_config.example.json # Exemple de config client MCP (à copier/adapter)
├── credentials.json                   # (non versionné) identifiants OAuth Google
├── token.json                         # (non versionné) token d'accès Gmail
└── mail_log.db                        # (non versionné) log SQLite des emails envoyés
```

## Sécurité

- `credentials.json` et `token.json` donnent accès à l'envoi d'emails **depuis votre compte Gmail**. Ils sont exclus via `.gitignore` — vérifiez toujours `git status` avant un commit pour vous assurer qu'ils n'y apparaissent pas.
- Le scope `gmail.readonly` permet la lecture de threads (utilisé uniquement pour `check_reply`) ; il n'y a pas d'accès en écriture/suppression au-delà de l'envoi.
- `mail_log.db` contient l'historique des destinataires et sujets envoyés : elle aussi est exclue du dépôt.
- Si vous pensez qu'un token a fuité, révoquez l'accès immédiatement depuis [myaccount.google.com/permissions](https://myaccount.google.com/permissions), puis relancez `setup_oauth.py`.

## Licence

Non spécifiée — ajoutez une licence (MIT, Apache-2.0...) si vous comptez rendre ce dépôt public et réutilisable par d'autres.