Skip to main content
Glama

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.

License: MIT Built with Claude Code Last commit

Tools exposed to Claude Code

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.Send permission, 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 with send_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

  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 (22)

Authentication & Status

Tool

Description

microsoft_auth

Authenticate a Microsoft account via OAuth browser flow (PKCE)

microsoft_status

Live connection health for all configured accounts

Mail (14 tools)

Tool

Description

outlook_search

Search messages (KQL: from:, subject:, or keywords)

outlook_read

Read a specific message by ID (plain-text body + attachment names)

outlook_download_attachment

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 ~/Projects/_intake* folder (e.g. ~/Projects/_intake, ~/Projects/_intake-client), no dot-folders; never overwrites; skips risky types (.app .command .sh .zsh .bash .plist .pkg .dmg .scpt .applescript .workflow .terminal .webloc .js .py) and item/reference attachments

outlook_draft

Create a draft: plain text or rich HTML body, attachments (≤3MB/file), optional reply-in-thread (does NOT send)

outlook_list_drafts

List drafts (id, subject, to, cc, lastModified, conversationId, isReply). Read-only

outlook_update_draft

Edit a draft in place (PATCH only the fields passed; reply threading preserved). Refuses non-drafts. Does NOT send

outlook_delete_draft

Soft-delete a draft: move to Deleted Items (never a permanent delete). Refuses non-drafts

outlook_list_folders

List mail folders with unread counts

outlook_list_categories

List categories (the Gmail-labels equivalent)

outlook_create_category

Create a category

outlook_apply_category

Apply a category to messages

outlook_remove_category

Remove a category from messages

outlook_create_rule

Create an inbox rule (the Gmail-filter equivalent)

outlook_move_to_delete

Soft-delete: move messages to a "To Be Deleted" folder

Calendar (7 tools)

Tool

Description

calendar_list

List upcoming events

calendar_search

Search events by title keyword

calendar_get

Full details of one event

calendar_create

Create an event (attendees NOT invited by default)

calendar_update

Modify an event (attendee-notification caveat in tool description)

calendar_flag_delete

Soft-delete: prepend "DELETE - " to the title

calendar_availability

Free/busy blocks for a date range

Contacts (2 tools)

Tool

Description

contacts_search

Search contacts by name, email, or phone

contacts_list

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

config.json

Account registry (aliases, email hashes, default)

tokens/<hash>.json

OAuth tokens per account (never leave this machine)

action-log.jsonl

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_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

Available Tools

21 tools
calendar_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_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.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers