convez.ai
MCP ServerBusca & PesquisaIntermediário
likelion

MCP Email Index

likelion/mcp-email-index

Indexe emails IMAP localmente para busca semântica e estruturada instantânea

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que indexa localmente sua caixa de entrada IMAP para busca semântica e estruturada rápida. Armazena metadados e embeddings localmente enquanto busca corpos de emails e anexos sob demanda no servidor IMAP. Suporta múltiplas contas Gmail, self-hosted ou qualquer provedor IMAP.

Instalação

$npx convez-ai likelion/mcp-email-index

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Buscar emails por significado (ex: 'aquele email sobre deadline do projeto')
  • Filtrar por critérios estruturados (sender, data, pasta)
  • Integrar busca de email em fluxos de automação Claude
  • Gerenciar múltiplas contas de email centralizadamente

Veredito

Solução prática e bem arquitetada para quem precisa buscar email via IA. A indexação local com Qdrant e SQLite oferece bom desempenho, mas requer Python 3.10+ e configuração manual de credenciais IMAP — adequado para usuários técnicos que querem controle total sobre seus dados.

README

A tradução para o português deste README ainda está na fila.

mcp-email-index

Indexes your IMAP email locally so you can search it fast — both semantically ("that email about the project deadline from last month") and structurally ("all emails from bob@example.com in March 2024"). Full email bodies and attachments are fetched live from IMAP on demand; only metadata and embeddings are stored locally.

Works with any IMAP mailbox (Gmail, self-hosted, etc.). Supports multiple accounts searched together or independently.

Requires Python 3.10+. Uses Qdrant (embedded) for vector search, SQLite with FTS5 for structured search, and sentence-transformers for embeddings.


Quick Start

1. Configure

Edit ~/.mcp-email-index/config.toml (auto-created on first run):

[account.work]
imap_host         = "mail.example-corp.com"
imap_port         = 993
imap_ssl          = true
imap_verify_ssl   = true                                 # set false for self-signed certs
username          = "alice@example-corp.com"
password          = "..."
max_connections   = 10                                   # max concurrent IMAP connections
# default_from    = "Alice <alice@example-corp.com>"     # backfill empty From headers
# exclude_folders = ["[Gmail]/All Mail", "[Gmail]/Spam"] # glob patterns for folders to skip
# smime_pfx       = "~/.mcp-email-index/certs/work.pfx" # S/MIME decryption certificate
# smime_password  = "..."                                # or env MCP_EMAIL_INDEX_WORK_SMIME_PASSWORD

[account.personal]
imap_host         = "imap.example-personal.com"
imap_port         = 993
imap_ssl          = true
imap_verify_ssl   = true
username          = "alice@example-personal.com"
password          = "..."

Add as many [account.<name>] sections as you need. The <name> is what you use in --account flags and MCP tool parameters.

Passwords can also be set via environment variables: MCP_EMAIL_INDEX_<ACCOUNT>_PASSWORD (uppercase account name) takes priority over the config file value. Same pattern for S/MIME: MCP_EMAIL_INDEX_<ACCOUNT>_SMIME_PASSWORD.

2. Add to your MCP client

{
  "mcpServers": {
    "email-index": {
      "command": "uvx",
      "args": ["mcp-email-index"]
    }
  }
}

Multiple clients can use the same config — the first one starts the daemon, the rest connect to it. When the last client disconnects, the daemon auto-shuts down after 60 seconds (MCP_EMAIL_INDEX_GRACE env var to override).

3. Index your email

Add a shell function (e.g. in ~/.zshrc) so email invokes the CLI:

email() { uvx --from mcp-email-index mcp-email-index-cli "$@"; }

Then build the index:

email index

This starts the server (if not already running) and indexes all configured accounts. Run it once after setup, then periodically to pick up new mail.


CLI Commands

All commands use uvx --from mcp-email-index mcp-email-index-cli (the email alias from Quick Start).

The server is started automatically when needed.

stop — Shut down the server

email stop

If an indexing job is running, it is cancelled (progress saved) before shutdown.

index — Build or update the index

# Incremental — only new emails since last run
email index

