mariana-outlook-mcp

A custom MCP (Model Context Protocol) server that gives Claude Code access to Outlook Mail, Calendar, and Contacts via Microsoft Graph — with safety-first defaults. Sibling of mariana-google-mcp, same architecture pointed at Microsoft accounts (M365 work/school and personal Outlook/Hotmail).

Design Philosophy

Built for an operator who wants AI help managing their mailbox without risk of accidental damage:

• No sending email — enforced by Microsoft, not just this code. The server never requests the Mail.Send permission, so its tokens are physically incapable of sending. You draft; you send from Outlook.

• No deleting anything. Mail moves to a "To Be Deleted" folder (reversible). Calendar events get "DELETE - " prepended to the title. You review and confirm in the Outlook UI.

• Every mutation is logged. An append-only JSONL action log records every write with timestamps, tool name, account, and summary.

• Multi-account support. Work and personal Microsoft accounts under named aliases.

• No client secret. Desktop PKCE flow — the only credential is a public Application ID.

Related MCP server: Outlook MCP Server

Setup

Easiest path: paste this one line into Claude Code and it runs the entire setup for you, including guiding you through the Azure clicks:

Fetch https://raw.githubusercontent.com/marianasmall/mariana-outlook-mcp/main/SETUP-PROMPT.md and follow the instructions in it.

The manual steps below cover the same ground.

1. Azure App Registration

1. Go to portal.azure.com → search "App registrations" → New registration

2. Name: "Claude Code". Supported account types: Accounts in any organizational directory and personal Microsoft accounts (the option that includes personal accounts)

3. Redirect URI: platform Public client/native (mobile & desktop), value http://localhost

4. Register, then copy the Application (client) ID from the Overview page

5. Under Authentication, set "Allow public client flows" to Yes

No client secret is created — this is a PKCE public client.

2. Install and Build

git clone https://github.com/marianasmall/mariana-outlook-mcp.git
cd mariana-outlook-mcp
npm install
npm run build

3. Add to Claude Code

claude mcp add outlook --scope user \
  -e MS_CLIENT_ID="<application-client-id>" \
  -- node /FULL/PATH/TO/mariana-outlook-mcp/dist/index.js

Optional: set MS_TENANT to a specific tenant ID (defaults to common, which accepts both work and personal accounts). Restart Claude Code after adding.

4. Authenticate

Run the microsoft_auth tool with a friendly account name (e.g. consulting, personal). A browser window opens for consent; approve as the matching Microsoft account. Repeat per account. Verify with microsoft_status.

Available Tools (20)

Authentication & Status

Mail (10 tools)

Calendar (7 tools)

Contacts (2 tools)

Multi-Account Support

microsoft_auth account_name: "consulting"
microsoft_auth account_name: "personal"

Most tools accept an optional account parameter; omitted, they use the default (first-connected) account. microsoft_status shows all accounts and their health.

Configuration Files

All state lives in ~/.config/mariana-outlook-mcp/:

Graph-vs-Gmail Differences Worth Knowing

• Categories ≈ labels; folders ≈ folders. Outlook has both. Categories apply like Gmail labels; soft-delete uses a folder because that's the native Outlook idiom.

• Reply drafts take a reply_to_message_id (Graph threads replies from a message, not a thread ID).

• Moved messages get new IDs — Graph reassigns message IDs on folder moves.

• Attendee invitations: Outlook sends invitation/update emails itself when an event has attendees; calendar_create therefore defaults to NOT attaching attendees (names go in the description) unless send_invites=true.

• Refresh tokens last ~90 days sliding for personal accounts — regular use keeps them alive indefinitely; a long-unused account may need re-auth.

License

MIT