mariana-outlook-mcp
Connect Claude Code to one or more Microsoft/Outlook accounts for safe, logged help with mail, calendar, and contacts—without sending email or permanently deleting anything.
Authenticate accounts via OAuth PKCE and check live connection health.
Search/read Outlook mail and create plain-text or HTML drafts with attachments and reply threading; drafts are never sent.
List folders and categories, create categories, apply/remove categories, and create inbox rules (forwarding is opt-in).
Soft-delete mail by moving messages to a To Be Deleted folder.
Manage calendar events: list, search, get details, create/update, flag for deletion by title prefix, and check free/busy availability; attendee invitations are opt-in.
Search and list contacts by name, email, phone, or organization.
Most tools support an optional account parameter for multi-account use, and every write is logged.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mariana-outlook-mcp Find emails from my manager about Q3 planning"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mariana-outlook-mcp
Let Claude Code read, organize and draft in your Outlook mailbox, calendar and contacts. It can't send email: the Mail.Send permission is never requested. It doesn't delete: mail moves to a To Be Deleted folder and events get a DELETE prefix. Mail-rule forwarding and calendar invites are opt-in actions you ask for.
Who this is for: people who want AI help in Outlook (work M365 or personal Outlook/Hotmail) with safety-first defaults and a log of every change.
The 22 tools Claude Code sees once the server is connected, plus the exact Microsoft Graph permissions it asks for.
Quick start (you need an Azure Application ID first; see Setup step 1):
git clone https://github.com/marianasmall/mariana-outlook-mcp.git
cd mariana-outlook-mcp && npm install && npm run build
claude mcp add outlook --scope user -e MS_CLIENT_ID="<application-client-id>" -- node "$PWD/dist/index.js"Then restart Claude Code and run the sign-in tool (Setup step 4).
What This Is
A custom MCP (Model Context Protocol) server that connects Claude Code to Outlook Mail, Calendar, and Contacts through Microsoft Graph. Sibling of mariana-google-mcp, same architecture pointed at Microsoft accounts (M365 work/school and personal Outlook/Hotmail).
Related MCP server: Outlook MCP Server
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.Sendpermission, so its tokens cannot send a message. You draft (and can revise or soft-delete drafts); you send from Outlook. Two opt-in actions can still make mail go out, and only when you ask: an inbox rule with a forwarding address (outlook_create_rule), and a calendar event created withsend_invites=true.No deleting anything. Mail moves to a "To Be Deleted" folder (reversible); drafts move to Deleted Items. 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.
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
Go to portal.azure.com → search "App registrations" → New registration
Name: "Claude Code". Supported account types: Accounts in any organizational directory and personal Microsoft accounts (the option that includes personal accounts)
Redirect URI: platform Public client/native (mobile & desktop), value
http://localhostRegister, then copy the Application (client) ID from the Overview page
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 build3. 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.jsOptional: 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 (22)
Authentication & Status
Tool | Description |
| Authenticate a Microsoft account via OAuth browser flow (PKCE) |
| Live connection health for all configured accounts |
Mail (14 tools)
Tool | Description |
| Search messages (KQL: from:, subject:, or keywords) |
| Read a specific message by ID (plain-text body + attachment names) |
| Save a message's file attachment(s) to an absolute folder. Allowlist: save_dir must resolve (symlinks followed, case/Unicode-insensitive) inside a top-level |
| Create a draft: plain text or rich HTML body, attachments (≤3MB/file), optional reply-in-thread (does NOT send) |
| List drafts (id, subject, to, cc, lastModified, conversationId, isReply). Read-only |
| Edit a draft in place (PATCH only the fields passed; reply threading preserved). Refuses non-drafts. Does NOT send |
| Soft-delete a draft: move to Deleted Items (never a permanent delete). Refuses non-drafts |
| List mail folders with unread counts |
| List categories (the Gmail-labels equivalent) |
| Create a category |
| Apply a category to messages |
| Remove a category from messages |
| Create an inbox rule (the Gmail-filter equivalent) |
| Soft-delete: move messages to a "To Be Deleted" folder |
Calendar (7 tools)
Tool | Description |
| List upcoming events |
| Search events by title keyword |
| Full details of one event |
| Create an event (attendees NOT invited by default) |
| Modify an event (attendee-notification caveat in tool description) |
| Soft-delete: prepend "DELETE - " to the title |
| Free/busy blocks for a date range |
Contacts (2 tools)
Tool | Description |
| Search contacts by name, email, or phone |
| List contacts, optionally filtered |
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/:
File | Purpose |
| Account registry (aliases, email hashes, default) |
| OAuth tokens per account (never leave this machine) |
| Append-only log of every write operation |
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_createtherefore defaults to NOT attaching attendees (names go in the description) unlesssend_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
Available Tools
21 toolscalendar_availabilityA
Check free/busy status for a date or date range (derived from events not marked 'free').
Inputs: date_start (required), account, date_end.
calendar_createA
Create a calendar event. By default attendees are NOT invited (their names go into the description instead); set send_invites=true to actually invite them — Outlook sends invitation emails to every attendee on the event.
Inputs: end (required), start (required), title (required), account, +4 more.
calendar_flag_deleteA
Soft-delete: prepend 'DELETE - ' to event title. Does NOT actually delete the event.
Inputs: event_id (required), account.
calendar_getB
Get full details of a specific calendar event.
Inputs: event_id (required), account.
calendar_listA
List upcoming calendar events. Times are returned in UTC.
Inputs: account, days_ahead.
calendar_searchA
Search calendar events by keyword in the title. Times are returned in UTC.
Inputs: query (required), account, time_max, time_min.
calendar_updateA
Modify an existing calendar event. CAUTION: if the event has invited attendees, Outlook notifies them of changes automatically.
Inputs: event_id (required), end, start, title, +3 more.
contacts_listB
List Outlook contacts, optionally filtered by organization or name.
Inputs: group, account, max_results.
contacts_searchB
Search Outlook contacts by name, email, or phone number.
Inputs: query (required), account, max_results.
microsoft_authA
Authenticate a Microsoft account (M365 work/school or personal e.g. Hotmail). Returns the consent URL IMMEDIATELY (does not block): give it to the user, they approve in the browser as the right Microsoft account, and the token saves in the background. Confirm afterwards with microsoft_status. A browser tab also opens automatically as a convenience, but the URL in the response is authoritative if it opens with the wrong profile.
Inputs: account_name.
microsoft_statusA
Check connection health for all configured Microsoft accounts with a LIVE credential check against Microsoft (not just local file state). tokenStatus 'needs_reauth' means run microsoft_auth for that account.
Inputs: no named parameters.
outlook_apply_categoryA
Apply a category to one or more Outlook messages (by category NAME, not ID).
Inputs: category (required), message_ids (required), account.
outlook_create_categoryA
Create a new Outlook category (the Gmail-labels equivalent).
Inputs: name (required), account, color_preset.
outlook_create_ruleA
Create an Outlook inbox rule (the Gmail-filter equivalent). Matches incoming messages by criteria and applies actions automatically. At least one criterion and one action required.
Inputs: name (required), account, mark_read, forward_to, +5 more.
outlook_draftA
Create a draft email. Does NOT send — the draft appears in Outlook's Drafts folder for manual review and sending. (The server's Microsoft permissions exclude sending entirely.)
Inputs: to (required), body (required), subject (required), cc, +5 more.
outlook_list_categoriesA
List Outlook categories (the Gmail-labels equivalent) for an account.
Inputs: account.
outlook_list_foldersA
List Outlook mail folders for an account.
Inputs: account.
outlook_move_to_deleteA
Soft-delete: move messages to a 'To Be Deleted' folder. Does NOT delete or trash messages. NOTE: moved messages get NEW message IDs.
Inputs: message_ids (required), account.
outlook_readA
Read a specific Outlook message by ID. Returns full message content as plain text.
Inputs: message_id (required), account.
outlook_remove_categoryA
Remove a category from one or more Outlook messages (by category NAME).
Inputs: category (required), message_ids (required), account.
outlook_searchB
Search Outlook messages. Uses KQL syntax (e.g. 'from:name subject:topic', or plain keywords).
Inputs: query (required), account, max_results.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools have clear, distinct purposes within their domains, but 'calendar_search' and 'calendar_list' both retrieve calendar events and could be confused. The soft-delete tools for mail and calendar share a similar pattern but are separated by domain.
All tools follow a consistent 'domain_action' pattern, using lowercase with underscores (e.g., outlook_read, calendar_create, contacts_search). The use of compound actions like 'flag_delete' and 'move_to_delete' still maintains a uniform style without mixing conventions.
With 21 tools, the server is slightly above the typical well-scoped range, but the breadth is justified by covering mail, calendar, contacts, and authentication. The tools are not excessively fragmented for the wide scope.
Mail and calendar have decent coverage, but contacts only support search and list with no create/update/delete operations. The lack of hard delete for messages/events and exclusion of sending email are notable gaps that limit full lifecycle management.
Maintenance
Related MCP Connectors
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Manage Microsoft 365 email, calendar, contacts and inbox rules via the Graph API with OAuth 2.0.
Permissioned access to Outlook, OneDrive and Teams via the user's own Microsoft account
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects Claude with Microsoft Outlook through the Graph API, providing comprehensive email, calendar, folder management, and rules creation capabilities.19MIT
- AlicenseNot gradedqualityDmaintenanceConnects Claude to Microsoft Outlook through the Microsoft Graph API, enabling email management (list, search, read, send) and calendar operations (list, create, accept, decline, delete events) via OAuth 2.0 authentication.1MIT
- FlicenseNot gradedqualityDmaintenanceProvides Claude Desktop and Claude Code with access to Microsoft 365 email and calendar services via the Microsoft Graph API. It enables users to manage emails, search folders, schedule calendar events, and check availability through natural language commands.-
- FlicenseAqualityBmaintenanceEnables Claude to manage Outlook calendar events and Microsoft To Do tasks for a specific mailbox via Microsoft Graph API.7-