# Specific accounts
email index --account work
email index --account work --account personal

# Specific folders (suffix-wildcard glob, only trailing * supported)
email index --account work --folder "Archive/2025/*"

# Full reindex — wipes existing data and rebuilds from scratch
email index --full
email index --full --account work --folder "Archive/2025/2025-03"
FlagWhat it does
--account NAME / -aRestrict to this account. Repeat for multiple. Omit for all.
--folder GLOB / -fRestrict to folders matching this glob. Only trailing * wildcard. Requires exactly one --account.
--fullDelete existing index data first, then reindex. Required when the embedding model changes.

The CLI shows the live progress stream after starting the job. Press Ctrl-C to choose: run in background (default) or cancel the job.

During indexing the server automatically:

  • Detects and prunes emails deleted from IMAP (stale UIDs)
  • Removes folders that no longer exist on IMAP or are now in exclude_folders
  • Leaves other already-indexed folders untouched when using --folder to scope a run
  • Validates the embedding model fingerprint — blocks incremental indexing if the model changed (use --full to confirm)

index cancel — Stop the current indexing job

email index cancel

Finishes the current batch, saves progress, and stops. No data is lost.

index remove — Remove indexed data

email index remove -a work -f "Archive/2024/2024-03"  # specific folder
email index remove -a work                            # entire account
email index remove                                    # everything

Prompts for confirmation before deleting.

scan — Discover new and removed folders

email scan

Compares live IMAP folder lists against the index. Removes stale folders from the index and shows an ASCII tree of all folders with their index status, including counts of new (unindexed) messages.

email (no command) — Version and live status

email

Prints the version, starts the server if needed, and streams a live progress display while an indexing job is running. Press Ctrl-C to exit — the job keeps running. If no job is active, exits immediately.

Command interactions

SituationWhat happens
index while a job is runningShows the running job's status. Cancel first to start a new one.
scan while a job is runningRejected — cancel the job first.
stop while a job is runningCancels the job (progress saved), then shuts down.

MCP Tools

These tools are exposed to MCP clients. All search tools query across all configured accounts by default.

search_emails — Semantic search

Natural language search across email subjects and bodies.

ParameterTypeDefaultDescription
querystringrequiredNatural language query
accountslist[string][] (all)Restrict to specific accounts
n_resultsint10Number of results
sincestring | nullnullISO date lower bound
beforestring | nullnullISO date upper bound
folder_globstring | nullnullFolder path glob (trailing * only)
from_addrstring | nullnullSender substring
to_addrstring | nullnullTo/CC recipient substring
has_attachmentbool | nullnullFilter by attachment presence
overfetchint5Candidate multiplier for address filters

find_emails — Structured search

Field-specific lookups with FTS5 keyword search. Supports pagination.

ParameterTypeDefaultDescription
accountslist[string][] (all)Restrict to specific accounts
from_addrstring | nullnullSender substring
to_addrstring | nullnullTo/CC recipient substring
subjectstring | nullnullSubject keyword search (FTS5)
bodystring | nullnullBody preview keyword search (FTS5)
sincestring | nullnullISO date lower bound
beforestring | nullnullISO date upper bound
folder_globstring | nullnullFolder path glob
has_attachmentbool | nullnullFilter by attachment presence
limitint50Page size (capped at max_find_results)
offsetint0Pagination offset

get_email — Fetch full email content

Fetches the complete email body live from IMAP.

ParameterTypeDescription
accountstringAccount name
folderstringIMAP folder path
uidstringIMAP UID

Returns full plain-text body (HTML stripped if no text/plain part), headers, and attachment filenames. If the email has been moved to a different folder on the server, the index is updated automatically. If the email no longer exists on IMAP, it is pruned from the index.

get_metadata_by_message_id — Look up by Message-ID

Instant lookup from the local index — no IMAP connection needed.

ParameterTypeDefaultDescription
message_idstringrequiredRFC 2822 Message-ID
accountslist[string][] (all)Restrict to specific accounts

get_thread — Reconstruct email thread

Returns all indexed emails in the same conversation, sorted by date ascending. Thread reconstruction uses In-Reply-To and References headers.

