outlook-mcp

Servidor MCP local que conecta o Claude Desktop à sua caixa de e-mail do Outlook (via Microsoft Graph API), para listar, buscar e organizar e-mails direto pela conversa com o Claude.

Estrutura do projeto

MCP Outlook/
├── server.py            # entrypoint stdio (Claude Desktop local)
├── server_http.py       # entrypoint HTTP (rede local: Termux, Docker)
├── outlook_mcp/         # código do servidor
│   ├── __init__.py
│   ├── auth.py          # login MSAL (device code) + cache de token
│   ├── server.py        # definição do MCP e das 16 ferramentas
│   └── http_app.py      # app Starlette + middleware de auth Bearer
├── docker/
│   └── Dockerfile
├── docs/
│   ├── entra-id.md      # registrar o app no Azure AD (passo 1)
│   └── rede-local.md    # rodar via Termux/Android/Docker na Wi-Fi
├── requirements.txt
├── .env.example         # modelo das variáveis de ambiente
└── token_cache.bin      # gerado no 1º login — NUNCA versionar

Os dois entrypoints da raiz são atalhos finos: python server.py e python server_http.py funcionam como antes.

Related MCP server: Outlook MCP Server

1. Registrar um app no Entra ID (Azure AD)

O Graph API exige um app registrado, mesmo para uso 100% pessoal e gratuito. Passo a passo completo em docs/entra-id.md. No fim você terá o OUTLOOK_MCP_CLIENT_ID.

2. Instalar dependências

cd outlook-mcp
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Configurar variáveis de ambiente

export OUTLOOK_MCP_CLIENT_ID="cole-o-client-id-aqui"

# "consumers" = contas pessoais @outlook/@hotmail (padrão, não precisa mudar)
export OUTLOOK_MCP_TENANT_ID="consumers"

No Windows (PowerShell): $env:OUTLOOK_MCP_CLIENT_ID = "...".

Há um modelo com todas as variáveis em .env.example — copie para .env (já ignorado pelo git) e preencha, ou use como referência. Para não repetir isso toda vez, você pode salvar essas variáveis direto no JSON de configuração do Claude Desktop (passo 5).

4. Primeira execução (autorizar a conta)

python server.py

Na primeira vez, o terminal vai mostrar algo como:

To sign in, use a web browser to open the page https://microsoft.com/devicelogin
and enter the code ABCD-1234 to authenticate.

Abra o link, cole o código, faça login com sua conta Outlook normal. O token fica salvo em token_cache.bin (local, não sobe pro git) e é renovado automaticamente nas próximas execuções.

5. Conectar ao Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Adicione:

{
  "mcpServers": {
    "outlook-organizer": {
      "command": "C:\\caminho\\completo\\outlook-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\caminho\\completo\\outlook-mcp\\server.py"],
      "env": {
        "OUTLOOK_MCP_CLIENT_ID": "cole-o-client-id-aqui",
        "OUTLOOK_MCP_TENANT_ID": "consumers"
      }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas devem aparecer disponíveis na conversa.

Ferramentas disponíveis

Rodando na rede local (Termux / Android / Docker)

Dá pra rodar o servidor 24/7 num celular Android antigo via Termux, fechado à sua Wi-Fi, e conectar o Claude Desktop de outra máquina. Guia completo — incluindo Docker, token de auth e proteção contra DNS rebinding — em docs/rede-local.md.

Trabalhando com volume alto

Para caixas com centenas de e-mails, a ordem que gasta menos contexto:

1. sender_stats primeiro — devolve o mapa da caixa (quem manda, quanto, quantos não lidos, até 3 assuntos de exemplo) em poucos KB. Uma listagem equivalente custaria ~7x mais. Um remetente pode misturar tipos de e-mail (fatura e cupom do mesmo endereço) — os 3 exemplos ajudam a notar isso.

2. Para classificar vários remetentes de uma vez, preview_plan — avalia uma lista de regras numa única varredura (cada mensagem cai na primeira regra que casar) e devolve nao_classificados com o que sobrou sem destino. Uma varredura por regra sairia bem mais caro para N regras.

3. move_by_sender com dry_run=True (o padrão) — confira a contagem antes de executar. Os IDs são filtrados no servidor e nunca trafegam. Use subject_contains/subject_not_contains para separar remetentes mistos.

4. Para executar um plano de várias regras de uma vez, apply_plan — mesma lista de rules do preview_plan, uma varredura, dry_run=True por padrão. Evita reexecutar move_by_sender regra por regra revarrendo a mesma janela, e evita que a caixa mude entre a primeira e a última regra.

5. Só então list_recent_emails com fields=["id","de","assunto"] e skip para o que sobrou. Cortar o bodyPreview reduz a resposta em ~75%.

target_folder sempre aceita nome de exibição (ex: 'Financeiro/Recibos'), nome bem-conhecido ('archive', 'inbox', 'deleteditems') ou id de pasta — em move_email, move_emails_batch, move_by_sender e apply_plan. Todos resolvem o nome para o id real antes de chamar o Graph.

Caixas grandes: sender_stats e move_by_sender varrem no máximo max_scan mensagens por chamada (padrão 400). Ao bater o teto, a resposta traz atingiu_limite/atingiu_limite_varredura e proximo_skip — repita a chamada com skip=proximo_skip para continuar de onde parou, em vez de subir max_scan numa única chamada.

move_emails_batch e mark_as_read_batch agrupam em lotes de 20 numa única requisição. Atenção: o move troca o ID do e-mail — use os id_novo que voltam em detalhes_movidos para qualquer passo seguinte. O PATCH do mark_as_read_batch preserva os ids.

Regras de caixa de entrada (opcional)

As ferramentas list_rules / create_rule / delete_rule exigem o escopo MailboxSettings.ReadWrite, separado de Mail.*. Esse escopo dá acesso a todas as configurações da caixa (respostas automáticas, fuso horário etc.), por isso vem desligado por padrão. Para habilitar:

1. No Entra ID → seu app → Permissões de APIs → Microsoft Graph → Permissões delegadas → adicione MailboxSettings.ReadWrite

2. Defina OUTLOOK_MCP_ENABLE_RULES=1 (no ambiente ou no env do claude_desktop_config.json)

3. Apague token_cache.bin e refaça o login para consentir o novo escopo

Sem isso, as três ferramentas devolvem um erro explicando o que falta — o restante do servidor funciona normalmente.

Por decisão de projeto, create_rule não expõe as ações forwardTo, redirectTo nem permanentDelete do Graph: regra de encaminhamento automático é o vetor clássico de vazamento de e-mail, e exclusão permanente destrói mensagem sem passar pela lixeira.

Segurança

• token_cache.bin contém tokens de acesso à sua conta — não compartilhe nem suba para repositórios públicos.

• O app só tem os escopos que você concedeu (Mail.Read/ReadWrite/Send) — não tem acesso a outros dados do Microsoft 365.

• O .gitignore do projeto já cobre token_cache.bin, .env e .venv/. Confira com git status antes do primeiro commit.