Outlook Assistant

Outlook Assistant

Servidor MCP para e-mail, calendário e contatos do Outlook — deixe seu assistente de IA gerenciar sua caixa de entrada diretamente da conversa.

O Outlook Assistant conecta assistentes de IA à sua conta Microsoft Outlook por meio do Model Context Protocol. Peça ao seu assistente de IA para pesquisar sua caixa de entrada, enviar e-mails, agendar reuniões, gerenciar contatos e configurar definições da caixa de correio — sem sair da conversa. Funciona com Claude, Cursor, Windsurf e qualquer cliente compatível com MCP.

Funciona com contas pessoais Outlook.com e contas corporativas/escolares Microsoft 365.

_{Pesquisar caixa de entrada → ler e resumir → rascunhar uma resposta — tudo a partir da conversa}

O que você pode fazer

• 📨 Pesquisar e ler e-mails — encontre mensagens por remetente, assunto, data ou palavras-chave; leia conversas completas com agrupamento por conversa; sinalize, mova, exporte ou categorize vários e-mails de uma só vez
• 🛡️ Enviar e-mails com controles de segurança — pré-visualização em modo de teste, dicas de e-mail antes do envio (fora do escritório, caixa de correio cheia, restrições de entrega), limite de taxa por sessão e lista de permissões de destinatários para evitar erros
• ✏️ Criar rascunhos de e-mails para revisão — crie, atualize e envie rascunhos; responda e encaminhe como rascunho; pré-visualize antes de salvar com o modo de teste
• 📅 Gerenciar seu calendário — veja eventos futuros, agende reuniões com participantes, recuse ou cancele convites
• 📦 Exportar e-mails — salve mensagens individuais em Markdown, EML, JSON ou CSV; exporte conversas completas em MBOX ou HTML; exporte em lote resultados de pesquisa em uma única chamada
• 🔍 Investigar cabeçalhos de e-mail — acesso completo aos cabeçalhos brutos (DKIM, SPF, DMARC, cadeia de entrega, X-Mailer, X-Originating-IP) para investigação de phishing e revisão de conformidade
• 🗂️ Organizar sua caixa de entrada — crie pastas aninhadas (endereçáveis por caminho), configure regras de caixa de entrada, codifique por cores com categorias, gerencie a Caixa de Entrada Focada — tudo funciona em conjunto para automação completa da caixa de entrada
• 🔄 Acompanhar mudanças na caixa de entrada — sincronização delta detecta e-mails novos, modificados e excluídos desde sua última verificação, com tokens para sondagem incremental
• 👥 Gerenciar contatos — pesquise sua agenda de contatos e o diretório organizacional, crie e atualize registros de contatos
• ⚙️ Configurar definições — defina respostas automáticas de ausência, horário de trabalho e fuso horário
• 📬 Acessar caixas de correio compartilhadas — leia caixas de entrada de equipes e contas de serviço (Microsoft 365)
• 🏢 Encontrar salas de reunião — pesquise por prédio, andar, capacidade, equipamento de áudio/vídeo e acessibilidade para cadeirantes (Microsoft 365)

Por que o Outlook Assistant?

Recursos

22 ferramentas no total — consolidadas a partir de 55 para desempenho ideal da IA. Consulte a Referência de Ferramentas para obter detalhes completos dos parâmetros.

Formatos de Exportação

O suporte a formatos varia conforme target:

Exporte e-mails individuais, resultados de pesquisa ou conversas inteiras — use target=messages com uma consulta de pesquisa (ou o atalho query) para exportar em lote sem coletar IDs manualmente.

Compatibilidade de Contas

O Outlook Assistant funciona com contas Microsoft pessoais e corporativas/escolares, mas alguns recursos se comportam de maneira diferente:

Observação: Em contas pessoais, a API $search da Microsoft tem suporte limitado para consultas em texto livre. O Outlook Assistant lida com isso automaticamente com pesquisa progressiva — se sua consulta não retornar resultados, ele recorre a filtros OData, filtros booleanos e listagem de mensagens recentes para encontrar seus e-mails. Para obter resultados mais diretos em contas pessoais, use os parâmetros de filtro estruturados (from, subject, to, receivedAfter).

O Que Torna Isso Diferente

