email-mcp/README.md

email-mcp

Serveur MCP local pour lire une boîte mail via IMAP. Le serveur parle le protocole MCP standard sur stdio, avec des messages JSON-RPC 2.0 (initialize, notifications/initialized, tools/list, tools/call). Le projet expose trois outils :

• list_mailboxes — lister les boîtes IMAP visibles
• list_messages — lister les messages récents d'une boîte
• get_message — récupérer un message par UID IMAP

Le stockage des credentials repose sur KDE Wallet via D-Bus. La V1 cible Linux avec session KDE Wallet disponible.

Sommaire

• Prérequis
• Configuration
  • Étape 1 : enregistrer les credentials
  • Étape 2 : lancer le serveur MCP
• Installation
  • Claude Code CLI
  • Configuration JSON manuelle
• Compiler depuis les sources
• Outils
  • list_mailboxes
  • list_messages
  • get_message

Prérequis

• Linux
• une session D-Bus utilisateur active
• KDE Wallet accessible sur cette session
• Go 1.25+
• un compte IMAP fonctionnel

Configuration

Étape 1 : enregistrer les credentials

Le setup est interactif :

./email-mcp setup

Le binaire demande ensuite :

1. l'hôte IMAP
2. le nom d'utilisateur
3. le mot de passe

Les credentials sont stockés dans KDE Wallet sous le profil default.

Si KDE Wallet n'est pas disponible, le setup échoue explicitement et n'écrit rien ailleurs.

Étape 2 : lancer le serveur MCP

Le serveur MCP s'exécute sur stdin/stdout avec le handshake MCP standard :

./email-mcp mcp

Si aucun credential n'a été configuré, le serveur renvoie l'erreur :

credentials not configured; run `email-mcp setup`

Installation

Claude Code CLI

Ajoute le serveur MCP en pointant vers le binaire et la sous-commande mcp :

claude mcp add email-mcp -- /absolute/path/to/bin/email-mcp mcp

Le setup doit être exécuté une fois séparément avant d'utiliser le serveur.

Configuration JSON manuelle

Ajoute le bloc suivant à ta configuration MCP (~/.claude.json côté utilisateur, ou .mcp.json dans un projet) :

{
  "mcpServers": {
    "email-mcp": {
      "command": "/absolute/path/to/bin/email-mcp",
      "args": ["mcp"]
    }
  }
}

Releases

Une release est générée automatiquement quand tu pousses un tag v* sur le repo Gitea.

Exemple pour démarrer en v1.0 :

git tag v1.0
git push origin v1.0

Le workflow build alors email-mcp pour linux/amd64 et joint le binaire build/email-mcp-linux-amd64 comme asset de la release.

Compiler depuis les sources

make build

Le binaire est généré dans build/email-mcp-<goos>-<goarch>.

Pour cross-compiler :

make build GOOS=windows GOARCH=amd64

Pour lancer les tests :

make test

Outils

list_mailboxes

Liste les boîtes IMAP visibles pour le compte configuré. Aucun paramètre.

list_messages

Liste les messages récents d'une boîte.

Paramètre	Type	Description
mailbox	string	Requis. Nom de la boîte IMAP
limit	number	Nombre maximum de messages à retourner. Par défaut : 20

Retourne des résumés de messages avec un uid IMAP stable, le sujet et l'expéditeur.

get_message

Récupère un message précis à partir de sa boîte et de son UID IMAP.

Paramètre	Type	Description
mailbox	string	Requis. Nom de la boîte IMAP
uid	number	Requis. UID IMAP du message

Retourne :

• les métadonnées du message
• les headers dans l'ordre d'origine
• un body texte décodé de manière conservative pour les contenus MIME courants