Setting up Outlook

Microsoft has permanently retired basic auth for Outlook.com, so app passwords no longer work — OAuth2 is the only way in. That needs a free Azure app registration, done once.

1. Register the app

1. Go to portal.azure.com → Microsoft Entra ID → App registrations → New registration.
2. Name it anything (rubit-mcp-mail).
3. Supported account types: "Accounts in any organizational directory and personal Microsoft accounts". Required for an outlook.com/hotmail address — the default single-tenant option will reject your sign-in.
4. Leave Redirect URI empty. Click Register.
5. Authentication → Advanced settings → Allow public client flows: set to Yes. Without this the device-code flow fails immediately.
6. API permissions → Add a permission → APIs my organization uses tab → search Office 365 Exchange Online → Delegated permissions → check IMAP.AccessAsUser.All → Add permissions.
7. Copy the Application (client) ID from the Overview page.

If registering an app is blocked by your organization's policy, sign in to portal.azure.com with the personal Microsoft account itself (not a work account) — a personal outlook.com/hotmail account has its own directory that org policies don't govern.

2. Configure

mkdir -p ~/.config/rubit-mcp-mail
cat > ~/.config/rubit-mcp-mail/config.toml <<'EOF'
download_dir = "~/Downloads/rubit-mcp-mail"

[accounts.outlook]
provider  = "outlook"
email     = "you@outlook.com"
client_id = "<Application (client) ID from step 7>"
EOF

No secrets go in this file. Tokens live in your OS keyring (with a 0600 file fallback on headless machines). See Configuration for every key.

3. Sign in

./.venv/bin/rubit-mcp-mail auth outlook

This prints a code and a URL; approve in your browser. The refresh token is cached, so this is a one-time step — the server itself only ever refreshes silently and never prompts. The same flow runs in the settings window if you would rather not use a terminal.

4. Verify

./.venv/bin/rubit-mcp-mail doctor

This checks config, credentials, connectivity, and authentication, then lists your folders with their detected roles. If this works, the server will too.

Can't register your own app?

If your Microsoft account genuinely can't register an Azure app (and it isn't just a work-tenant policy — see the note in step 1), you can use a public client ID that other open-source mail tools already share for exactly this purpose instead of registering your own: Thunderbird's, 9e5f94bc-e8a4-4e73-b8be-63364c29d753. It's multi-tenant and already has the IMAP.AccessAsUser.All permission granted, so device-code sign-in works immediately — just paste it in as client_id:

[accounts.outlook]
provider  = "outlook"
email     = "you@outlook.com"
client_id = "9e5f94bc-e8a4-4e73-b8be-63364c29d753"

Two things to know:

• The Microsoft consent screen will say "Thunderbird" is requesting access. Cosmetic only — the token it grants works the same.
• Because this ID is outside our control, Microsoft could disable or rotate it in the future (it's happened to Thunderbird's client IDs before). If sign-in suddenly starts failing, that's the first thing to suspect. Switch to your own registration above if that happens.

The settings window's Accounts tab offers this ID directly for accounts that can't register their own app.