Email Processing

Um servidor de processamento de e-mail que utiliza MongoDB para busca semântica e SQLite para armazenamento e recuperação eficientes.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP de Processamento de Email

Um servidor MCP multiplataforma que processa emails do Microsoft Outlook, gera embeddings vetoriais usando Ollama e oferece recursos de busca semântica. Funciona em Windows, macOS e qualquer plataforma via API do Microsoft Graph.

O servidor está em conformidade com a especificação Model Context Protocol (MCP) 2025-06-18 e usa o SDK oficial do MCP.

Recursos

Capacidades Principais

Processa emails do Outlook com filtro por intervalo de datas
Armazena emails em banco de dados SQLite com gerenciamento adequado de conexões
Gera embeddings vetoriais usando Ollama (nomic-embed-text)
Busca semântica no conteúdo dos emails via armazenamento vetorial MongoDB
Suporte a múltiplas caixas de entrada e múltiplas contas
Suporte às pastas Caixa de Entrada, Itens Enviados e, opcionalmente, Itens Excluídos

Suporte Multiplataforma

Windows: Automação COM nativa do Outlook via pywin32
macOS: Integração com AppleScript no Outlook para Mac
Qualquer Plataforma: API do Microsoft Graph para acesso em nuvem (Windows, macOS, Linux, contêineres)

Conformidade com MCP 2025-06-18

Resultados Estruturados de Ferramentas: As ferramentas retornam modelos Pydantic tipados e validados
Transporte HTTP: Suporta transportes STDIO e HTTP (HTTP Streamable)
Negociação de Protocolo: Declara a versão do protocolo durante o handshake
Metadados Aprimorados: Títulos e descrições de ferramentas para melhor integração com a interface

Ferramentas Disponíveis (12+)

Categoria	Ferramentas
Processamento de Email	`process_emails`
Busca e Análise	`search_emails`, `analyze_email_sentiment`, `find_actionable_items`
Exportação de Dados	`export_email_data` (CSV, JSON, HTML, Excel)
Gerenciamento de Pastas	`list_outlook_folders`, `get_folder_statistics`, `organize_emails_by_rules`
Gerenciamento de Contatos	`extract_contacts`
Estatísticas	`get_email_statistics`, `check_data_consistency`

Pré-requisitos

Obrigatórios (Todas as Plataformas)

Python 3.10 ou superior
Ollama rodando localmente com o modelo nomic-embed-text
Servidor MongoDB (para armazenar embeddings)

Requisitos Específicos por Plataforma

Plataforma	Requisito
Windows	Microsoft Outlook instalado + pywin32
macOS	Microsoft Outlook para Mac instalado
Graph API	Registro de aplicativo no Azure AD com permissão Mail.Read

Instalação

1. Instalar o uv (se ainda não estiver instalado)

pip install uv

2. Criar e ativar o ambiente virtual

uv venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

3. Instalar as dependências

Instalação principal (obrigatória):

uv pip install -e .

Extras específicos por plataforma:

# Windows (adds pywin32 for COM automation)
uv pip install -e ".[windows]"

# Graph API support (cross-platform cloud access)
uv pip install -e ".[graph]"

# All optional dependencies
uv pip install -e ".[all]"

4. Instalar o modelo de embedding do Ollama

ollama pull nomic-embed-text

5. (Somente Graph API) Registrar o aplicativo no Azure AD

Se estiver usando a API do Microsoft Graph, você precisa registrar um aplicativo no Azure AD:

Vá para Portal Azure → Azure Active Directory → Registros de aplicativos
Clique em "Novo registro"
Dê um nome ao seu aplicativo e selecione "Contas somente neste diretório organizacional"
Após a criação, anote o ID do aplicativo (cliente) e o ID do diretório (locatário)
Vá para "Certificados e segredos" → "Novo segredo do cliente" → anote o valor do segredo
Vá para "Permissões de API" → "Adicionar uma permissão" → "Microsoft Graph" → "Permissões de aplicativo"
Adicione: Mail.Read, User.Read.All (para descoberta de múltiplas contas)
Clique em "Conceder consentimento do administrador"