• Pesquisa progressiva — em contas onde a API $search da Microsoft é limitada, o Outlook Assistant recorre automaticamente a até 4 estratégias de pesquisa para encontrar seus e-mails e informa qual delas respondeu em _meta.searchMetadata, juntamente com qualquer filtro que não pôde atender (droppedFilters). A maioria dos wrappers da Graph API falha silenciosamente; este se adapta e informa você.
• Forense de e-mail — acesso a cabeçalhos brutos para DKIM, SPF, DMARC, cadeia de entrega, X-Mailer, X-Originating-IP e pontuações de spam. Retorna os dados completos para que você possa investigar phishing, auditar conformidade ou rastrear problemas de entrega. (Veredito automático está no roadmap; hoje os dados são apresentados e analisados na conversa.)
• Sincronização delta — monitoramento incremental da caixa de entrada retorna apenas o que mudou desde sua última verificação, com tokens para sondagem contínua. Projetado para fluxos de trabalho de agentes que precisam monitorar uma caixa de correio.
• Operações em lote — sinalize, mova, exporte ou categorize vários e-mails em uma única chamada. A exportação orientada por pesquisa permite exportar resultados em lote sem coletar IDs manualmente.
• Inteligência pré-envio — verifique destinatários quanto a ausência, caixa cheia, restrições de entrega e status de moderação antes de enviar — nenhum outro servidor MCP do Outlook oferece isso.
• Automação composta — regras, categorias, pastas e Caixa de Entrada Focada funcionam juntas. Configure o gerenciamento completo da caixa de entrada por meio do seu assistente de IA em uma única conversa.

Segurança e Eficiência de Tokens

O Outlook Assistant foi projetado com princípios de segurança em primeiro lugar para acesso a e-mail orientado por IA:

Proteções para ações destrutivas — Cada ferramenta carrega anotações MCP (readOnlyHint, destructiveHint, idempotentHint) para que clientes de IA possam aprovar automaticamente leituras seguras e solicitar confirmação para operações destrutivas, como envio de e-mails ou exclusão de eventos.

Proteções de envio de e-mail — A ferramenta send-email inclui:

• Dicas de e-mail pré-envio (checkRecipients: true) — verifique destinatários quanto a ausência, caixa cheia e restrições de entrega antes de enviar
• Modo de teste (dryRun: true) — pré-visualize e-mails compostos sem enviar
• Limite de taxa por sessão — configurável via OUTLOOK_MAX_EMAILS_PER_SESSION (padrão: ilimitado)
• Lista de permissões de destinatários — restrinja o envio a endereços/domínios aprovados via OUTLOOK_ALLOWED_RECIPIENTS

Configuração recomendada: ative ambas as proteções de segurança no seu .mcp.json desde o primeiro dia. Elas estão desativadas por padrão; auth action=about informa o estado delas e imprime uma dica de configuração quando não definidas. Consulte .mcp.json.example para obter um modelo de copiar e colar.

"env": {
  "OUTLOOK_CLIENT_ID": "…",
  "OUTLOOK_CLIENT_SECRET": "…",
  "OUTLOOK_MAX_EMAILS_PER_SESSION": "10",
  "OUTLOOK_ALLOWED_RECIPIENTS": "your-domain.com,trusted@example.com"
}

Proteções de rascunho — A ferramenta draft compartilha os controles de segurança send-email: pré-visualização em modo de teste, lista de permissões de destinatários, validação de dicas de e-mail e limite de taxa. A ação send compartilha o contador de limite de taxa send-email, evitando burla pelo caminho de rascunho-e-depois-envio.

Arquitetura otimizada para tokens — As ferramentas são consolidadas usando a abordagem STRAP (Ferramenta Única, Recurso, Padrão de Ação). 22 ferramentas em vez de 55 reduz a sobrecarga por turno em ~11.000 tokens (~64%), mantendo mais do contexto do assistente de IA disponível para sua conversa real. Menos ferramentas também significa que a IA seleciona a ferramenta certa com mais precisão — pesquisas mostram que a seleção de ferramentas degrada além de ~40 ferramentas.

Importante: Essas proteções são medidas de defesa em profundidade que reduzem o risco, mas não são uma garantia contra ações não intencionais. O acesso a e-mail orientado por IA é inerentemente sensível — sempre revise as chamadas de ferramentas antes de aprovar, especialmente para envios e exclusões. Nenhuma proteção automatizada é infalível, e você permanece responsável pelas ações realizadas por meio da sua caixa de correio.

Início Rápido

1. Instalar

npm install -g @littlebearapps/outlook-assistant

Ou execute diretamente sem instalar:

npx @littlebearapps/outlook-assistant

Para verificar qual versão você tem ou para ver as opções disponíveis:

outlook-assistant --version     # prints e.g. 3.11.1
outlook-assistant --help        # usage, options and key environment variables

