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 binaire s’appuie maintenant sur mcp-framework pour :

• la gestion de profils CLI
• le stockage JSON de configuration dans os.UserConfigDir()
• le stockage du mot de passe dans Bitwarden via bw
• le manifeste mcp.toml
• les helpers Go générés depuis mcp.toml (mcpgen/)
• l’auto-update via email-mcp update

Commandes

• email-mcp setup : configure (ou met à jour) un profil IMAP
• email-mcp config show : affiche la configuration IMAP résolue et la provenance
• email-mcp config test : lance les checks de configuration/connectivité (équivalent de doctor)
• email-mcp config delete : supprime un profil local et son mot de passe stocké
• email-mcp mcp : lance le serveur MCP sur stdin/stdout
• email-mcp doctor : diagnostique la configuration locale, Bitwarden, le manifeste et l’accès IMAP
• email-mcp update : met à jour le binaire courant depuis la dernière release
• email-mcp version : affiche la version du binaire

La commande email-mcp help (ou -h / --help) affiche l’aide globale.

Outils MCP

• 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

Configuration

La configuration est séparée en deux parties :

• host et username sont stockés dans config.json
• password est stocké dans Bitwarden via le CLI bw

Le profil actif est résolu dans cet ordre :

1. --profile
2. EMAIL_MCP_PROFILE
3. current_profile dans config.json
4. [profiles].default dans mcp.toml
5. default

Les credentials IMAP sont résolus ensuite via les champs [[config.fields]] du manifeste et les helpers générés par le framework :

1. host : EMAIL_MCP_HOST puis config.json
2. username : EMAIL_MCP_USERNAME puis config.json
3. password : EMAIL_MCP_PASSWORD puis secret Bitwarden imap-password/<profile>

Configurer un profil

./email-mcp setup

Pour un profil nommé :

./email-mcp setup --profile work

Le binaire demande ensuite :

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

Si un mot de passe existe déjà dans Bitwarden, laisser le champ vide le conserve.

Le backend de secrets déclaré dans mcp.toml est bitwarden-cli. Le CLI bw doit être installé, connecté et déverrouillé avec BW_SESSION disponible dans l’environnement. EMAIL_MCP_PASSWORD reste accepté pour fournir le mot de passe sans lire Bitwarden.

Lancer le serveur MCP

./email-mcp mcp

Pour un profil nommé :

./email-mcp mcp --profile work

Si aucun credential n’a été configuré pour le profil résolu, le serveur renvoie l’erreur :

credentials not configured; run `email-mcp setup`

Inspecter la configuration résolue

./email-mcp config show
./email-mcp config show --profile work

Tester la configuration résolue

./email-mcp config test
./email-mcp config test --profile work

Auto-update

email-mcp update lit mcp.toml depuis le répertoire du binaire courant, puis remonte les répertoires parents. Si aucun manifeste n’est trouvé, la commande échoue.

./email-mcp update

Le manifeste de ce repo utilise le driver Gitea du framework :

binary_name = "email-mcp"

[update]
source_name = "email-mcp releases"
driver = "gitea"
repository = "AI/email-mcp"
base_url = "https://gitea.lclr.dev"
asset_name_template = "{binary}-{os}-{arch}{ext}"
checksum_asset_name = "{asset}.sha256"
checksum_required = true
token_env_names = ["GITEA_TOKEN"]

Diagnostic

email-mcp doctor vérifie :

• la lisibilité du fichier de configuration
• le profil IMAP résolu
• la disponibilité du backend Bitwarden
• la présence du mot de passe stocké
• la validité du manifeste mcp.toml
• la connectivité IMAP avec les credentials résolus

./email-mcp doctor
./email-mcp doctor --profile work

La commande retourne un code de sortie non nul si au moins un check échoue.

Pour l’update, la validation du manifeste accepte :

• soit update.latest_release_url
• soit un couple driver/référentiel (update.driver, update.repository) avec les champs requis (ex. update.base_url pour Gitea)

Installation

Installateur interactif

Le repo inclut un assistant interactif install.sh :

./install.sh

Tu peux aussi l’exécuter directement depuis la branche main :

curl -fsSL https://gitea.lclr.dev/AI/email-mcp/raw/branch/main/install.sh | bash

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

La configuration se fait une fois séparément via email-mcp setup.

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.

Les assets publiés sont :

• build/email-mcp-linux-amd64
• build/email-mcp-linux-amd64.sha256
• mcp.toml

Compiler depuis les sources

make build

Le binaire est généré dans build/email-mcp-<goos>-<goarch> avec une version injectée depuis git describe.

Pour cross-compiler :

make build GOOS=windows GOARCH=amd64

Pour lancer les tests :

make test

Pour régénérer la glue framework après une modification de mcp.toml :

make generate
make generate-check