ParameterTypeDescription
accountstringAccount name
message_idstringMessage-ID of any email in the thread

save_attachments — Download attachments

Fetches the email live from IMAP and saves attachments to a local directory. Handles filename collisions by appending a counter.

ParameterTypeDefaultDescription
accountstringrequiredAccount name
folderstringrequiredIMAP folder path
uidstringrequiredIMAP UID
dest_dirstring"."Local path to save into (auto-created if needed)
nameslist[string][] (all)Specific filenames to save; empty means all

list_folders — See what's indexed

Lists all indexed folders with email counts and last indexing timestamp.

ParameterTypeDefaultDescription
accountstring | nullnullSpecific account, or null for all

Search Tips

  • search_emails for natural language: "that email about the project deadline".
  • find_emails for precise lookups: exact sender, date range, subject keywords.
  • folder_glob narrows scope: "Archive/2024/*" searches only 2024 folders.
  • from_addr and to_addr are substring matches — "bob" matches bob@example.com.
  • get_thread after finding an interesting email to see the full conversation.

S/MIME Support

If your IMAP server stores S/MIME encrypted or signed emails (common with Exchange), configure a PFX/P12 certificate for transparent decryption:

[account.work]
smime_pfx      = "~/.mcp-email-index/certs/work.pfx"
smime_password = "pfx-password"

The PFX can contain multiple key+cert pairs (e.g. current + historical). All pairs are tried during decryption. OpenSSL is used as a fallback for BER-encoded PKCS7 and legacy algorithms (RC2, DES).

Handled formats:

  • Standard S/MIME enveloped-data (encrypted)
  • Opaque-signed messages (signature unwrapped to extract body)
  • Detached signatures (multipart with text + pkcs7 signature)
  • Exchange "Microsoft Mail Internet Headers" wrapper
  • Exchange TNEF-wrapped S/MIME (application/ms-tnef with PKCS7 body)
  • Apple Mail S/MIME (missing Content-Type, only filename=smime.p7m)

Account Options

default_from — Backfill empty From headers

Old Exchange Sent folders sometimes store emails with an empty From header. Set default_from to backfill it during indexing and live fetches:

[account.work]
default_from = "Your Name <you@example.com>"

exclude_folders — Skip folders during indexing

Glob patterns for folders to exclude from indexing and scanning:

[account.work]
exclude_folders = ["[Gmail]/All Mail", "[Gmail]/Spam", "Drafts"]

Configuration Reference

~/.mcp-email-index/config.toml:

SectionKeyDefaultDescription
[account.<name>]imap_host—IMAP server hostname
imap_port993IMAP port
imap_ssltrueUse SSL
imap_verify_ssltrueVerify SSL certs (set false for self-signed)
username—IMAP username
password—IMAP password (or env MCP_EMAIL_INDEX_<NAME>_PASSWORD)
max_connections10Max concurrent IMAP connections
default_from—Backfill empty From headers (e.g. "Name <email>")
exclude_folders—List of glob patterns for folders to skip
smime_pfx—Path to PFX/P12 certificate for S/MIME decryption
smime_password—PFX password (or env MCP_EMAIL_INDEX_<NAME>_SMIME_PASSWORD)
[index]data_dir~/.mcp-email-index/dataWhere index data is stored (Qdrant + SQLite)
embedding_modelnomic-ai/nomic-embed-text-v1.5Sentence-transformers model (changing requires --full reindex)
batch_size50Emails per IMAP fetch batch
max_find_results500Hard cap on find_emails results
preview_chars500Body preview length stored in index
embed_chars8000Body text fed to embedding model (must be ≥ preview_chars)
[server]host127.0.0.1Bind address
port6644HTTP port for MCP (SSE) and CLI
log_levelINFODEBUG | INFO | WARNING | ERROR
semaphore_timeout_s30Timeout (seconds) waiting for IMAP connection slot

Server files:

  • PID file: ~/.mcp-email-index/server.pid
  • Log file: ~/.mcp-email-index/server.log
  • Config: ~/.mcp-email-index/config.toml (auto-created with defaults on first run, chmod 600)
Ver o original no GitHub

Bom para

Relacionados