Sem argumentos, o servidor fala o Model Context Protocol via stdio. Normalmente, ele é iniciado pelo seu cliente MCP em vez de executado manualmente — iniciado a partir de um terminal, ele simplesmente aguardará na entrada padrão.

2. Registrar um Aplicativo Azure

Você precisa de um registro de aplicativo no Microsoft Azure para autenticar. Consulte o Guia de Configuração do Azure para um passo a passo detalhado (incluindo a criação da conta Azure pela primeira vez), ou se você já fez isso antes:

1. Crie um novo registro de aplicativo em portal.azure.com
2. Adicione permissões delegadas do Microsoft Graph (Mail, Calendar, Contacts)
3. Crie um segredo de cliente e copie o Valor (não o ID do Segredo)
4. Em Autenticação > Adicionar uma plataforma > Aplicativos móveis e de desktop — marque o URI nativeclient
5. Ative "Permitir fluxos de clientes públicos" em Autenticação > Configurações avançadas
6. (Opcional) Defina o URI de redirecionamento para http://localhost:3333/auth/callback — necessário apenas para o fluxo de autenticação via navegador

3. Configure Seu Cliente MCP

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

claude mcp add outlook -- npx @littlebearapps/outlook-assistant

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

4. Autentique-se

1. Inicie o servidor de autenticação: outlook-assistant-auth (ou npx @littlebearapps/outlook-assistant-auth)
2. No seu assistente de IA, use a ferramenta auth com action=authenticate para obter uma URL OAuth
3. Abra a URL, entre com sua conta Microsoft e conceda as permissões
4. Os tokens são salvos localmente e atualizados automaticamente

Nota: O servidor de autenticação precisa das variáveis de ambiente OUTLOOK_CLIENT_ID e OUTLOOK_CLIENT_SECRET. A configuração "env" do seu cliente MCP se aplica apenas ao processo do servidor MCP — ao executar o servidor de autenticação separadamente, certifique-se de que elas estejam definidas em um arquivo .env ou exportadas no seu shell.

Instalação

Pré-requisitos

• Node.js 18.0.0 ou superior
• npm (incluído com Node.js)
• Conta Azure para registro de aplicativo (o nível gratuito funciona)

Pelo npm (recomendado)

npm install -g @littlebearapps/outlook-assistant

Pelo código-fonte

git clone https://github.com/littlebearapps/outlook-assistant.git
cd outlook-assistant
npm install

Opções de CLI

Um argumento não reconhecido é reportado em stderr e sai com código 1, em vez de iniciar um servidor que o ignoraria.

Registro de Aplicativo no Azure

Primeira vez com Azure? O Guia de Configuração do Azure cobre tudo, desde a criação de conta até sua primeira autenticação, incluindo configuração de cobrança e armadilhas comuns.

Crie o Aplicativo

1. Abra o Portal do Azure
2. Entre com uma conta Microsoft corporativa ou pessoal
3. Pesquise por Registros de aplicativo e clique em Novo registro
4. Digite um nome (ex.: "Outlook Assistant Server")
5. Selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft
6. Defina o URI de redirecionamento: plataforma Web, URI http://localhost:3333/auth/callback
7. Clique em Registrar
8. Copie o ID do aplicativo (cliente)

Adicione Permissões

1. Vá para Permissões de API > Adicionar uma permissão > Microsoft Graph > Permissões delegadas
2. Adicione estas permissões obrigatórias:
   • offline_access — tokens de atualização entre sessões
   • User.Read — perfil básico
   • Mail.Read, Mail.ReadWrite, Mail.Send — operações de e-mail
   • Calendars.Read, Calendars.ReadWrite — operações de calendário
   • Contacts.Read, Contacts.ReadWrite — gerenciamento de contatos
   • MailboxSettings.ReadWrite — configurações, respostas automáticas, categorias
   • People.Read — pesquisa de pessoas
3. Opcionalmente, adicione permissões somente para organização (apenas contas corporativas/de estudante):
   • Mail.Read.Shared — acesso a caixas de correio compartilhadas
   • Place.Read.All — pesquisa de salas de reunião (requer consentimento do administrador)
4. Clique em Adicionar permissões

Crie um Segredo de Cliente

1. Vá para Certificados e segredos > Novo segredo de cliente
2. Digite uma descrição e selecione a expiração
3. Clique em Adicionar
4. Copie o Valor do segredo imediatamente — você não poderá vê-lo novamente. Use o Valor, não o ID do Segredo.

Configuração

