mail-mcp
Allows connecting to a Gmail mailbox via IMAP to retrieve incoming emails and expose them as structured, searchable data through the MCP server.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mail-mcp — assistant mail personnel via IA locale + serveur MCP
Projet en 3 parties, conforme au sujet:
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/.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.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. Transportstreamable-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 3Installation
cd mail-mcp
python -m venv .venv
.venv\Scripts\activate # Windows
pip install -r requirements.txt
cp .env.example .envRemplis .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 exempleqwen2.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: imap-mcp
Utilisation
Recuperer les nouveaux mails et les structurer avec l'IA locale:
python -m src.pipelineLe 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_serverLe tester avec l'inspecteur MCP officiel:
npx @modelcontextprotocol/inspectorDeploiement (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.
Construit et pousse l'image Docker vers la plateforme de ton choix (Render, Railway, Fly.io...). Le
Dockerfilefourni ne contient aucune donnee mail personnelle (le dossierdata/est vide dans l'image, etdata/est dans.gitignore) — seul le code est publie.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).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).
Un client MCP (Claude Desktop, etc.) se connecte alors a
https://ton-serveur.exemple.com/mcpavec le headerAuthorization: Bearer <MCP_AUTH_TOKEN>.
Tests
pip install -r requirements-dev.txt
python -m pytest tests/ -vtests/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/
DockerfileTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Your mailbox for MCP clients: search, read, draft, send, rules and notes. Sending is off by default.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables searching, reading full conversations, and sending email across multiple IMAP/SMTP mailboxes from any MCP client, with multi-user support and per-user API tokens.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to check, list, search, read, send, draft, and trash email in a single IMAP mailbox using standard IMAP and SMTP settings, with sending and trash moves enabled only when explicitly allowed.36 npmMIT
- AlicenseAqualityBmaintenanceEnables MCP clients to manage multiple IMAP/SMTP mailboxes by listing folders, searching and reading messages, preparing Markdown drafts and replies, and sending only a draft the user has reviewed and confirmed.944 npmMIT
- AlicenseAqualityBmaintenanceEnables MCP clients to list folders, inspect and search recent emails, retrieve individual messages, and optionally move promotions with explicit confirmation. An optional background monitor classifies new messages via AI and sends important-mail alerts.5MIT