mail-macos-mcp

Mail macOS — MCP pour Claude Desktop

Un serveur MCP qui permet à Claude de piloter l'app Mail de macOS : lire, rechercher, préparer des brouillons, envoyer et gérer ses mails — directement depuis Claude Desktop, y compris dans des routines et des agents.

Fonctionne uniquement sur macOS (utilise l'app Mail intégrée).

---

📥 Installation (pour l'utilisateur)

Aucune compétence technique requise, pas de terminal, pas de Node à installer.

1. Télécharger le fichier mail-macos.mcpb :

👉 Télécharger la dernière version

1. Installer dans Claude Desktop :

• D'abord, mettre Claude Desktop à jour (dernière version requise).
• Aller dans Réglages → Extensions
• Cliquer « Advanced settings » / Paramètres avancés
• Dans la section « Extension Developer », cliquer « Install Extension… »
• Sélectionner le fichier mail-macos.mcpb téléchargé
• Un avertissement « développeur non vérifié » peut s'afficher : c'est normal

(l'extension n'est pas signée par un éditeur commercial). Cliquer Installer quand même.

Le glisser-déposer fonctionne surtout pour les extensions du répertoire officiel d'Anthropic ; pour ce bundle privé, utiliser le bouton « Install Extension… » via les paramètres avancés.

1. Autoriser l'accès à Mail :

Au premier usage, macOS demande : « Claude souhaite contrôler Mail ». Cliquer Autoriser. (Sinon : Réglages Système → Confidentialité et sécurité → Automatisation → activer Mail pour Claude.)

C'est prêt. 🎉

---

💬 Exemples d'utilisation

Une fois installé, on parle simplement à Claude :

• « Liste mes 5 derniers mails non lus »
• « Cherche les mails de Clément des 7 derniers jours »
• « Ouvre le mail [id] et résume-le »
• « Prépare un brouillon de réponse à ce mail » *(le brouillon reste dans Mail,

rien n'est envoyé sans validation)*

• « Marque ce mail comme lu »
• « Mets ce mail à la corbeille »

---

🧰 Outils fournis

| Outil | Description | Sécurité | |---|---|---| | tester_acces | Vérifie que Claude peut contrôler Mail (diagnostic, ne touche pas aux mails) | lecture seule | | lister_mails | Liste les derniers mails (filtre non lus / expéditeur) | lecture seule | | rechercher_mails | Recherche dans les mails récents (sujet, expéditeur, corps en option) | lecture seule | | lire_mail | Renvoie le contenu complet d'un mail | lecture seule | | lister_comptes | Liste les comptes mail connectés (nom et adresse(s)) | lecture seule | | creer_brouillon | Crée un brouillon sans l'envoyer (CC, CCI, expéditeur) | non destructif | | envoyer_mail | Envoie un mail (CC, CCI, expéditeur ; Claude Desktop demande confirmation) | sortant | | repondre_mail | Répond à un mail en reprenant le fil ; brouillon par défaut | non destructif | | transferer_mail | Transfère un mail vers un ou plusieurs destinataires ; brouillon par défaut | non destructif | | marquer_mail | Marque un mail lu / non lu | réversible | | deplacer_mail | Déplace un mail vers un dossier | réversible | | corbeille_mail | Met un mail à la Corbeille (récupérable) | récupérable |

Aucune suppression définitive : le pire cas possible est un mail envoyé ou un mail en corbeille (récupérable depuis Mail).

Multi-comptes

lister_comptes renvoie tous les comptes configurés dans l'app Mail, avec leur nom et leurs adresses email. Tous les outils de rédaction (creer_brouillon, envoyer_mail, repondre_mail, transferer_mail) acceptent un paramètre optionnel expediteur : si tu passes une adresse qui correspond à un compte connecté, Mail utilisera ce compte pour envoyer. Si le paramètre est absent, Mail utilise le compte par défaut (ou le compte du mail d'origine pour les réponses). Utilise d'abord lister_comptes pour connaître les adresses disponibles, puis précise expediteur si tu veux choisir le compte d'envoi.

---

🆘 En cas de blocage (Mail qui rame ou se fige)

Sur un gros compte pro synchronisé serveur (IMAP/Exchange), Mail peut être lent à répondre aux requêtes. Le MCP est conçu pour rester sûr dans ce cas :

• Demande « Teste l'accès à Mail » (outil tester_acces) : c'est l'appel le plus

léger. S'il répond, l'autorisation et l'accès sont bons ; le souci vient du volume.

• Le MCP a un délai max (20 s par défaut) : si Mail ne répond pas à temps, tu reçois

un message clair au lieu d'un blocage. Réessaie quelques secondes plus tard (Mail finit souvent de se synchroniser).

• Les lectures sont bornées aux mails récents : lister_mails et rechercher_mails

ne parcourent qu'une fenêtre récente de la boîte de réception, jamais toute la boîte.

• Si Mail était figé : le quitter et le rouvrir, le laisser finir sa synchro, puis réessayer.
• Pour allonger le délai (réseau lent) : variable d'environnement MAIL_MCP_TIMEOUT_MS

(en millisecondes).

🔧 Développement (pour reconstruire le bundle)

Prérequis : Node.js ≥ 18.

npm install        # installe les dépendances
npm run build      # compile TypeScript -> dist/
npm start          # lance le serveur (transport stdio) pour tester

Reconstruire le bundle .mcpb :

npm run build
npm prune --omit=dev                              # ne garder que les deps runtime
npx @anthropic-ai/mcpb pack . mail-macos.mcpb     # produit le .mcpb
npm install                                       # restaurer les deps de dev

Architecture

src/
  index.ts        # serveur MCP : déclare les 11 outils (validation via zod)
  mail.ts         # logique métier : construit les scripts AppleScript
  applescript.ts  # exécution osascript + parsing + messages d'erreur FR

Le pilotage de Mail passe par AppleScript (via osascript), l'API d'automatisation standard de macOS. Aucune adresse ni compte n'est codé en dur : le MCP agit sur la boîte de réception unifiée de l'app Mail de la machine.

---

Licence

MIT