Variáveis de Ambiente

Crie um arquivo .env a partir do exemplo:

cp .env.example .env

Edite com suas credenciais do Azure:

OUTLOOK_CLIENT_ID=your-application-client-id
OUTLOOK_CLIENT_SECRET=your-client-secret-VALUE
USE_TEST_MODE=false

Nota: O servidor também aceita MS_CLIENT_ID e MS_CLIENT_SECRET para compatibilidade retroativa.

Substituições opcionais (v3.8.0+) — consulte .env.example para a lista completa com exemplos comentados:

Configuração do Cliente MCP

Consulte Início Rápido — Configure Seu Cliente MCP acima para configurações do Claude Desktop, Claude Code, Cursor e Windsurf.

Se instalado pelo código-fonte, use node em vez de npx:

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/path/to/outlook-assistant/index.js"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

Fluxo de Autenticação

Fluxo de Código de Dispositivo (Padrão — Recomendado)

Nenhum servidor de autenticação necessário. Funciona em qualquer lugar, incluindo ambientes remotos/sem cabeça.

1. Peça ao seu assistente de IA para autenticar (chama a ferramenta auth com action=authenticate)
2. Visite a URL exibida (microsoft.com/devicelogin) em qualquer navegador, qualquer dispositivo
3. Digite o código, entre com sua conta Microsoft e conceda as permissões
4. Diga ao seu assistente de IA para concluir a autenticação (chama auth com action=device-code-complete)
5. Os tokens são salvos em ~/.outlook-assistant-tokens.json e atualizados automaticamente

Pré-requisito: Ative "Permitir fluxos de clientes públicos" no Portal do Azure > seu aplicativo > Autenticação > Configurações avançadas.

Reinicializações do servidor (v3.7.2+): O estado do código de dispositivo é persistido em ~/.outlook-assistant-pending-auth.json, então device-code-complete funciona mesmo se o servidor MCP reiniciar entre os passos 1 e 4 (ex.: ponte Untether/Telegram, mudanças de sessão do Claude Desktop).

Fluxo de Redirecionamento via Navegador (Alternativa)

Para desenvolvimento em localhost ou se você preferir o fluxo OAuth tradicional:

npm run auth-server

Isso inicia um servidor local na porta 3333 para lidar com o callback OAuth.

1. No seu assistente de IA, use a ferramenta auth com action=authenticate, method=browser
2. Abra a URL fornecida no seu navegador
3. Entre e conceda as permissões — os tokens são salvos automaticamente

Nota: O servidor de autenticação lê OUTLOOK_CLIENT_ID e OUTLOOK_CLIENT_SECRET das variáveis de ambiente. A configuração "env" do seu cliente MCP se aplica apenas ao processo do servidor MCP, não a um servidor de autenticação iniciado separadamente.

Estrutura de Diretórios

outlook-assistant/
├── index.js                 # Main entry point (22 tools)
├── config.js                # Configuration settings
├── outlook-auth-server.js   # OAuth server (port 3333)
├── auth/                    # Authentication module (1 tool)
├── email/                   # Email module (7 tools)
│   ├── mail-tips.js         # Pre-send recipient validation
│   ├── headers.js           # Email header retrieval
│   ├── mime.js              # Raw MIME/EML content
│   ├── conversations.js     # Thread listing/export
│   ├── attachments.js       # Attachment operations
│   └── ...
├── calendar/                # Calendar module (3 tools)
├── contacts/                # Contacts module (2 tools)
├── categories/              # Categories module (3 tools)
├── settings/                # Settings module (1 tool)
├── folder/                  # Folder module (1 tool)
├── rules/                   # Rules module (1 tool)
├── advanced/                # Advanced module (2 tools)
└── utils/
    ├── graph-api.js         # Microsoft Graph API client (includes $batch)
    ├── safety.js            # Rate limiting, recipient allowlist, dry-run
    ├── odata-helpers.js     # OData query building
    ├── field-presets.js     # Token-efficient field selections
    ├── response-formatter.js # Verbosity levels
    └── mock-data.js         # Test mode data

Solução de Problemas

"Cannot find module '@modelcontextprotocol/sdk/server/index.js'"

npm install

"EADDRINUSE: address already in use :::3333"

npx kill-port 3333
npm run auth-server

"Invalid client secret" (AADSTS7000215)

Você está usando o ID do Segredo em vez do Valor do Segredo. Vá para o Portal do Azure > Certificados e segredos e copie a coluna Valor para OUTLOOK_CLIENT_SECRET.

