mail-mcp — assistant mail personnel via IA locale + serveur MCP

Projet en 3 parties, conforme au sujet:

1. Collecte de donnees externes, sans IA (src/email_client.py) Connexion IMAP a une vraie boite mail (Gmail, Outlook, ou tout fournisseur IMAP), recuperation des derniers mails, sauvegarde en JSON brut dans data/raw/.

2. Structuration des donnees via IA (src/ai_structurer.py) Chaque mail brut est envoye a un modele qui tourne en local dans Ollama (via le client openai-python, pointe sur l'API compatible OpenAI d'Ollama), avec une sortie JSON strictement contrainte par un schema (src/schema.py) pour extraire un maximum d'informations: categorie, resume, sentiment, priorite, actions a faire (avec echeance), personnes/organisations/lieux cites, dates mentionnees, montants (avec devise et contexte), liens, tags, langue, caractere automatique/newsletter, etc. Le contenu des mails ne quitte jamais la machine: seul Ollama y a acces.

3. Serveur MCP (src/mcp_server.py) Expose les mails structures a n'importe quel client MCP (Claude Desktop, un autre agent...) via 5 outils: list_emails, get_email, search_emails, get_action_items, get_stats. Transport streamable-http, deployable avec une URL publique, protege par un token Bearer.

Boite mail (IMAP)  -->  data/raw/*.json  -->  IA locale (Ollama)  -->  data/structured/emails.jsonl  -->  Serveur MCP (public)
   partie 1 (sans IA)                            partie 2                                                    partie 3

Installation

cd mail-mcp
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -r requirements.txt
cp .env.example .env

Remplis .env:

• IMAP_*: identifiants de ta boite mail. Pour Gmail, active la validation en 2 etapes puis cree un "mot de passe d'application" (myaccount.google.com/apppasswords) — n'utilise jamais ton mot de passe principal.

• OLLAMA_MODEL: un modele deja present en local (ollama list), par exemple qwen2.5:7b-instruct.

• MCP_AUTH_TOKEN: un token que tu inventes, pour proteger le serveur MCP une fois deploye (les donnees servies sont personnelles).

Verifie qu'Ollama tourne (ollama serve, generalement deja lance en arriere-plan sous Windows) et que le modele choisi est bien telecharge (ollama pull qwen2.5:7b-instruct).

Related MCP server: simple-email-mcp

Utilisation

Recuperer les nouveaux mails et les structurer avec l'IA locale:

python -m src.pipeline

Le script est idempotent: relance-le plus tard, il ne retelecharge et ne re-structure que ce qui est nouveau (base sur le Message-ID IMAP). Pas besoin de cron: un import initial suffit, et tu peux relancer la commande a la main quand tu veux mettre a jour les donnees.

Lancer le serveur MCP en local (http://localhost:8000/mcp):

python -m src.mcp_server

Le tester avec l'inspecteur MCP officiel:

npx @modelcontextprotocol/inspector

Deploiement (URL publique pour le MCP)

Le serveur MCP (partie 3) doit etre accessible en ligne. La collecte (partie 1) et la structuration IA (partie 2) restent locales par design (l'IA tourne sur ta machine) — seules les donnees deja structurees sont servies publiquement.

1. Construit et pousse l'image Docker vers la plateforme de ton choix (Render, Railway, Fly.io...). Le Dockerfile fourni ne contient aucune donnee mail personnelle (le dossier data/ est vide dans l'image, et data/ est dans .gitignore) — seul le code est publie.

2. Configure les variables d'environnement sur la plateforme: MCP_AUTH_TOKEN (obligatoire pour un deploiement public), OLLAMA_* (non utilises par le serveur MCP lui-meme, seulement par le pipeline local).

3. Une fois deploye, pousse tes donnees structurees locales vers l'instance deployee:

python scripts/upload_data.py https://ton-serveur.exemple.com

A refaire apres chaque python -m src.pipeline local pour garder le serveur distant a jour (l'upload remplace data/structured/emails.jsonl cote serveur).

4. Un client MCP (Claude Desktop, etc.) se connecte alors a https://ton-serveur.exemple.com/mcp avec le header Authorization: Bearer <MCP_AUTH_TOKEN>.

Tests

pip install -r requirements-dev.txt
python -m pytest tests/ -v

tests/test_ai_structurer.py fait un vrai appel a Ollama en local (saute automatiquement si aucun serveur Ollama n'est joignable, par ex. en CI).

Limitations connues

• Stockage JSONL: les donnees structurees sont dans un fichier JSONL unique, relu integralement a chaque appel MCP. Suffisant pour quelques milliers de mails; au-dela, envisager une base (SQLite, PostgreSQL).

• Filesystem ephemere (PaaS): sur Render/Railway le disque est reinitialise a chaque deploy — les donnees doivent etre repoussees via scripts/upload_data.py.

• Traitement sequentiel Ollama: les mails sont envoyes un par un a l'IA locale. Un traitement parallele (asyncio) accelererait les gros imports.

• Double representation du schema: le JSON Schema (pour Ollama) et le modele Pydantic (pour la validation Python) sont definis separement dans schema.py. Ils doivent rester synchronises manuellement.

Structure du projet

mail-mcp/
  src/
    config.py          configuration (.env)
    schema.py           schema JSON + modeles Pydantic de la donnee structuree
    email_client.py      partie 1: IMAP -> JSON brut
    ai_structurer.py     partie 2: IA locale -> JSON structure
    pipeline.py           CLI qui enchaine les deux
    mcp_server.py         partie 3: serveur MCP (streamable-http)
  scripts/
    upload_data.py         pousse les donnees locales vers le serveur deploye
  data/
    raw/                    mails bruts (JSON, non commite)
    structured/             mails structures (JSONL, non commite)
  tests/
  Dockerfile