Configuração

Adicione o servidor ao seu arquivo de configuração do Claude for Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Variáveis de Ambiente

Variável	Descrição	Obrigatória
`MONGODB_URI`	String de conexão do MongoDB	Sim
`SQLITE_DB_PATH`	Caminho para o arquivo do banco de dados SQLite	Sim
`EMBEDDING_BASE_URL`	URL do servidor Ollama (padrão: http://localhost:11434)	Não
`EMBEDDING_MODEL`	Nome do modelo de embedding (padrão: nomic-embed-text)	Não
`COLLECTION_NAME`	Nome da coleção no MongoDB	Sim
`PROCESS_DELETED_ITEMS`	Processar pasta Itens Excluídos (padrão: "false")	Não
`OUTLOOK_PROVIDER`	Provedor: `auto`, `windows`, `mac`, `graph` (padrão: "auto")	Não
`LOCAL_TIMEZONE`	Fuso horário para datas (padrão: "UTC", ex.: "America/Chicago")	Não

Variáveis do Graph API (obrigatórias quando OUTLOOK_PROVIDER=graph):

Variável	Descrição
`GRAPH_CLIENT_ID`	ID do aplicativo (cliente) do Azure AD
`GRAPH_CLIENT_SECRET`	Segredo do cliente do Azure AD
`GRAPH_TENANT_ID`	ID do locatário do Azure AD
`GRAPH_USER_EMAILS`	Caixas de correio: lista separada por vírgulas ou "All" para descoberta automática

Configuração no Windows (Automação COM)

Usa automação COM nativa do Outlook via pywin32.

{
  "mcpServers": {
    "outlook-email": {
      "command": "C:/path/to/.venv/Scripts/python",
      "args": ["C:/path/to/src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
        "SQLITE_DB_PATH": "C:\\path\\to\\data\\emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "windows",
        "LOCAL_TIMEZONE": "America/Chicago"
      }
    }
  }
}

Configuração no macOS (AppleScript)

Usa AppleScript para se comunicar com o Outlook para Mac.

{
  "mcpServers": {
    "outlook-email": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
        "SQLITE_DB_PATH": "/path/to/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "mac",
        "LOCAL_TIMEZONE": "America/Los_Angeles"
      }
    }
  }
}

Configuração do Graph API (Multiplataforma)

Funciona em qualquer plataforma com credenciais do Azure AD. Suporta caixas de correio únicas ou múltiplas.

Caixa de correio única ou caixas específicas:

{
  "mcpServers": {
    "outlook-email": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP",
        "SQLITE_DB_PATH": "/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "graph",
        "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
        "GRAPH_CLIENT_SECRET": "your-client-secret",
        "GRAPH_TENANT_ID": "your-tenant-id",
        "GRAPH_USER_EMAILS": "user1@example.com,user2@example.com"
      }
    }
  }
}

Todas as caixas de correio no locatário (descoberta automática):

{
  "mcpServers": {
    "outlook-email": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP",
        "SQLITE_DB_PATH": "/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "graph",
        "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
        "GRAPH_CLIENT_SECRET": "your-client-secret",
        "GRAPH_TENANT_ID": "your-tenant-id",
        "GRAPH_USER_EMAILS": "All"
      }
    }
  }
}

Detecção Automática de Provedor

Quando OUTLOOK_PROVIDER está definido como auto (padrão), o servidor seleciona automaticamente o melhor provedor:

Plataforma	Provedor Selecionado Automaticamente
Windows	`windows` (automação COM)
macOS	`mac` (AppleScript)
Linux/Outros	`graph` (requer configuração do Azure AD)

Transporte HTTP (Conformidade com 2025-06-18)