O Valor é exibido apenas uma vez, quando o segredo é criado — se você navegou para longe, ele não pode ser lido novamente, então crie um novo segredo. Um segredo expirado produz este mesmo erro, então verifique também a coluna Expira.

Desde a v3.11.0, o servidor detecta este erro e anexa a explicação à mensagem original da Microsoft, para que você veja tanto o código de erro bruto quanto o que fazer a respeito.

A URL de autenticação não funciona

Se estiver usando o fluxo de navegador: inicie o servidor de autenticação primeiro com npm run auth-server. Se estiver usando o fluxo de código de dispositivo: visite microsoft.com/devicelogin em vez disso.

Código de dispositivo "invalid_client"

Ative "Permitir fluxos de clientes públicos" no Portal do Azure > Registros de aplicativo > Autenticação > Configurações avançadas.

A atualização do token falha após ~60 minutos (autenticação por código de dispositivo)

Corrigido na v3.7.2. Versões anteriores enviavam client_secret em solicitações de atualização de token para autenticação por código de dispositivo, o que a Microsoft rejeita para fluxos de clientes públicos. Atualize para v3.7.2+ ou reautentique.

Respostas de API vazias

Verifique o status de autenticação com a ferramenta auth (action=status). Os tokens podem ter expirado — reautentique se necessário.

Desenvolvimento

Executando Testes

npm test                     # Jest unit tests
npm run inspect              # MCP Inspector (interactive)

Modo de Teste

Execute com dados simulados (sem chamadas reais de API):

USE_TEST_MODE=true npm start

Estendendo o Servidor

1. Crie um novo diretório de módulo (ex.: tasks/)
2. Implemente manipuladores de ferramentas em arquivos separados
3. Exporte as definições de ferramentas do index.js do módulo
4. Importe e adicione ferramentas ao array TOOLS no index.js principal
5. Adicione testes em test/
6. Atualize docs/quickrefs/tools-reference.md

Documentação

Documentação completa: docs/

Limitações Conhecidas

• Pesquisa em conta pessoal: Texto livre query e o searchExpression bruto (anteriormente kqlQuery) dependem da API $search da Microsoft, que tem suporte limitado em contas pessoais do Outlook.com. query mitiga isso com fallback progressivo (filtros OData, filtros booleanos e, em seguida, uma varredura no lado do cliente). $search com escopo de campo (ex.: subject:"…") é rejeitado diretamente lá; desde a v3.10.0, expressões from:/to:/subject: são traduzidas para os filtros OData equivalentes mais próximos e tentadas novamente, mas operadores booleanos, agrupamento, curingas e outros prefixos de campo não são — esses ainda terminam com um resultado explícito de nenhum resultado, em vez de uma busca mais ampla silenciosa. Filtros estruturados (from, subject, to, receivedAfter) continuam sendo o caminho mais direto. A pesquisa entre pastas (searchAllFolders: true) retorna um superconjunto dos resultados apenas da caixa de entrada. Observe que query e searchExpression não são intercambiáveis lá: searchExpression vai para $search, que corresponde à mensagem inteira, incluindo o corpo, e classifica por relevância em vez de data, enquanto query recorre a uma correspondência de substring no assunto que nunca lê os corpos.
• Profundidade de pesquisa to em contas pessoais: o filtro de destinatário no lado do servidor é rejeitado, então to é correspondido localmente nas 500 mensagens mais recentes (OUTLOOK_SEARCH_SCAN_LIMIT, máximo 5000). Em um arquivo grande que exclui e-mails mais antigos — combine to com receivedAfter/receivedBefore. Desde a v3.11.1, a resposta informa isso sempre que a varredura foi truncada, independentemente de ter correspondido ou não.
• Caixa de entrada focada: Disponível apenas em contas corporativas/escolares do Microsoft 365.
• Caixas de correio compartilhadas: Exigem permissão Mail.Read.Shared e uma conta corporativa/escolar.
• Pesquisa de sala de reunião: Exige permissão Place.Read.All com consentimento do administrador (somente contas corporativas/escolares).
• Caminho padrão de exportação: As exportações são salvas no diretório temporário do sistema por padrão. Use savePath ou outputDir para especificar um local diferente.

Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para diretrizes.

Segurança

Para preocupações de segurança, consulte nossa Política de Segurança. Não abra problemas públicos para vulnerabilidades.

Changelog

Consulte CHANGELOG.md para o histórico de versões.

Sobre

Construído e mantido por Little Bear Apps. Outlook Assistant é open source sob a Licença MIT.