mcp_gmail_autosend

Serveur MCP (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
• Un client MCP (Claude Desktop, Claude Code...)

Installation

1. Cloner le dépôt

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

2. Installer les dépendances

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.
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

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 :

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 :

{
  "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, 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.