Para transporte HTTP, execute o servidor com o sinalizador --http:

python src/mcp_server.py --http

Isso iniciará o servidor em http://localhost:8000/mcp com conformidade total com o protocolo 2025-06-18, incluindo:

Negociação de versão do protocolo
Esquemas de saída estruturados
Validação de cabeçalhos HTTP
Tratamento adequado de erros

O transporte HTTP suporta modos de operação com e sem estado.

Ferramentas Disponíveis

1. process_emails

Processa emails de um intervalo de datas especificado e retorna resultados estruturados:

Entrada:

{
  "start_date": "2024-01-01",    # ISO format date (YYYY-MM-DD)
  "end_date": "2024-02-15",      # ISO format date (YYYY-MM-DD)
  "mailboxes": ["All"]           # List of mailbox names or ["All"] for all mailboxes
}

Saída (Estruturada):

{
  "success": true,
  "processed_count": 150,
  "retrieved_count": 200,
  "stored_count": 180,
  "failed_count": 20,
  "message": "Successfully processed 150 emails (retrieved: 200, stored: 180, failed: 20)",
  "error": null
}

A ferramenta irá:

Conectar-se às caixas de correio do Outlook especificadas
Recuperar emails das pastas Caixa de Entrada e Itens Enviados (e Itens Excluídos, se habilitado)
Armazenar emails no banco de dados SQLite
Gerar embeddings usando Ollama
Armazenar embeddings no MongoDB para busca semântica
Retornar resultados estruturados com estatísticas detalhadas

Exemplo de Uso no Claude

"Process emails from February 1st to February 17th from all mailboxes"

Arquitetura

Design de Conectores Baseado em Provedores

O servidor usa uma abstração baseada em provedores para acesso multiplataforma a emails:

src/connectors/
├── base.py               # OutlookConnectorBase (abstract interface)
├── factory.py            # create_connector() with auto-detection
├── windows_connector.py  # Windows COM via pywin32
├── mac_connector.py      # macOS AppleScript via osascript
└── graph_connector.py    # Microsoft Graph API (cross-platform)

Todos os conectores implementam a mesma interface, retornando objetos EmailMetadata padronizados, independentemente da plataforma.

Arquitetura de Banco de Dados Duplo

O servidor usa uma abordagem de armazenamento híbrido:

Banco de Dados SQLite:

Armazenamento primário de emails e metadados
Recursos de busca em texto completo
Rastreamento de status de processamento
Filtragem por intervalo de datas e pastas
Consultas estruturadas rápidas

MongoDB:

Armazenamento de embeddings vetoriais (768 dimensões)
Busca por similaridade semântica
Metadados armazenados junto com embeddings
Habilita busca com IA

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para problemas comuns:

Formatos de data inválidos
Problemas de conexão com o Outlook
Erros do MongoDB
Falhas na geração de embeddings com lógica de repetição
Erros de armazenamento no SQLite
Problemas de conexão com o servidor Ollama com repetições automáticas

Gerenciamento de Recursos

O servidor implementa gerenciamento adequado de recursos para evitar problemas:

As conexões de banco de dados (SQLite e MongoDB) são mantidas abertas durante a vida útil do servidor para evitar erros de "Não é possível operar em um banco de dados fechado"
As conexões são fechadas apenas quando o servidor é encerrado, usando um manipulador atexit
Destrutores e gerenciadores de contexto são usados como fallback para garantir que as conexões sejam fechadas quando os objetos são coletados pelo garbage collector
O gerenciamento de conexões é projetado para equilibrar o uso de recursos com a confiabilidade operacional
Lógica robusta de repetição para serviços externos como Ollama para lidar com problemas temporários de conexão

Conformidade com MCP 2025-06-18

Este servidor foi atualizado para estar em conformidade com a especificação MCP 2025-06-18:

Recursos do Protocolo

