outlook-mcp

Outlook/Office365 para agentes de IA — servidor MCP (stdio) + serviço FastAPI (:8445), sem App Registration no Azure AD.

Arquitetura

Claude Code / agente ──(MCP stdio)──► mcp_server ──HTTP──► outlook_service :8445
                                                              │
                                              ┌───────────────┴───────────────┐
                                              ▼ primário                      ▼ fallback
                                     OWA REST API v2.0                Playwright/Chromium
                                (token da sessão, TTL 30min)         (sessão web logada)

• Sem App Registration: o token Bearer é extraído da própria sessão web do Outlook (interceptação Playwright), com cache de 30 min e invalidação automática em 401.
• 11 ferramentas MCP: inbox, inbox compartilhado, enviar e-mail, agenda hoje/semana, detalhes de evento, criar/editar/cancelar evento, disponibilidade, freebusy.
• Endpoints REST completos (/calendario/*, /email/*): use direto por HTTP se preferir (bridges, cron, outros serviços).

⚠️ Sobre o método de login. Este projeto não usa OAuth/App Registration — ele automatiza o login web real do Outlook via Playwright (a senha é lida de uma variável de ambiente e digitada no formulário de login da Microsoft). É um atalho deliberado para evitar burocracia de Azure AD, mas foge do fluxo oficial suportado pela Microsoft: rode isso só com contas que você controla, entenda que a sessão pode quebrar se a Microsoft mudar o formulário de login ou exigir MFA adicional, e prefira uma App Registration + Graph API oficial se isso for rodar em produção para terceiros.

Instalação

pip install -e .
playwright install chromium

Configure as variáveis de ambiente antes do primeiro login:

Variável	Uso
OUTLOOK_MCP_EMAIL	conta que faz login (obrigatório)
OUTLOOK_MCP_PASSWORD	senha dessa conta (obrigatório, só usado no login inicial)
OUTLOOK_MCP_DEFAULT_MAILBOX	e-mail do calendário/caixa gerenciada por padrão (opcional)
OUTLOOK_MCP_DEFAULT_CC	e-mail incluído em CC automático nos envios (opcional)
OUTLOOK_MCP_ORG_DOMAINS	domínios internos da sua organização, separados por vírgula — usado pra distinguir participante interno de externo no FreeBusy (opcional)

Login (uma vez): inicie o serviço e faça o login web quando o Chromium abrir — a sessão persiste (cookies) e o serviço renova sozinho.

outlook-service          # FastAPI em 127.0.0.1:8445

Produção (macOS): use launchd/com.outlookmcp.service.plist via install.sh (inclui restart automático). Em Linux, rode outlook-service sob o supervisor de sua preferência (systemd, supervisord etc.) — não há unit pronta ainda.

Registrar o MCP em outro projeto (Claude Code)

.mcp.json do projeto (ou ~/.claude/.mcp.json para todas as sessões):

{
  "mcpServers": {
    "outlook": {
      "command": "outlook-mcp"
    }
  }
}

O MCP fala com localhost:8445 — o serviço precisa estar rodando (mesma máquina).

FreeBusy externo (opcional)

Calendários externos via iCal: copie config/ical_feeds.json.example para ical_feeds.json no diretório do pacote instalado e preencha. ⛔ ical_feeds.json contém tokens privados — está no .gitignore, nunca commite.

Notas de robustez

• Token OWA: TTL 30 min + invalidação em 401. Um TTL curto força refresh constante do Chromium de vida longa, o que desgasta o driver com o tempo — 30 min reduz bastante essa frequência sem risco de token vencido (o token real vive ~60 min).
• Recomenda-se um watchdog no /health (o corpo indica status: degraded mesmo com HTTP 200) e uma reciclagem preventiva diária do serviço.

Status

O projeto ainda não tem testes automatizados nem CI. Use, reporte problemas, contribua.