Versão do Protocolo: Declara protocolVersion: "2025-06-18" durante o handshake
Saída Estruturada: Todas as ferramentas retornam modelos Pydantic tipados e validados
Transporte HTTP: Suporta HTTP Streamable com validação adequada de cabeçalhos
Metadados de Ferramentas: Descrições aprimoradas de ferramentas com títulos e esquemas
Tratamento de Erros: Respostas de erro estruturadas com informações detalhadas

Suporte a Transporte

STDIO: Comunicação tradicional stdin/stdout (padrão)
HTTP: HTTP Streamable em localhost:8000/mcp com validação de cabeçalhos
Cabeçalhos de Protocolo: Valida cabeçalhos MCP-Protocol-Version e Origin
JSON-RPC de Mensagem Única: Sem suporte a solicitações em lote conforme especificação 2025-06-18

Saída Estruturada

A ferramenta process_emails retorna um ProcessEmailsResult estruturado com:

success: Booleano indicando sucesso da operação
processed_count: Número de emails processados com sucesso
retrieved_count: Total de emails recuperados do Outlook
stored_count: Número de emails armazenados no SQLite
failed_count: Número de emails que falharam no processamento
message: Mensagem de status legível por humanos
error: Detalhes do erro se a operação falhou

Notas de Segurança

O servidor processa apenas emails de caixas de correio especificadas
Todos os dados são armazenados localmente (SQLite) e no MongoDB
Nenhuma chamada de API externa, exceto para o servidor Ollama local (e Microsoft Graph se estiver usando esse provedor)
Requer aprovação explícita do usuário para processamento de emails
Nenhum dado confidencial de email é exposto pela interface MCP
O transporte HTTP vincula-se apenas a localhost por segurança
O Graph API usa fluxo de credenciais de cliente OAuth 2.0 com Azure AD
Armazene as credenciais do Azure AD com segurança (variáveis de ambiente, não no código)

Depuração

Se você encontrar problemas:

Verifique se os emails foram processados com sucesso (verifique a resposta do process_emails)
Certifique-se de que o servidor Ollama esteja rodando para geração de embeddings
Verifique se o banco de dados SQLite está acessível
Verifique se a conexão com o MongoDB está funcionando corretamente
Use a ferramenta check_data_consistency para verificar a sincronização SQLite/MongoDB

Depuração Específica por Plataforma

Windows:

Certifique-se de que o Outlook esteja rodando e acessível
Verifique se o pywin32 está instalado: pip show pywin32
Verifique se a automação COM funciona: python -c "import win32com.client; print('OK')"

macOS:

Certifique-se de que o Outlook para Mac esteja instalado (não apenas o aplicativo web "Novo Outlook")
Teste o acesso via AppleScript: osascript -e 'tell application "Microsoft Outlook" to get name'
Conceda permissão ao Terminal/IDE em Preferências do Sistema → Segurança e Privacidade → Automação

Graph API:

Verifique se o aplicativo do Azure AD tem as permissões corretas (Mail.Read, User.Read.All)
Verifique se o consentimento do administrador foi concedido
Teste a aquisição de token: as credenciais são registradas na inicialização
Verifique se GRAPH_USER_EMAILS está definido corretamente ("All" ou emails separados por vírgula)

Limitações por Plataforma

Plataforma	Limitação
Windows	Requer o aplicativo de desktop do Outlook em execução
macOS	O "Novo Outlook" pode ter suporte limitado a AppleScript; use o Graph API como alternativa
Graph API	Requer configuração do Azure AD; intervalo máximo de datas de 30 dias imposto
Todas	Intervalo máximo de processamento de 30 dias por solicitação

Recursos Futuros

Resumo de emails usando LLMs
Categorização automática de emails
Relatórios de email personalizáveis
Rascunho de respostas de email no Outlook
Sugestões de regras do Outlook
Opções expandidas de banco de dados com integração Neo4j e ChromaDB