Skip to main content
Glama
outlook-mcp

outlook-mcp

by mpalermiti

outlook-mcp

MCP server for Microsoft Outlook personal accounts via Microsoft Graph API.

PyPI Python License: MIT MCP Registry

Personal Microsoft accounts only — @outlook.com, @hotmail.com, @live.com. Work/school accounts (Entra ID) are not supported: the server is built and tested on personal accounts. Fixes that make a tool behave on a work account, without changing what a personal account sees, are welcome.

Disclaimer: Independent open-source project. Not affiliated with, endorsed by, or supported by Microsoft Corporation. "Outlook" and "Microsoft Graph" are trademarks of Microsoft.

On a Mac and seeing "Not authenticated"? Upgrade to 1.32.0, then run outlook-mcp status. On Oct 26, 2026, an update to the Microsoft sign-in library outlook-mcp uses changed where your sign-in is kept in the Keychain, so installs and upgrades from that day couldn't find it. 1.32.0 looks in the original place again. What happened and what to do.


Who this is for

You'll like this if you're:

  • An agent builder wiring Outlook into your own infra (OpenClaw, Claude Code, Cursor, custom MCP host) and want a typed tool surface — not stdout you have to parse

  • Building on personal Microsoft accounts (Outlook.com / Hotmail / Live) and want full control: BYO Azure app, no enterprise consent flow, no shared client ID

  • Looking for real coverage — mail, calendar, contacts, to-do, drafts, folders, batch ops, threading — instead of a mail-only or calendar-only wrapper

  • Security-conscious: tokens in the OS keyring (Keychain on macOS, libsecret on Linux -- never cleartext unless you opt in), granular allow_categories, optional read_only mode, zero telemetry

This isn't for you if you need work/school M365 accounts (use Microsoft's official tooling — Entra ID auth and admin-consent flows are out of scope here), or if a basic mail-only client would suffice (this has 78 tools — way more than you need for "read my inbox").

How it differs from other Outlook tools you'll find

This is the only first-class MCP server in the personal-Outlook space — most alternatives are bash scripts or skill-shaped CLI wrappers the agent shells out to. That distinction matters: the agent gets typed tool schemas with structured args/returns, not stdout it has to parse. Other things you won't find elsewhere: /$batch-optimized triage (10-20× faster on bulk ops), recursive folder ops with name resolution, granular per-category permissions, multiple mailboxes (one server per account via OUTLOOK_MCP_CONFIG_DIR), and full attachment write paths including >3MB upload sessions for drafts and calendar events.


Related MCP server: mega-outlook-mcp

What This Enables

Give your AI agent full Outlook access. Example prompts that just work:

  • "Summarize my unread email from the past 24 hours and flag anything time-sensitive."

  • "What's in my Focused Inbox right now? Anything in Other that looks like it belongs up top?"

  • "Any shipping updates in my inbox? Track what I'm waiting on and when it's supposed to arrive."

  • "Scan my email for upcoming subscription renewals — what's about to auto-charge in the next two weeks?"

  • "I've got a trip to Seattle next week — check my calendar for the itinerary and create a To Do task with a packing checklist."

  • "Draft a reply to the last message from my sister saying I'll call her this weekend."

  • "Move all newsletter and promotional email from this week to a 'Read Later' folder — batch 20 at a time."

The server exposes 78 discrete tools (71 load by default; the four rule tools, document reader, MIME export and contact photo tool are opt-in) so the agent can compose its own workflow — read, triage, write, schedule, track tasks — without hardcoded macros.

Works With

Listed on the official MCP Registry as io.github.mpalermiti/outlook-mcp.


What's new

The last few releases, in brief. Every change is in the CHANGELOG.

  • To Do time zones (1.33): a task's due date, reminder and repeat rule use your configured time zone instead of UTC, so a task lands on the day you meant. due also takes +7d or now.

  • Contact photos (1.33): set or replace a contact's photo from a JPEG, PNG or GIF file. Off unless you turn it on.

  • Relative event times (1.32): an event's start and end take +2h, now or 7d, like every other date, and the reply shows the time each became.

  • Online meetings (1.32): outlook_update_event can add an online meeting to an existing event. Some personal accounts ignore is_online, so the reply says whether it took.

  • Repeating tasks (1.32): moving a repeating task's due date is refused, because Microsoft would leave a duplicate task. Change it in the To Do app.

  • Mac sign-in fixed (1.32): from Oct 26, a Microsoft library update made outlook-mcp look for your sign-in in the wrong Keychain entry and report "Not authenticated". 1.32 reads the original entry again. After upgrading, run outlook-mcp status, and if it still says not authenticated, run outlook-mcp auth once (what happened).

  • Safer by default (1.31.3–1.31.4): downloads never overwrite a file, writing into a calendar or task list someone else owns needs send permission like an invitation, attachment text is read only in standard character sets, and a config that points the attachments folder at your home folder, under any of its names, is refused. A reply or forward that fails says whether anything was sent (1.31.4).

  • Export an email (1.31): get a message's original file exactly as it arrived, attachments included, up to 10 MB. Off unless you turn it on.

  • Inbox rules (1.30): list, create, change and delete server-side inbox rules, and see what each rule leaves out (1.30.2). Off unless you turn it on, and a rule that forwards mail also needs send permission.

  • Calendar (1.27–1.29): turn a meeting invitation into its calendar event, attach files to events, tag an event so you can find it again, create events in any of your calendars, and see who owns each calendar.

  • Remote clients (1.27–1.28): an optional HTTP mode serves a client on another machine and refuses to start without a token. Downloads can come back in the reply instead of as a file on the server.

  • Safer sends (1.27–1.28): a send that times out is never sent twice on its own, and a large attachment that fails to upload no longer lets the mail go without it.

  • Accounts and settings (1.29): pin a server to one sign-in, and set options from environment variables, which can only tighten security.

  • Cheaper every turn (1.29): the tool list every client reads on each turn is a quarter smaller, and features that would add to it are off by default.


Features

78 tools across 14 categories. 71 load by default; the four rule tools, document reader, MIME export and contact photo tool are opt-in groups (see Toolset selection).

  • Auth (1) -- auth status check (login is via CLI)

  • Mail Read (8) -- list inbox (with Focused Inbox and uncategorized filters), read message, opt-in original MIME export, bulk read by ID via $batch, search (KQL), list folders, delta-sync inbox changes, composed "since last call" digest across mail/events/contacts

  • Mail Write (3) -- send, reply/reply-all, forward

  • Mail Triage (9) -- move, delete (soft by default), flag, categorize, mark read/unread, reclassify (Focused Inbox), list/set/delete per-sender Focused Inbox overrides

  • Mail Rules (4) -- list rules in execution order, create from sender/subject/body conditions, update (reads the rule first, so other actions survive a re-point), delete — opt-in toolset group

  • Calendar Read (4) -- list events (with recurring expansion), get event details, find events by key, delta-sync event changes

  • Calendar Write (6) -- create, update, delete, RSVP (accept/decline/tentative), attach and remove event files

  • Contacts (8) -- list, search, get, create, update, delete, delta-sync changes, set a contact's photo (opt-in)

  • To Do (14) -- task lists, tasks (list/get/create/update/complete/delete), checklist items (add/update/delete), task attachments (list/download/upload/delete)

  • Drafts (5) -- list, create (new, or a reply, reply-all or forward in the message's thread), update, send, delete

  • Attachments (6) -- list, download, read document text (opt-in), send-with-attachments, attach-to-draft, remove-draft-attachment

  • Folder Management (3) -- create, rename, delete mail folders

  • Threading and Batch (3) -- list thread, copy message, batch triage

  • User and Admin (4) -- whoami, list calendars, list categories, mail tips

Design principles:

  • BYOID -- Bring Your Own ID. You register your own Azure AD app. No shared client ID.

  • Zero telemetry -- no analytics, no local caching, no third-party calls.

  • Token storage -- OS keyring via azure-identity (macOS Keychain, Windows Credential Store, Linux Secret Service).

  • Input validation -- all inputs validated (email, Graph IDs, OData, KQL, datetimes) before any API call.

  • Read-only mode -- set read_only: true in config to block all write operations. Note this limits the tools, not the token -- see What read_only does and does not do.

  • Soft delete -- delete moves to Deleted Items by default. Hard delete requires explicit permanent: true.

  • Timezone-aware -- calendar operations respect your configured IANA timezone.

  • Relative dates -- every datetime parameter takes ISO 8601 or an offset: 7d is seven days ago, +7d is seven days from now, now is this moment. Units: m, h, d, w.

  • Bounded attachments -- attachment reads and writes are confined to attachments_dir, so a message that asks an agent to mail a file elsewhere on disk cannot be obeyed.

  • Bounded delta cursors -- a delta_token is caller-held state, so it is untrusted input. Every URL that would carry a Graph bearer token is parsed and required to be https on graph.microsoft.com, which is what stops a poisoned cursor from redirecting your mailbox token to someone else. Its path must also be the delta endpoint of the tool it was handed to, so a cursor cannot point a delta tool at some other part of the mailbox.

  • Workflow prompts -- morning_brief, triage_folder and catch_up ship as MCP prompts, so the common sequences do not have to be reconstructed call by call.

Agent-friendly shape (1.8.0)

Two pure-code upgrades that make the tools cheaper and more recoverable for AI agents:

  • Concise mode — pass concise=True to the six high-volume read tools (outlook_list_inbox, outlook_read_message, outlook_read_messages, outlook_search_mail, outlook_list_events, outlook_list_thread) to drop bulky fields: full message bodies, quoted prior-message text in threads, body previews and categories on inbox listings — typical payload reduction ~10×. On outlook_list_events the trade is different and smaller: organizer, response_status, type, show_as and key come off, is_organizer and attendees_count are added, and is_online is spelled is_online_meeting, so a concise scan cannot tell a recurring occurrence from a one-off. Default concise=False preserves the existing response shape — strict backward compat.

  • Structured Graph errors — every tool turns msgraph SDK exceptions into a tool error whose text carries Graph's message and a recovery hint: re-auth on 401, a link to the repo's ROADMAP dead-ends list on 403/ErrorAccessDenied, re-list on 404/ErrorItemNotFound, back-off on 429, retry on 503 — except on the tools that can email someone (mail, invitations, event updates, RSVPs), where a 5xx says the write may already have gone through and where to check, because those writes are never re-sent after one. OutlookMCPError subclasses and validation errors pass through unchanged.


Azure AD App Registration

You need to register a free Azure AD app to get a client ID.

Prerequisites (Personal Microsoft Accounts)

Microsoft has deprecated app registration for personal accounts without an Azure AD tenant. You need to create a free Azure account first:

  1. Go to azure.microsoft.com/free and sign up with your personal @outlook.com account. Requires a credit card for identity verification but won't charge you. This creates a proper Azure AD tenant.

Register the App

  1. Go to App Registrations and sign in with your @outlook.com account.

  2. Click "+ New registration" and fill in:

    • Name: anything except Microsoft-branded terms (e.g. mp-outlook-mcp — names like "Outlook MCP" will be rejected)

    • Supported account types: select "Personal Microsoft accounts only"

    • Redirect URI: leave blank

  3. Click Register. Copy the Application (client) ID from the overview page.

  4. Go to Authentication (Preview) → Settings tab → toggle "Allow public client flows" to Yes → Save.

  5. Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions → add:

    • Mail.ReadWrite, Mail.Send

    • Calendars.ReadWrite

    • Contacts.ReadWrite, Tasks.ReadWrite

    • MailboxSettings.Read

    • User.Read, offline_access

No client secret is needed. The device code flow uses public client auth.


Quick Start

Install

Option A — from PyPI (recommended):

uv tool install outlook-graph-mcp
# or: pipx install outlook-graph-mcp
# or: pip install outlook-graph-mcp

To read PDF and XLSX attachments as text, install the optional documents extra instead (uv tool install 'outlook-graph-mcp[documents]') and enable the opt-in documents group; see Attachments.

Option B — from source:

git clone https://github.com/mpalermiti/outlook-mcp.git
cd outlook-mcp
uv sync

Configure

Create ~/.outlook-mcp/config.json:

{
  "client_id": "YOUR_APPLICATION_CLIENT_ID",
  "tenant_id": "consumers",
  "timezone": "America/Los_Angeles",
  "read_only": true,
  "attachments_dir": "~/.outlook-mcp/attachments"
}

The only required field is client_id. Everything else has sensible defaults. Start with read_only: true — flip to false when you're comfortable.

Register with your MCP client

If installed from PyPI:

{
  "mcpServers": {
    "outlook": {
      "command": "outlook-mcp"
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "outlook": {
      "command": "uv",
      "args": ["--directory", "/path/to/outlook-mcp", "run", "outlook-mcp"]
    }
  }
}

For OpenClaw, use the openclaw mcp CLI — it writes to mcp.servers in ~/.openclaw/openclaw.json for you:

# If installed from PyPI:
openclaw mcp set outlook '{"command":"outlook-mcp"}'

# If installed from source:
openclaw mcp set outlook '{"command":"uv","args":["--directory","/path/to/outlook-mcp","run","outlook-mcp"]}'

# Verify:
openclaw mcp list
openclaw mcp show outlook --json

Restart the OpenClaw gateway after registering. See the OpenClaw MCP docs for SSE/HTTP transport variants.

Authenticate

Run this once on the machine where the MCP server will run:

outlook-mcp auth          # installed from PyPI
uv run outlook-mcp auth   # from a source checkout

You'll get a URL and a code. Open the URL in any browser, enter the code, and sign in with your Microsoft account. Tokens are cached in the OS keyring — the MCP server picks them up automatically.

The consent screen lists the full read-write set (Mail.ReadWrite, Mail.Send, Calendars.ReadWrite, Contacts.ReadWrite, Tasks.ReadWrite, MailboxSettings.Read, User.Read) — with mailbox_settings_write: true the settings scope becomes MailboxSettings.ReadWrite — even when the config starts with read_only: true, because read_only gates the tools, not the token (see What read_only does and does not do), and the scopes a first consent leaves out can never be granted later without logging in again. (The one exception is read_only_consent: true, which asks for the read permissions only; it exists for a separate read-only app, described under the same heading.) Every request afterwards — silent refresh and each Graph call — uses the .default scope, which on an already-consented account means exactly "the set you granted". That ordering is deliberate: on personal accounts a first consent asking only for .default can land a session with no delegated permissions, which then can't be redeemed (AADSTS70000) without logging in again (#82).

Other CLI commands (prefix uv run from a source checkout):

outlook-mcp status   # Check auth status
outlook-mcp logout   # Remove this instance's auth record (the OS token cache is left to age out)
outlook-mcp serve    # Start MCP server (default; stdio, or HTTP with OUTLOOK_MCP_TRANSPORT)

Troubleshooting

"Not authenticated" after upgrading (macOS)

What happened. outlook-mcp keeps your Microsoft sign-in in the Mac Keychain, through azure-identity, Microsoft's sign-in library. Version 1.27 of that library, released on Oct 26, 2026, saves sign-ins under a different Keychain entry. outlook-mcp 1.31.4 and earlier accepted any newer version of the library, so an install or upgrade from Oct 26 on picked up 1.27. It then looked in the new entry, found nothing, and reported "Not authenticated", although your sign-in was still in the Keychain.

The fix. 1.32.0 keeps the library below 1.27, so outlook-mcp reads the original entry again. Only Macs were affected.

What to do.

uv tool upgrade outlook-graph-mcp    # or: pipx upgrade outlook-graph-mcp
outlook-mcp status

If it says authenticated, you're done. If it says not authenticated, run outlook-mcp auth once. That happens when you signed in again after Oct 26, often to get past this problem: that sign-in went to the new entry, which 1.32.0 doesn't read.

Next. #244 tracks reading a sign-in from either entry and moving it across, so the library can be updated again without signing anyone out.

me-token-to-replace is invalid on every call

You're on 1.22.0 installed after 2026-09-18. A fresh install of that version resolves microsoft-kiota-* 1.13 or later, which msgraph-core 1.5.1 doesn't handle, so every /me request reaches Graph as /users/me-token-to-replace. Fixed in 1.22.1, which caps kiota below 1.13 (#80). In 1.26.0 that cap is replaced by a msgraph-core>=1.5.2 floor, which carries the fix and works with kiota 1.13+:

uv tool upgrade outlook-graph-mcp
# or: pipx upgrade outlook-graph-mcp
# or: pip install --upgrade outlook-graph-mcp

Your config and sign-in are untouched; no re-auth needed.

SSL: CERTIFICATE_VERIFY_FAILED on Linux

If auth fails with [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate, your Python environment can't find the system CA bundle. This is common on minimal/container Linux images and with the isolated venv from uv tool install.

Point Python at your system CA bundle. Set both variables — auth (via azure-identity → requests) reads REQUESTS_CA_BUNDLE, while the delta/$batch paths (via httpx) read SSL_CERT_FILE:

export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt      # httpx + Python ssl
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt  # azure-identity auth

The path varies by distro: Debian/Ubuntu use /etc/ssl/certs/ca-certificates.crt; RHEL/Fedora use /etc/pki/tls/certs/ca-bundle.crt. If the file is missing, install your distro's CA package (ca-certificates). Set these in the same environment your MCP client launches the server from so they apply at runtime, not just to the one-time auth command.

Token cache stored unencrypted (Linux)

On Linux without an encrypted store (libsecret/PyGObject not importable, or no running Secret Service), outlook-mcp auth and the server refuse to write the token cache in cleartext, and every tool call says why. Install the system packages for an encrypted store — see Privacy and Security — or set allow_unencrypted_token_cache: true to accept a plaintext cache file, after which the server logs a one-time warning at startup.


Tool Reference

Dates. Every datetime parameter (after, before, start, end, due, deferred_send_datetime) accepts ISO 8601 — 2026-10-22 or 2026-10-22T14:30:00Z — or a relative offset: 7d is seven days ago, +7d is seven days from now, and now is this moment. Units are m, h, d, w. Bare means ago, matching the usual CLI convention, so a due date in the future needs the +. Zone-less input is interpreted in your configured timezone; responses are UTC, except a To Do task's due, which comes with its zone in due_time_zone: some accounts store a repeating task's due in the zone it was sent in, others in UTC.

Folders. Every folder argument, outlook_create_folder's parent_folder and outlook_batch_triage's move target take a well-known name (inbox, junkemail), a display name (Junk Email), a Graph ID, or a path: Inbox/Travel/Flights is Flights under Travel under Inbox. A / inside a folder's own name is written // (Inbox/Q1//Q2). A display name finds a top-level folder of that name first; a name that several nested folders share is refused, and the error lists their paths. outlook_rename_folder and outlook_delete_folder take an ID.

Auth

Tool

Description

outlook_auth_status

Check if authenticated and whether read-only mode is active.

Note: Authentication is handled via the CLI (outlook-mcp auth), not through MCP tools. See Authenticate above.

Mail Read

Tool

Description

outlook_list_inbox

List messages in a folder. folder accepts display names, well-known names, paths (Inbox/Travel/Flights), or Graph IDs. Filter by read status, sender, date range, Focused Inbox classification, or no categories (uncategorized_only). Pagination via cursor (or skip).

outlook_read_message

Get full message by ID, or by its Message-ID header value (<abc@example.com>, matched exactly; the response's id is the Graph ID the other tools take). Format: text (Graph's plain-text rendering), html, or full — the stored body, usually HTML, in both body and body_html; read text for plain text. Pass include_deferred_send=True to also surface the draft's scheduled delivery time. Pass include_sender_auth=True to add sender_authentication, Microsoft's verdict on the From domain: authenticated, from_domain, the dkim, dmarc and compauth results, and a short reason. Only Microsoft's own topmost Authentication-Results header counts, and authenticated is true only for a pass aligned with the From domain. It vouches for from_domain only, never for the display name, and false means unverified, not spoofed.

outlook_read_messages

Bulk read up to 20 messages by ID via Graph $batch in one round-trip. Per-message shape matches outlook_read_message byte-for-byte for the same (format, concise, include_deferred_send, include_sender_auth). Partial-failure tolerant: 404s on some IDs surface in failures[] without failing the whole call. Use NOT N outlook_read_message calls.

outlook_search_mail

Search mail using KQL query. Optionally scope to a folder by name, path or ID. A cursor continues the search in the folder it started in. Graph has been seen to end a search a little past 250 results without saying so (255–275 on Exchange Online; 275 also observed on Outlook.com), so a last page past 250 carries incomplete, a note that older matches may be missing and how to reach them.

outlook_list_folders

List mail folders with counts, parent_id, and child_count. Pass recursive=true to walk the full folder tree (subfolders included); each folder then carries its path, the form every folder argument accepts.

outlook_list_inbox_delta

List only inbox changes since the last call. folder (default inbox) takes a name, path or ID. First call returns a full snapshot plus a delta_token; subsequent calls (token passed back) return only added/updated/deleted items. Deletes come back as {id, is_deleted: True}. Cursor is stateless — agent persists and replays.

outlook_changes_since

One structured "since last call" digest composing mail/events/contacts deltas. Returns counts + urgent_flagged mail + top-5 by_sender + new/cancelled events. Each resource has an independent delta_token; stale-token recovery (HTTP 410) auto-resyncs that resource and surfaces _meta.resync. The first call covers the last fallback_window_hours (default 24): Mail requests Graph's received-time filter and enforces it client-side when ignored (_meta.mail_window_fallback); contacts are kept by last-modified time, and events by the calendar view (the window plus the next 7 days). Where Graph honours the mail filter, later calls keep it: mail received before the window reports only deletes, moves out of the inbox and read/unread changes, not new flags or categories. has_more names any resource the per-call cap stopped mid-sync; replace the stored delta_tokens dictionary with the returned one and pass it back; do not merge the dictionaries. It keeps mail_bootstrap_from while a mail bootstrap is unfinished, so continuation keeps the original bound and reports it in window.from. A reply with no new cursor hands back the token passed in. Designed for recurring agent loops.

outlook_export_message

Opt-in (mime group). Export original MIME by Graph message ID as a message/rfc822 resource blob after JSON metadata (size_bytes, sha256); read-only, bounded to 10 MiB.

Original MIME export uses the existing sign-in and needs no additional scope or package. Enable it with OUTLOOK_MCP_TOOLSETS=mail,mime (plus any other groups you need) and restart. It preserves the original bytes, including attachments; it does not parse or rewrite them. The result contains a small JSON metadata block followed by an embedded resource with a base64 blob, never decoded text. Messages larger than 10 MiB are refused while streaming. A throttled request (HTTP 429) returns an error; bulk exporters must pace their calls and handle throttling rather than relying on automatic retries.

Mail Write

Tool

Description

outlook_send_message

Send email. Supports TO/CC/BCC, HTML or Markdown body, importance level, reply_to and a read receipt (request_read_receipt).

outlook_reply

Reply or reply-all to a message, the text above the quoted original. Plain text keeps its paragraphs, line breaks and - lists; a plain-text thread gets a plain-text reply.

outlook_forward

Forward a message to one or more recipients with optional comment, which keeps its line breaks like a reply's text.

Bodies are plain text unless is_html=True (HTML, sent as written) or is_markdown=True. Markdown is converted to HTML for a safe subset: paragraphs, line breaks, -/*/+ and numbered lists, **bold**, *italic*, `code`, and [text](url) links to https: and mailto: addresses only. An image, ![alt](url), becomes a link to it, never an embedded picture. Everything else, raw HTML included, is shown as written. outlook_send_message, outlook_reply, outlook_forward (its comment), outlook_create_draft and outlook_update_draft take it; on a plain-text thread a Markdown reply is sent as written, as plain text.

Mail Triage

Tool

Description

outlook_move_message

Move a message to a folder by name, path or ID.

outlook_delete_message

Delete a message. Soft delete (Deleted Items) by default. permanent: true for hard delete.

outlook_flag_message

Set follow-up flag: flagged, complete, or notFlagged.

outlook_categorize_message

Set categories on a message.

outlook_mark_read

Mark a message as read or unread.

outlook_reclassify_message

Move a message between Focused Inbox and Other (focused / other).

outlook_list_inbox_overrides

List Focused Inbox per-sender override rules.

outlook_set_inbox_override

Upsert a per-sender Focused Inbox override (focused / other). Case-insensitive sender matching; PATCH-if-exists, else POST.

outlook_delete_inbox_override

Delete a Focused Inbox override by ID.

Mail Rules

Server-side rules: they run whether or not any Outlook client is open. A rule is durable, not a one-off — create one and it keeps applying to all future mail long after the agent that made it has disconnected. That is what makes rules useful, and it is also why outlook_create_rule and outlook_update_rule are annotated destructive — re-enabling one resumes whatever it does — and why forward_to, and re-enabling a rule that forwards or redirects, additionally require the mail_send category: a forwarding rule keeps mailing a third party after the session ends, which is the standard way a compromised mailbox gets drained. Hard delete is not offered here — delete moves matching mail to Deleted Items, which is recoverable. The same mail_send gate covers the indirect routes to a forwarding rule starting work: reordering one, or disabling, reordering or deleting a stop_processing_rules or permanentDelete rule that was hiding it — permanentDelete removes the message before later rules see it. Repairing an errored forwarding rule needs mail_send too: the repair puts it back into service. And a listing that stopped early (complete: false) counts as "cannot tell", so it gates the same way rather than assuming nothing is hidden. A rule that never runs until the rule above it changes is still a rule that forwards mail.

Tool

Description

outlook_list_rules

List inbox rules in execution order, with conditions, exceptions and actions, and whether Exchange reports an error applying the rule.

outlook_create_rule

Create a rule from sender/subject/body/attachment conditions and move, copy, mark-read, delete, forward, categorize or stop-processing actions.

outlook_update_rule

Change a rule's name, enabled state, sequence, target folder or mark-read action. Other actions are preserved; re-enabling a rule that forwards or redirects needs mail_send.

outlook_delete_rule

Delete a rule by ID. Irreversible.

The three write tools are gated by the mail_rules permission category — add it to allow_categories (or leave allow_categories unset for a full read-write install).

The four rule tools are opt-in, off in a stock install: with OUTLOOK_MCP_TOOLSETS unset none of them is loaded — not even outlook_list_rules — and the surface every user pays for is unchanged. Name rules in OUTLOOK_MCP_TOOLSETS to load them, or set mailbox_settings_write: true, which adds them only when OUTLOOK_MCP_TOOLSETS is unset — an explicit selection is what you asked for, so it wins.

A rule hides as well as forwards, and the hiding needs no permission beyond mail_rules: a rule at sequence 1 that deletes, marks read and stops processing on "security", "sign-in" or "password" removes that mail before any later rule sees it. Read the rules of a mailbox you did not configure before trusting what it shows you.

Not every personal mailbox allows rules. One answered all four operations; another refused even a plain listing with 403, though its token reads categories under the same MailboxSettings.Read scope. A refused listing says it is either the consent or the mailbox. If a fresh sign-in does not change it, rules cannot be managed there.

Order is Graph's to set. On a live personal mailbox, sequence was ignored on both create and update: a rule created at sequence 500 and then patched to 500 stayed at the sequence Graph had assigned (128 of 127). The tools accept the field because Graph's schema does, and they return the sequence Graph actually stored — treat that returned value as authoritative, not the one you asked for. When the two differ, the reply also carries sequence_requested, so an ignored request is visible. The ordering and tie logic in the mail_send gate is defensive against a listing that reports equal or missing sequences, not something this API was observed to produce.

Creating, updating or deleting a rule also needs MailboxSettings.ReadWrite on the token. The default read-write consent set requests MailboxSettings.Read only, so the write tools answer ErrorAccessDenied until the token carries the scope. To enable the write tools:

  1. Ask for the write scope at sign-in. Set mailbox_settings_write: true in your config. The default read-write consent asks for MailboxSettings.Read only, so without this every rule write answers ErrorAccessDenied no matter what the app registration allows.

  2. Re-run outlook-mcp auth. Consent is granted per requested scope and an existing token keeps the scopes it was issued with, so the new scope only lands on a fresh consent.

  3. Restart the server. Tools are chosen when the process starts, so the rule tools appear only after a restart — a config change mid-session does nothing to the surface, and the write scope alone does not add them.

  4. If your tenant restricts it, add MailboxSettings.ReadWrite (delegated, Microsoft Graph) to the app registration in the Azure portal and grant admin consent before step 2. A personal account does not need this.

outlook_mcp cannot detect a half-configured setup: a token without the scope authenticates fine and reads keep working, and every rule write fails at Microsoft's end with ErrorAccessDenied. If rule writes fail while outlook_list_rules works, the scope is the cause.

Calendar Read

Tool

Description

outlook_list_events

List events in a date range. Expands recurring events. Each event carries type — occurrence or exception for an instance of a series, singleInstance for a one-off — so a listing tells recurring work apart without a second call. A seriesMaster never appears here: calendarView returns expanded instances, so use outlook_get_event to see a master. Each event also carries show_as, the free/busy status Outlook labels "Show as". Configurable via days, after, before. calendar selects which calendar to read: omit (or "primary") for the default, otherwise a display name (case-insensitive; not-found and ambiguous errors name what exists) or an ID from outlook_list_calendars. A cursor continues the listing it came from, so later pages need neither calendar nor a second lookup. An event that has a key (see outlook_create_event) carries it; one without has no key field. concise=True omits type, show_as and key.

outlook_get_event

Get full event details: attendees, body, online meeting URL, recurrence, type (singleInstance / seriesMaster / occurrence / exception), show_as, key (null when the event has none), and attachments — id, name, size, content_type and is_inline of each file, never its bytes ([] when there are none; read with a second request only when Graph reports the event has attachments). Pass either event_id or an invitation's message_id to resolve the exact event in your calendar (never by subject). Returns current details and invitation staleness, plus nullable is_organizer, allow_new_time_proposals, is_cancelled and attendee proposed_new_time slots with their zones. Missing metadata stays null; organizer status is relative to the calendar owner.

outlook_find_event_by_key

Find the events whose key is the one given — the caller's own reference set by outlook_create_event or outlook_update_event. No date window: a booking months away is found as readily as tomorrow's. Searches the default calendar, or calendar (resolved as for outlook_list_events). Returns events in the default listing's shape, key included: single events and series masters, never occurrences, so the ID found is the one to update. Nothing matching returns an empty list; has_more is true when more than 25 events share the key.

outlook_list_events_delta

List only event changes inside a window since the last call. start and end (ISO 8601) required on the first call (Graph constraint — no whole-calendar sync). Each changed event carries every field the default outlook_list_events listing returns except key, type and show_as included, plus is_deleted (concise=True has its own narrower shape, which the delta tool does not mirror). Unlike the listing, this endpoint does return seriesMaster items, so a caller seeding from outlook_list_events should expect ids here that the seed never held. Deletes come back as {id, is_deleted: True} and nothing else. Cursor is stateless.

Calendar Write

Tool

Description

outlook_create_event

Create event with location and attendees. start/end may be relative (+2h, now); the result then shows the time each became, in the event's zone. is_online=True adds an online meeting; it may have no effect on some personal accounts, so the result carries is_online as Graph reported it (omitted if Graph's reply has no such field — read the event back). Pass recurrence to create a series: a shorthand (daily, weekdays, weekly, monthly, yearly, anchored on start) or a full Graph recurrence object for anything else. range.startDate defaults to the event's start date. timezone (an IANA name such as America/Los_Angeles, never an abbreviation) is the zone the event is anchored in and a series is expanded in; omit it for the config timezone. show_as sets the free/busy status Outlook labels "Show as" — free, tentative, busy, oof (out of office), workingElsewhere, or unknown; omit it and Graph applies its own default of busy. calendar creates it in another calendar, resolved as outlook_list_events resolves it: omit (or "primary") for the default, otherwise a display name or an ID from outlook_list_calendars. A calendar Graph lists as read-only (canEdit: false) is refused before anything is sent. The tools that take an event ID need no calendar: an ID reaches an event on any of your own calendars. key stores your own reference for the event (a booking number, say: 1–128 letters, digits and . _ : @ -) in a hidden extended property, so outlook_find_event_by_key can find the event again when a change to the same booking arrives. Nothing stops two events sharing a key; look it up before creating.

outlook_update_event

Update event fields (subject, time, location, body, attendees, all-day, show_as). Only patches changed fields. A relative start/end (+2h, now) is placed in the event's own zone and shown in the result. Pass recurrence to turn a single event into a series, or remove_recurrence=True to turn a series back into a single event. attendees replaces the whole guest list and emails invitations/cancellations; is_all_day needs start+end in the same call, while show_as patches on its own. Patching a time keeps the zone the event is anchored in; timezone (with start+end) re-anchors it elsewhere, which is how a series created before zones existed gets repaired. A start, end or recurrence patch to a series with edited or deleted occurrences is refused, naming them — Graph would silently discard every one. key sets or replaces the event's key and patches on its own; there is no clearing one. is_online=True adds an online meeting and reports is_online as on create; is_online=False is refused, because Graph accepts it and keeps the meeting.

outlook_delete_event

Delete a calendar event.

outlook_rsvp

RSVP to an event: accept, decline, or tentative. Optionally include a message.

outlook_attach_to_event

Attach files to an event — an e-ticket on a flight, say. attachment_paths resolve inside attachments_dir, as for outlook_attach_to_draft; a missing file, or one path outside it, attaches nothing. Files over 3 MB use an upload session; a chunk Graph refuses, or an upload it does not report complete, stops the call with an error rather than reporting the file attached. Returns the new attachment IDs (none yet for an upload-session file). Attendees are not sent the files when they are attached; they get them with the event's next update, so on an event with attendees this needs mail_send under a restricted allow_categories.

outlook_remove_event_attachment

Remove one attachment from an event, by the ID outlook_attach_to_event returned or outlook_get_event lists.

Contacts

Tool

Description

outlook_list_contacts

List contacts with cursor pagination. Summaries carry categories; outlook_search_contacts omits the key because Graph's $search does not return it.

outlook_search_contacts

Search contacts by name or email. phone, instead of query, finds a number however it is written: with or without its country code, a leading 00 or trunk 0, spaces or dashes, from at least its last seven digits. Graph's contact $search finds a number only as it is stored, and phone fields can't be filtered, so a phone search reads the contact listing (pages of 1,000, up to 10,000 contacts) and compares digits. has_more is true when there were more matches than count, or contacts past the 10,000th.

outlook_get_contact

Get full contact details by ID, including middle_name, job_title, birthday, home/business/other addresses, categories and personal notes.

outlook_create_contact

Create a new contact. title is the name prefix ("Dr.", "Ms."), which Outlook shows in the display name; the job goes in job_title. phone_type (mobile, the default, business or home) says which kind of number phone is. birthday is a date (YYYY-MM-DD), stored at 11:59 UTC so that it is the same date in every time zone from UTC−11 to UTC+12; outlook_get_contact returns that timestamp. middle_name, personal_notes and categories are set as given.

outlook_update_contact

Update contact fields, including middle_name, company, title, job_title and personal_notes. A text field passed as "" is cleared. categories replaces the contact's whole list, as outlook_categorize_message does a message's, so [] removes every category; read the contact first to add one. phone_type works as on create; a business or home number replaces that list of numbers with the one given. clear_phones empties the types it names, so phone_type="business", clear_phones=["mobile"] moves a number saved as mobile to business in one update. home_address, business_address and other_address take the shape outlook_get_contact returns — any subset of street, city, state, postal_code, country_or_region — and replace that whole address, so pass back every part you want to keep. Omit one to leave it untouched. birthday sets or replaces the date, as on create. email replaces every address with the one given; add_emails and remove_emails change only the addresses they name, keeping the rest (a contact holds three at most). They are merged with what the contact holds now, and the update is pinned to that read with If-Match, so an edit made in between is refused with 412 rather than overwritten. Removing an address the contact doesn't have is refused.

outlook_delete_contact

Delete a contact.

outlook_set_contact_photo

Opt-in (contact_photos group). Set or replace a contact's photo from a JPEG, PNG or GIF file. file_path resolves inside attachments_dir, as for outlook_attach_to_draft. The type is read from the file's bytes, not its name. A file over this server's 20 MiB limit, an empty one or another format is refused before anything is sent. Outlook may re-encode the image (it kept PNG and GIF uploads as JPEG), and Graph's own size limit still applies. Returns uploaded_bytes. Needs contacts_write.

outlook_list_contacts_delta

List only contact changes since the last call. Deletes come back as {id, is_deleted: True}. Cursor is stateless.

To Do

Tool

Description

outlook_list_task_lists

List To Do lists, with is_owner and is_shared so a list someone else owns is visible.

outlook_list_tasks

List tasks with status filter and pagination.

outlook_get_task

Get full task details: notes (body), checklist items (ordered unchecked-first), due and its zone, recurrence flag.

outlook_create_task

Create task with due date, importance, recurrence.

outlook_update_task

Update a task's title, due date, notes or importance. A repeating task's due date can't be changed here, because Microsoft would leave a duplicate task; change it in the To Do app.

outlook_complete_task

Mark task as completed.

outlook_delete_task

Delete a task.

outlook_add_checklist_item

Add a checklist item (sub-step) to a task.

outlook_update_checklist_item

Update a checklist item — mark done (is_checked) or rename (partial patch).

outlook_delete_checklist_item

Delete a checklist item from a task.

outlook_list_task_attachments

List attachments on a To Do task (id, name, size, content_type) with pagination.

outlook_download_task_attachment

Download a task attachment's content to a local file (confined to attachments_dir), or return it with as_content=True. Never replaces an existing file and never creates a hidden (dot) name or writes into a hidden folder; pick a new save_path.

outlook_upload_task_attachment

Attach a local file (from attachments_dir) to a task via inline base64 POST (1 byte – 20 MiB).

outlook_delete_task_attachment

Remove an attachment from a To Do task.

Drafts

Tool

Description

outlook_list_drafts

List draft messages with pagination.

outlook_create_draft

Create a draft, with an HTML (is_html=True) or Markdown (is_markdown=True) body if wanted. With reply_to_message_id (reply_all=True for reply-all) or forward_message_id, the draft is created in that message's thread with the original quoted below, and nothing is sent; Graph fills a reply's recipients and subject, and a forward needs to. Supports scheduled delivery via deferred_send_datetime (server-side, Outlook-desktop-compatible "Delay Delivery").

outlook_update_draft

Update draft fields. Accepts is_html=True for HTML bodies, is_markdown=True for Markdown ones, and deferred_send_datetime to set or clear the scheduled delivery time.

outlook_send_draft

Send an existing draft.

outlook_delete_draft

Delete a draft.

Attachments

Since 1.20.0, these tools only reach attachments_dir (default ~/.outlook-mcp/attachments). A bare filename resolves inside it; a path outside it is refused, including via a symlink. To email a file, move it there first — or widen attachments_dir, understanding that anything reachable from it can be sent. Before 1.20.0 these tools could read any file the server process could read, which meant an email asking an agent to attach one could be obeyed.

The same fence covers the To Do attachment tools (outlook_upload_task_attachment, outlook_download_task_attachment): uploads read from attachments_dir and downloads write into it, so neither can sweep arbitrary files off disk. (Downloads are not todo_write-gated — they are reads, like outlook_download_attachment; the fence, not the category, is what confines them.)

A client that can't see the server's disk, such as a remote or sandboxed one, can carry the bytes in the call instead, and then nothing is read from or written to disk. as_content=True on either download returns the attachment in the result, up to 10 MB: PNG, JPEG, GIF and WebP up to 5 MB as images, text up to 100,000 characters as text, and anything else, PDFs included, as an embedded resource holding the base64 bytes and their type. An image cut short (a PNG with no end chunk, say) comes back as that resource too. Text that carries control characters, or a lone surrogate its charset decoded to, also comes back as that resource, so it arrives unaltered. attachments on outlook_send_with_attachments and outlook_attach_to_draft takes inline files, [{name, content_base64, content_type?}], up to 3 MB each (Graph's simple-attachment size). The fence still governs every path argument. An inline file is bytes the agent already holds and could already put in a message body, so it widens nothing. outlook_attach_to_event, outlook_upload_task_attachment and outlook_set_contact_photo take paths only.

Tool

Description

outlook_list_attachments

List attachments on a message.

outlook_download_attachment

Download an attachment and save decoded bytes into attachments_dir, or return it with as_content=True. Never replaces an existing file and never creates a hidden (dot) name or writes into a hidden folder; pick a new save_path.

outlook_read_attachment

Opt-in (documents group, not loaded by default; see below). Read PDF pages, XLSX cells/formulas/saved results, or text in a standard text charset (UTF-8 when none is declared); offset / max_chars page the text, no file saved.

outlook_send_with_attachments

Send a message with attachments read from attachments_dir (auto upload session for >3MB) or passed inline in attachments. If a large upload fails, nothing is sent, and the error names the draft left in Drafts so it can be deleted or finished with outlook_attach_to_draft instead of sent twice.

outlook_attach_to_draft

Add attachments from attachments_dir (auto upload session for >3MB) or inline in attachments to an existing draft. A failed large upload is an error, never a file reported as attached. Returns the new attachment IDs (none yet for an upload-session file).

outlook_remove_draft_attachment

Remove a single attachment from a draft.

For readable document contents rather than original bytes, use outlook_read_attachment. The saved path from a download belongs to the server, so a remote client may not be able to open it. as_content=True avoids that path and preserves the original file; the reading tool instead returns extracted text for clients that cannot interpret the embedded binary resource. Existing downloads and their defaults are unchanged.

PDF and XLSX parsing is optional: install outlook-graph-mcp[documents] (for example, uv tool install 'outlook-graph-mcp[documents]', pipx install 'outlook-graph-mcp[documents]', pip install 'outlook-graph-mcp[documents]', or uv sync --extra documents in a source checkout). Enable the opt-in documents group with OUTLOOK_MCP_TOOLSETS=mail,attachments,documents (plus any other groups you need) and restart. Naming groups loads only those, so list every group you want; see Toolset selection. When enabled, a base install can read text in a standard text charset (UTF-8 when none is declared), and returns an installation hint for PDF/XLSX. Parser dependencies have bounded versions and are imported only in a short-lived worker; they add no requirement to the base install.

outlook_read_attachment(message_id, attachment_id, offset=0, max_chars=20000) returns text, next_offset (null at the end), total_chars, file bytes / sha256, and warnings. Continue with the same IDs and the returned offset until null. Each continuation downloads and parses the whole file again, then returns the requested slice; there is no document cache. Use a larger max_chars (up to 50000) to reduce repeated work. PDF output marks page numbers; a page without a text layer is reported as blank or needing OCR. Extracted PDF text lines are prefixed with | , so only the PDF reader can emit an unprefixed [Page N] structural marker in PDF output. This guarantee is PDF-only: XLSX and text chunks can start mid-cell or mid-line, and apparent cell addresses or page markers in their contents are untrusted text. No OCR is performed. XLSX output includes hidden sheets, cell addresses, number formats, formulas and saved_result (Excel's stored value, null when absent). Formulas are not recalculated, and charts/images are not extracted. All attachment contents remain untrusted data.

Worksheet metadata (sheets) is returned only at offset 0, and only when its serialized list plus at least one text character fits max_chars; otherwise the list is omitted and worksheet names remain in the paged text. A workbook above 100 sheets is refused; displayed sheet names are cut to Excel's 31-character limit, with … [N] marking a cut name and its one-based worksheet position so shared prefixes remain distinguishable. Names within the limit are unchanged. max_chars budgets text plus serialized worksheet metadata; the fixed response envelope and bounded warnings are separate. A PDF slice starting mid-line receives a | presentation prefix when it fits. continuation_prefix identifies that prefix: strip it before joining chunks to reconstruct the text. Offsets and total_chars count the canonical text, excluding this presentation prefix.

Reading is limited to 10 MiB of file bytes, 200 PDF pages, 100,000 visited spreadsheet cells, one million extracted characters and 50 MiB / 2,000 entries of expanded XLSX content. max_chars has a ceiling of 50,000. Text is decoded in-process; all extracted text is cleaned of control characters before paging. PDF/XLSX use a subprocess for crash and resource containment, not a sandbox: server credential environment variables are absent, but it runs as the same user with filesystem, network and Keychain access. A parent watchdog polls RSS every 10 ms and kills a parser above 256 MiB on Linux, macOS and Windows; brief overshoot between polls is possible. Only one parser runs at a time, with a 30-second wall timeout. OS resource limits supplement these checks where supported. A limit is an explicit error, never a silently partial document.

Folder Management

Tool

Description

outlook_create_folder

Create mail folder (top-level, or nested under parent_folder: a name, path or ID).

outlook_rename_folder

Rename a mail folder, by ID.

outlook_delete_folder

Delete a mail folder by ID (refuses well-known folders).

Threading and Batch

Tool

Description

outlook_list_thread

Get all messages in a conversation thread.

outlook_copy_message

Copy a message to another folder (name, path or ID).

outlook_batch_triage

Batch move/flag/categorize/mark_read (max 20 per call). Single Graph /$batch round-trip — 10-20× faster than per-message calls for large triage; a message Graph throttles is re-sent after its Retry-After rather than reported as failed. mark_read takes true/false (or read/unread).

User and Admin

Tool

Description

outlook_whoami

Get current user profile.

outlook_list_calendars

List available calendars, including owner (name, address) and can_view_private_items. Missing owner or private-item permission metadata is null; false means you cannot see private items on that calendar. Use the calendar ID when names repeat.

outlook_list_categories

List category definitions with colors.

outlook_get_mail_tips

Pre-send check (OOF, delivery restrictions).


Prompts

Three workflows ship as MCP prompts, so the common sequences do not have to be reconstructed call by call. Any MCP client that supports prompts will list them; in most clients they appear as slash commands or a prompt picker.

Prompt

Arguments

What it does

morning_brief

folder (default inbox)

Today's events, unread mail and tasks due, in the cheapest order — one scan each, concise=True, batched reads.

triage_folder

folder (default inbox), count (default 50)

One cheap scan of a folder, sorted into reply / archive / junk, applied with a single outlook_batch_triage call rather than one call per message.

catch_up

since (default 24h)

What changed in mail, calendar and contacts, via the delta path — roughly ten times cheaper than re-scanning on a schedule.

They cost nothing until invoked: prompts/list carries only a name and one line each, and the body is fetched on use.


Configuration

Config lives at ~/.outlook-mcp/config.json (created with 0600 permissions on macOS and Linux; see Config permissions below for Windows). It is read as UTF-8 on every platform, and a byte-order mark is accepted. Set the OUTLOOK_MCP_CONFIG_DIR environment variable to move that settings directory (config.json, auth record, and the attachments default move with it) — see Two accounts, two instances below.

Field

Type

Default

Description

client_id

string

null

Azure AD application (client) ID. Required for auth.

tenant_id

string

"consumers"

Azure AD tenant. Use "consumers" for personal Microsoft accounts.

expected_username

string

null

Since 1.29: optional sign-in username for this instance. A saved sign-in for another username is refused before refreshing it; a new sign-in is checked before saving its record or using its credential. Case-insensitive; compares Microsoft's sign-in username literally, without resolving aliases. Unset keeps the existing behaviour. Older versions ignore this key with a warning and do not enforce the guard.

timezone

string

"UTC"

IANA timezone (e.g. "America/New_York"). Interprets zone-less dates, and anchors every event you create — a recurring event is expanded in this zone, so on the default "UTC" a 09:00 weekly meeting shifts an hour when the clocks change. To Do due dates, reminders and new recurrences are sent in this zone too, but To Do keeps only the date of a non-repeating task, not its hour, and some accounts store a repeating task's zone as UTC whatever is sent. Set it to where you are.

read_only

bool

false

When true, all write tools (send, reply, move, delete, create, update, RSVP) return an error. Gates the tools, not the Microsoft token -- see below.

mailbox_settings_write

bool

false

When true, outlook-mcp auth asks for MailboxSettings.ReadWrite instead of MailboxSettings.Read, which is what the inbox-rule write tools need. Consent is per requested scope, so the Azure-portal permission alone does not put it in the token. It also loads the opt-in rules toolset group: asking for the scope is asking to manage rules, so the four rule tools come with it. Off by default: it widens the token to every mailbox setting, not only rules. Refused in combination with read_only_consent, which asks for the read scopes only — that pairing would silently never request the write scope.

read_only_consent

bool

false

When true, outlook-mcp auth asks Microsoft for the read permissions only, instead of the read-write set. For a second, read-only app registration -- see What read_only does and does not do. Requires read_only: true; the config is refused without it.

attachments_dir

string

"~/.outlook-mcp/attachments"

The only directory the attachment tools may read from or write to. Every path an agent supplies is resolved and must land inside it — a symlink out or a .. is refused. Widen it only if you understand that anything reachable can be emailed, and that downloads can add new files there. It must be an absolute path (a leading ~ is expanded), and it cannot be your home folder, a folder that contains it, or a folder that contains the settings folder; a subfolder of any of them is fine. A config that breaks these rules fails to load: the server starts in its safe state and outlook-mcp prints a repair line. Fix it by choosing a folder of its own.

allow_categories

list[string]

[]

Optional. Restrict write tools to specific categories (see below). Empty list = all writes allowed when read_only: false.

allow_unencrypted_token_cache

bool

false

Permit the OAuth token cache to be written in cleartext when the platform has no encrypted store (Linux without libsecret). Off by default: authentication stops with an explanation rather than silently persisting a reusable Graph token in plaintext. macOS and Windows always encrypt and are unaffected.

A config.json that repeats a key inside one object is refused, because the file would not say which value is meant.

Environment configuration (optional)

auth, serve and status share the same loader. It first loads and validates config.json (or the existing defaults when no file exists), then reads these optional variables. A bad, unreadable or symlinked config still refuses startup; environment values cannot bypass it. No override is automatically written back to the file.

Variable

Input

Relation to the file/default value

OUTLOOK_MCP_CLIENT_ID

Nonempty string

Supplies client_id only when the file has none; a different app registration is refused

OUTLOOK_MCP_EXPECTED_USERNAME

Nonempty string

Supplies expected_username only when the file has none; a different username is refused, as for client_id

OUTLOOK_MCP_TENANT_ID

Nonempty string

Overrides tenant_id

OUTLOOK_MCP_TIMEZONE

IANA timezone

Overrides timezone

OUTLOOK_MCP_READ_ONLY

true or false

May enable a restriction; cannot disable one

OUTLOOK_MCP_READ_ONLY_CONSENT

true or false

May enable read-only consent; requires effective read_only: true

OUTLOOK_MCP_ALLOW_CATEGORIES

JSON array of category names

May narrow the permitted categories; cannot widen them

OUTLOOK_MCP_ATTACHMENTS_DIR

Directory path

Must resolve to the configured directory or a descendant

OUTLOOK_MCP_ALLOW_UNENCRYPTED_TOKEN_CACHE

true or false

May prohibit plaintext storage; cannot enable it unless the file already permits it

Unset variables do nothing. A supported variable set to an empty value refuses startup, including an empty Compose ${VAR} pass-through. Booleans accept only true/false (case-insensitive, surrounding whitespace allowed); list input must be JSON, for example ["mail_drafts","contacts_write"].

An empty category list means all categories, so it cannot replace a restricted file list. Each security setting is checked independently: enabling read-only mode does not excuse widening another setting. Security permissions that require explicit consent in the file still require it.

Attachment roots are expanded and resolved without creating a directory. An override is kept as the checked absolute path; .., sibling prefixes and symlinks cannot escape the configured root. Every attachment path check rechecks that root, including when a directory becomes a symlink after startup. On Windows, a different drive/share or an unapproved UNC/device location is refused before resolution can contact it. Invalid inputs, misspelt security variables and attempts to loosen policy stop startup and name the variable to fix in the launch environment. Existing OUTLOOK_MCP_CONFIG_DIR, toolset and transport variables retain their meanings. With none of the new variables, file loading is unchanged. These checks guard the supported setting variables, not the launch environment as a whole: anyone who controls it can also retarget the settings file with OUTLOOK_MCP_CONFIG_DIR or HOME.

Toolset selection (optional) — OUTLOOK_MCP_TOOLSETS

The 71 default tool schemas load into the client's context every turn (the chars/4 proxy test_tool_surface_budget.py measures with; a different yardstick than the ~8.6k o200k figure in ROADMAP for the 62-tool surface). A client that only needs part of the surface can set the OUTLOOK_MCP_TOOLSETS environment variable to a comma-separated list of tool groups, and only those load. The account group (auth / identity) is always available. Groups: mail, drafts, attachments, calendar, contacts, todo, folders, digest, delta, admin, documents, rules, mime, and contact_photos. Unset loads every group except the opt-in ones — documents, rules, mime, and contact_photos — so a stock install gets 71 of the 78 tools. Name rules here, or set mailbox_settings_write: true with OUTLOOK_MCP_TOOLSETS unset, to get the four rule tools; that setting is itself the request for rule management. A selection here always wins: the flag does not add rules to a narrower list. For example, OUTLOOK_MCP_TOOLSETS="mail,calendar,digest,delta" loads 31 tools instead of 71, cutting the per-turn schema cost to about 40% of the default.

Naming any group loads only the groups named, plus account, and a name that is not a group matches nothing. To add all opt-in groups to the default set, name the default groups and the opt-ins: OUTLOOK_MCP_TOOLSETS=mail,drafts,attachments,calendar,contacts,todo,folders,digest,delta,admin,documents,rules,mime,contact_photos.

The groups are not the headings of the Tool Reference. mail holds the mail read, write and triage tools, outlook_list_thread, outlook_copy_message and outlook_batch_triage, but outlook_list_folders is in folders; the Focused Inbox tools (outlook_reclassify_message and the three override tools) are in admin, with categories and mail tips; the three *_delta tools are in delta and outlook_changes_since in digest; outlook_list_calendars is in calendar; the two draft-attachment tools are in drafts, outlook_read_attachment in documents, and the four rule tools in rules, MIME export in mime, and outlook_set_contact_photo in contact_photos; and account is outlook_auth_status and outlook_whoami.

Two accounts, two instances (optional) — OUTLOOK_MCP_CONFIG_DIR

One server process serves one mailbox. To work against two accounts, register two client entries and give each its own settings directory with OUTLOOK_MCP_CONFIG_DIR — pair it with OUTLOOK_MCP_TOOLSETS so each instance also only loads the tool groups it needs:

{
  "mcpServers": {
    "outlook-net": {
      "command": "outlook-mcp",
      "env": {
        "OUTLOOK_MCP_TOOLSETS": "mail,calendar,contacts",
        "OUTLOOK_MCP_CONFIG_DIR": "~/.outlook-mcp-net"
      }
    },
    "outlook-neko": {
      "command": "outlook-mcp",
      "env": {
        "OUTLOOK_MCP_TOOLSETS": "todo",
        "OUTLOOK_MCP_CONFIG_DIR": "~/.outlook-mcp-neko"
      }
    }
  }
}

Then run outlook-mcp auth once per instance, with the same env set, to write each auth record in its own directory. Each instance reads its own config.json (own client_id, timezone, permissions) from its own directory.

Only move the config directory — never HOME. The token cache is not in it: it stays in the OS keyring, and on macOS every azure-identity cache on the host shares one Keychain item, coordinated through a signal file — on this server, ~/.IdentityService/outlook-mcp.nocae (azure-identity appends .nocae to every non-CAE cache name; a CAE cache would be a different file over the same item). Both processes must keep consulting that same signal file so their cache writes lock and merge into the one shared entry — which is exactly what moving the config directory preserves and redirecting HOME (or the cache location) would break: two signal files that each believe they own the Keychain item overwrite each other's token. OUTLOOK_MCP_CONFIG_DIR deliberately moves only where config.json, the auth record, and attachments live; unset or empty keeps the default ~/.outlook-mcp.

Since 1.29, to require a particular sign-in for an instance, add "expected_username": "owner@example.com" to that instance's config.json. Older versions ignore this key with a warning and do not enforce the guard. This optional guard compares Microsoft's saved sign-in username case-insensitively; it does not resolve email aliases. A cached mismatch is refused before a credential is built or refreshed, and outlook-mcp status shows the refusal and remedy without either username: sign in as the expected user, or correct expected_username if it is wrong. A new sign-in is checked after Microsoft's interactive sign-in completes but before its record is saved or credential used. A refused sign-in leaves the previous auth record unchanged, but azure-identity may already have added that account's refresh token to the local shared OS token cache. On macOS this is the same Keychain item, with the previous account's tokens still present. Nothing in outlook-mcp, including logout, removes these cached tokens. Unset/null preserves today's behavior. Blank values and misspellings such as expected_usename stop startup instead of silently disabling the guard.

Remote / HTTP transport (optional) — OUTLOOK_MCP_TRANSPORT

stdio is the default, and every client entry above uses it. For a server that runs on another machine or in a container, or a client that cannot spawn a local process, OUTLOOK_MCP_TRANSPORT=streamable-http serves MCP's streamable-HTTP transport at /mcp instead:

export OUTLOOK_MCP_TRANSPORT=streamable-http
export OUTLOOK_MCP_HTTP_HOST=127.0.0.1   # default 127.0.0.1
export OUTLOOK_MCP_HTTP_PORT=8000      # default 8000
export OUTLOOK_MCP_HTTP_TOKEN=...      # python -c "import secrets; print(secrets.token_urlsafe(32))"
outlook-mcp serve

The client then connects to https://<your proxy>/mcp and sends Authorization: Bearer <token>.

OUTLOOK_MCP_TRANSPORT takes stdio (the default, also when unset or empty) or streamable-http. Any other value, a port outside 1–65535, a malformed OUTLOOK_MCP_HTTP_ALLOWED_HOSTS, or a missing or malformed token stops the server at startup with the reason, before anything binds.

For a container, explicitly set OUTLOOK_MCP_HTTP_HOST=0.0.0.0 and OUTLOOK_MCP_HTTP_ALLOWED_HOSTS=mcp.example.com for the public hostname your proxy forwards. Every public bind prints a plain-HTTP warning before it starts. A wildcard bind (0.0.0.0 or ::) without allowed hosts also warns that normal client Host headers will receive 421: the literal wildcard address is not the hostname or address clients use. The token protects against other OS users and browser pages; code running as your OS user can read the client configuration or launch the server itself. Forwarded headers are not trusted.

A secret file can replace the environment token: set OUTLOOK_MCP_HTTP_TOKEN_FILE to a regular file of at most 4096 bytes containing only the token (an ending newline is fine), and unset OUTLOOK_MCP_HTTP_TOKEN. Both set is refused. On POSIX the file must belong to the server user with no group or other permissions (chmod 600); symlinks are refused. On Windows, restrict the file ACL to the server account yourself; the server does not validate Windows ACLs. File contents and paths are never included in token-file errors.

Container secret mounts need the same file protections.

  • Kubernetes: projected Secret keys are symlinks, so their usual volume paths are refused. A file mounted with subPath avoids that symlink, but must still belong to the server UID and have mode 0400 or 0600; subPath alone does not fix ownership. For a non-root server, an init container can copy the projected key into a writable emptyDir as the server UID with mode 0400, then the application mounts that prepared directory read-only. Recreate the Pod after rotation to refresh the copy or subPath mount; subPath mounts do not receive Secret updates.

  • Docker: Swarm secrets default to root-owned, world-readable files, which are refused. Set the secret's uid to the server UID, gid to its group and mode to 0400. For Compose secrets backed by a local file, uid, gid and mode are ignored: prepare a regular host file with the matching container UID and mode 0400, and mount it read-only. Set OUTLOOK_MCP_HTTP_TOKEN_FILE to the resulting in-container file path. Restart the server after replacing a token; it reads the file only at startup.

This changes who can reach the mailbox. Over stdio, only the process that started the server can. Over HTTP, one request to the port is enough for anything that holds a token, so the token is the whole of the access control:

  • A token is required on every bind, loopback included. The server refuses to start without a token from OUTLOOK_MCP_HTTP_TOKEN or OUTLOOK_MCP_HTTP_TOKEN_FILE. On loopback, a port with no token would let other OS users or browser pages read the mailbox with one HTTP request. Every request must carry Authorization: Bearer <token> or gets 401. The token is one value of at least 32 characters from A–Z a–z 0–9 -._~+/, at least 8 of them different (trailing = padding is allowed). This rejects obvious low-variety values, not every predictable token; use the generator above. To change it, restart the server with the new one.

  • Plain HTTP sends the token in the clear. The server does not terminate TLS. On any bind other machines can reach, the token and everything the tools return cross the network readable by anything on the path, unless a reverse proxy in front of the server terminates TLS. Put it behind one, and let the proxy authenticate callers too if more than one client will reach it.

  • Host and Origin checks apply to every bind. Loopback binds accept loopback hosts and origins. OUTLOOK_MCP_HTTP_ALLOWED_HOSTS optionally adds comma-separated hostnames or IPs, with an optional port (for example mcp.example.com or mcp.example.com:8443). On a public bind it selects the permitted hosts; unset permits only the literal bind address. Bare names and :* entries permit any port, including a bare Host on the default HTTP/HTTPS port. Invalid Host is refused with 421; a supplied Origin must match an allowed host over HTTP or HTTPS, or gets 403. Clients without Origin work. A same-host proxy can send Host: 127.0.0.1:<port>.

  • File paths are on the server. Attach and send-with-attachments paths resolve inside the server’s attachments_dir; a remote client cannot hand over its own local path. A downloaded file and saved_to stay on the server, and a path refusal may name the server’s absolute attachments directory. Inline attachments and as_content=True carry the bytes in the call instead (see Attachments).

  • It is stateless. The server issues no Mcp-Session-Id and answers each request with JSON rather than an event stream. No tool sends anything to the client mid-call, so nothing is lost.

  • One process still serves one account. Pair it with OUTLOOK_MCP_CONFIG_DIR, as for stdio (one process, one port and one settings directory per mailbox), and run outlook-mcp auth where the server runs, with the same environment. A container usually has no keyring; see Token cache stored unencrypted (Linux).

  • No token, request URL or request line is logged.

What read_only does and does not do

read_only: true stops outlook-mcp's write tools from running. Ask it to send mail and it refuses.

It does not make your Microsoft credential read-only. The first sign-in consents the full read-write set, even with read_only: true in the config — the scopes a first consent leaves out can never be added without logging in again (every refresh afterwards uses .default -- "everything this account has already consented" -- so a session granted only read scopes would fail every write with 403 no matter what the config says). The stored token can send mail whether read_only is on or off, and a session consented before you turned read_only on keeps its write scopes.

Two consequences worth understanding:

  • read_only is a line in a text file. Anything able to edit ~/.outlook-mcp/config.json turns it off and has write access immediately -- no re-authentication, no new consent prompt.

  • The enforcement lives in this server's Python code. Any other process holding the cached token is unaffected by it.

So treat read_only as a guardrail against an agent doing something rash, not as a security boundary. If you want a credential that genuinely cannot write, have Microsoft enforce it rather than us:

  1. Register a second Azure app and give it the read permissions only: Mail.Read, Calendars.Read, Contacts.Read, Tasks.Read, MailboxSettings.Read, User.Read. It has to be an app this account has never granted write access to. Microsoft remembers consent per app, and a refresh returns everything that app was ever granted.

  2. Point client_id at it and set both keys:

    { "client_id": "<the read-only app>", "read_only": true, "read_only_consent": true }
  3. Run outlook-mcp auth. With read_only_consent the consent screen lists the read permissions only. Without it, sign-in would ask this app for the read-write set too.

read_only_consent is refused without read_only: true: a sign-in that asked only for read access cannot write, so a server expecting writes would fail on every one. And a sign-in belongs to the app it was made with. After client_id changes, the server will not use the old one — outlook-mcp status and outlook_auth_status say so until you run outlook-mcp auth again.

Granular Write Permissions (optional)

By default, read_only: false unlocks all write tools. For finer control, set allow_categories to restrict write access to specific categories. Read tools (list, search, get) are always allowed — allow_categories only narrows the write surface.

Available categories:

Category

Tools

Risk

mail_drafts

create/update/delete draft, attach to/remove from a draft

Low — stages mail that you send yourself, so check the recipients before sending; draft results list every recipient (to, cc, bcc, reply-to)

mail_triage

move, delete (soft), flag, categorize, mark read, copy, batch, reclassify and set/delete Focused Inbox overrides

Moderate — reversible except hard delete

mail_folders

create/rename/delete folder

Moderate

mail_rules

create/update/delete inbox rule

Dangerous — rules run server-side, so one keeps moving, forwarding or deleting mail with every client closed

mail_send

send, reply, forward, send_draft, send_with_attachments

Dangerous — sends email on your behalf

calendar_write

create/update/delete event, RSVP, attach/remove event files

Moderate — your own calendar, but outlook_attach_to_event reads local files from attachments_dir and pushes their bytes to Graph. The parts that email other people text the agent wrote need mail_send as well: writing into a calendar someone else owns (events there are shown to its owner), inviting attendees, rewording (subject, body, location) any event that already has them, attaching a file to such an event (they get it with its next update), and adding a message to an RSVP. A bare RSVP, a time change and a cancellation still notify the people involved, but carry nothing the agent wrote

contacts_write

create/update/delete contact, set contact photo

Moderate — your own contacts, but with the opt-in contact_photos group loaded, outlook_set_contact_photo reads a local image from attachments_dir and pushes its bytes to Graph

todo_write

create/update/complete/delete task, checklist items; upload/delete task attachments

Moderate — your own task list (writing into a list someone else owns also needs mail_send, like an invitation; outlook_list_task_lists shows is_owner and is_shared), but outlook_upload_task_attachment reads local files from attachments_dir and pushes their bytes to Graph, and task/checklist/attachment deletes are irreversible. Listing and downloading attachments are plain reads, gated like every other read (not at all) and fenced to attachments_dir

Example policies:

Draft-only assistant (agent can compose drafts, you review and send):

{ "read_only": false, "allow_categories": ["mail_drafts", "mail_triage", "todo_write"] }

(Note that todo_write includes the write-side task-attachment tools — file reads from attachments_dir, uploads to Graph, and irreversible deletes. Listing and downloading task attachments are reads and are not write-gated, like the mail attachment reads — see the table above.)

Calendar-only (agent can manage your own calendar):

{ "read_only": false, "allow_categories": ["calendar_write"] }

(It cannot invite anyone, and it cannot write into a calendar someone else owns. An invitation is an email, and so is a change to a shared calendar, so both need mail_send too — add it if the agent should set up meetings with other people or use a shared calendar, not just block out your own time.)

Full write access (agent can do everything):

{ "read_only": false }

Read-only (safest default, no writes):

{ "read_only": true }

When allow_categories is set, any tool in a non-allowed category returns a permission-denied error (PermissionDeniedError) naming the blocked category. When allow_categories is empty (or unset) and read_only is false, all write tools are permitted. read_only: true always takes precedence — if set, all writes are blocked regardless of allow_categories. Unknown category names are rejected at config load time with a validation error; only the eight names above are accepted.


Privacy and Security

  • Zero telemetry. No analytics, no tracking, no usage data collected.

  • Zero local caching. Every call goes directly to Microsoft Graph. No local email/calendar storage. (One carve-out: the To Do default-list id is resolved once per process and kept for the session — an id, not content; see outlook_list_tasks.)

  • Zero third-party calls. The server only talks to graph.microsoft.com and login.microsoftonline.com.

  • Token storage. OAuth tokens are persisted via azure-identity's TokenCachePersistenceOptions. On macOS the OS Keychain is used; on Windows, DPAPI; on Linux with PyGObject/libsecret available, gnome-keyring. On Linux without libsecret (e.g. the isolated venv created by uv tool install), the server refuses to persist tokens unless allow_unencrypted_token_cache is true; with it, they fall back to a 0600 plaintext file at ~/.IdentityService/ and the MCP logs a one-time warning at startup. For encrypted storage on Linux, install python3-gi gnome-keyring libsecret-1-0 and re-create the venv with --system-site-packages.

  • No logging of sensitive data. Message bodies, recipient addresses, and tokens are never logged.

  • Config permissions. On macOS and Linux the config directory is created 0700 and the config file 0600, and a loose mode on the file is repaired on load. On Windows those POSIX modes cannot be enforced — os.chmod there sets only the read-only attribute — so access is governed by the path's Windows ACL, including whatever it inherits from the directory it was created under, which this server neither applies nor verifies. Symlinked configs are rejected on every platform.

  • Input validation. All user inputs (email addresses, Graph IDs, OData filters, KQL queries, datetimes) are validated and sanitized before reaching the Graph API.

  • HTTP transport (opt-in). It changes who can reach the mailbox: a bearer token is required on every bind and checked on every request, and the server speaks plain HTTP, so TLS belongs to a proxy in front. The whole security story is in Remote / HTTP transport.


Development

# Install dev dependencies and the documents extra, as CI does (without it the PDF/XLSX tests skip)
uv sync --all-extras

# Run tests
uv run pytest

# Lint
uv run ruff check src/ tests/ scripts/

# Format (CI fails if `ruff format --check` would change a file)
uv run ruff format src/ tests/ scripts/

# Run server locally (stdio)
uv run outlook-mcp

Requirements: Python 3.10+


Roadmap

  • Advanced mail -- internet message headers

  • Calendar -- cancel event (with attendee notification)

  • Work/school-only tools -- free/busy, meeting times, automatic replies, shared mailboxes: not planned for now (#133). If any are taken later, they come as an opt-in group that personal accounts never load

Committed direction, and what was investigated and ruled out (mailbox settings), is in ROADMAP.md.


License

MIT. See LICENSE.

Available Tools

71 tools
outlook_add_checklist_itemC

Add a checklist item (sub-step) to a To Do task.

Inputs: task_id (required), display_name (required), list_id.

outlook_attach_to_draftA

Add attachments to an existing draft; auto-switches to upload-session for files >3MB.

attachment_paths resolve inside the configured attachments directory (attachments_dir, an attachments folder in the settings directory by default) — a bare filename is looked up there, and a path outside it is refused. attachments: inline files [{name, content_base64, content_type?}], up to 3MB each. Returns new attachment IDs for later removal via outlook_remove_draft_attachment.

Inputs: draft_id (required), attachments, attachment_paths.

outlook_attach_to_eventA
Destructive

Attach files to an event; auto-switches to upload-session for files >3MB.

attachment_paths resolve inside attachments_dir, as for outlook_attach_to_draft. Attendees get the files with the event's next update. Returns new attachment IDs.

Inputs: event_id (required), attachment_paths (required).

outlook_auth_statusA
Read-only

Check authentication status. Run outlook-mcp auth on the host if needed.

Inputs: no named parameters.

outlook_batch_triageA

Triage up to 20 messages in one $batch call.

action is "move", "flag", "categorize", or "mark_read".

Example: outlook_batch_triage(message_ids=[id1, id2], action="move", value="Archive") value is the action target (folder name for move, status for flag/mark_read, category name for categorize). Hard cap of 20.

Inputs: value (required), action (required), message_ids (required).

outlook_categorize_messageB
Idempotent

Set categories on a message (replaces the full list).

Example: outlook_categorize_message(message_id=..., categories=["Follow-up", "Pricing"])

Inputs: categories (required), message_id (required).

outlook_changes_sinceA
Read-only

One structured "since last call" digest across mail, events, and contacts.

Use this for recurring agent loops (morning brief, hourly inbox sweep) — one call returns counts, urgent_flagged mail, by-sender rollup, plus new/cancelled events and contacts counts. Use the three individual delta tools (outlook_list_inbox_delta, outlook_list_events_delta, outlook_list_contacts_delta) when you need raw item lists or per-resource control.

Example: first call: outlook_changes_since(); next: outlook_changes_since(delta_tokens=<delta_tokens from prior response>). First call covers the last fallback_window_hours (default 24); later calls (tokens passed back) return only what changed. Replace stored delta_tokens with the returned dict; never merge them. has_more true: a resource stopped early; pass the returned dict back. Each resource's token is independent — drop one stale token without re-syncing the others. If Graph 410s on a token (syncStateNotFound), that resource auto-resyncs and _meta.resync lists which one. urgent_flagged = high-importance OR flagged mail. by_sender = top 5 senders. Calendar modified[] is reserved for future use — modified events surface in new[] today (Graph delta doesn't distinguish them). Calendar organizer_email is also currently empty (the v1.9.0 delta formatter surfaces the organizer name only).

Inputs: delta_tokens, fallback_window_hours.

outlook_complete_taskC

Mark a To Do task as completed.

Inputs: task_id (required), list_id.

outlook_copy_messageA

Copy a message to another folder (duplicates; source is unchanged).

Use outlook_move_message to remove from source. folder accepts display names, well-known names, or Graph IDs — prefer names.

Inputs: folder (required), message_id (required).

outlook_create_contactA

Create a new contact with name and optional email, phone, company, job_title, birthday (YYYY-MM-DD).

title is the name prefix ("Dr.", "Ms."), shown in the display name — not the job. phone_type: "mobile", "business" or "home".

Inputs: first_name (required), email, phone, title, +8 more.

outlook_create_draftA

Create a draft email for later review/send (pair with outlook_send_draft).

Use this when a human should review before sending; use outlook_send_message to send immediately without review. reply_to_message_id (reply_all=True for all) or forward_message_id drafts in that thread, quoting the original; on a reply, Graph fills to/cc/subject, so pass [] for a recipient you want cleared and omit the argument to keep Graph's choice. Pass deferred_send_datetime (ISO 8601, e.g. "2026-05-06T08:00:00Z") to schedule delayed delivery — Exchange holds the message server-side after outlook_send_draft. Pass reply_to to pre-populate the Reply-To header.

Inputs: body (required), cc, to, bcc, +9 more.

outlook_create_eventA
Destructive

Create a calendar event with optional attendees, recurrence, busy status, online meeting.

Example: outlook_create_event(subject="Q3 review", start="2026-08-15T14:00:00Z", end="2026-08-15T15:00:00Z", attendees=["alice@acme.com"]) is_online adds an online meeting; it may have no effect on some personal accounts, so check is_online in the result (absent there: read it with outlook_get_event). start/end are ISO 8601 or a relative offset. Passing recurrence creates a series, not a single event. It takes either a shorthand — "daily", "weekdays", "weekly", "monthly", "yearly", all anchored on start and open-ended — or a full Microsoft Graph recurrence object for anything else, e.g. every other Mon+Fri for 10 occurrences: {"pattern": {"type": "weekly", "interval": 2, "daysOfWeek": ["monday", "friday"]}, "range": {"type": "numbered", "numberOfOccurrences": 10}} range.startDate defaults to the event's start date. Prefer a bounded range ("endDate"/"numbered") when the event has attendees — a "noEnd" series invites them to every future occurrence. timezone is the IANA zone the event is anchored in, which is what a recurring series is expanded against (default: the configured zone). A zone name like America/Los_Angeles, never an abbreviation like PDT. show_as is Outlook's "Show as": "free", "tentative", "busy", "oof" (out of office), "workingElsewhere", or "unknown". Omitted, Graph defaults the event to busy. calendar: name or ID; omit for the default. key: your own reference for the event, e.g. a booking number.

Inputs: end (required), start (required), subject (required), key, +9 more.

outlook_create_folderB

Create a mail folder; pass parent_folder (name, path or ID) to nest it under that one.

Inputs: name (required), parent_folder.

outlook_create_taskA

Create a Microsoft To Do task with optional due date, importance, body, and recurrence.

Example: outlook_create_task(title="Send invoice", due="2026-09-01", importance="high") reminder=True requires due and sets the reminder to the due time — Graph silently drops a reminder that has no time. due takes ISO 8601 or a relative offset — note +7d is seven days from now, while a bare 7d means seven days ago. importance is "low", "normal", or "high". Defaults to the user's default list when list_id is omitted.

Inputs: title (required), due, body, list_id, +3 more.

outlook_delete_checklist_itemB
Destructive

Delete a checklist item from a To Do task.

Inputs: task_id (required), checklist_item_id (required), list_id.

outlook_delete_contactC
Destructive

Delete a contact by ID.

Inputs: contact_id (required).

outlook_delete_draftC
Destructive

Delete a draft message by ID.

Inputs: draft_id (required).

outlook_delete_eventA
Destructive

Delete a calendar event by ID (cancels and notifies attendees if you're the organizer).

Inputs: event_id (required).

outlook_delete_folderA
Destructive

Delete a user-created mail folder by ID; refuses well-known folders (inbox, sentitems).

Inputs: folder_id (required).

outlook_delete_inbox_overrideB
Destructive

Delete a Focused Inbox per-sender override rule by its ID.

Inputs: override_id (required).

outlook_delete_messageA
Destructive

Delete a message — soft delete (to Deleted Items) by default; permanent=True to hard-delete.

This is the canonical way to delete a message. Do NOT use outlook_move_message(folder="deleteditems") for deletion.

Inputs: message_id (required), permanent.

outlook_delete_taskC
Destructive

Delete a task from a Microsoft To Do list.

Inputs: task_id (required), list_id.

outlook_delete_task_attachmentC
Destructive

Remove an attachment from a To Do task.

Inputs: task_id (required), attachment_id (required), list_id.

outlook_download_attachmentA
Idempotent

Download an attachment to save_path on the host, or return it with as_content=True.

save_path is resolved inside the configured attachments directory (attachments_dir, an attachments folder in the settings directory by default) — a bare filename lands there; a path outside it is refused. Same directory for reads and writes. as_content writes nothing; 10 MB at most.

Inputs: message_id (required), attachment_id (required), save_path, as_content.

outlook_download_task_attachmentA
Idempotent

Download a To Do task attachment to a local file, or return it with as_content=True.

save_path resolves inside the configured attachments directory; it never replaces an existing file. as_content writes nothing; 10 MB at most.

Inputs: task_id (required), attachment_id (required), list_id, save_path, +1 more.

outlook_find_event_by_keyA
Read-only

Find events by the key given to outlook_create_event or outlook_update_event.

Any date. Searches the default calendar, or calendar. Returns events and series masters, not occurrences.

Inputs: key (required), calendar.

outlook_flag_messageB
Idempotent

Set the follow-up flag on a message. status is "flagged", "complete", or "notFlagged".

Inputs: status (required), message_id (required).

outlook_forwardC
Destructive

Forward an existing message to new recipients, with optional comment.

Inputs: to (required), message_id (required), comment, is_markdown.

outlook_get_contactB
Read-only

Get one full contact by ID.

Inputs: contact_id (required).

outlook_get_eventA
Read-only

Read an event by event_id, or an invitation by message_id (exactly one).

Returns your current event: body, attendees with proposed_new_time, organizer, is_organizer, allow_new_time_proposals, is_cancelled, recurrence, type, show_as, key and attachment metadata. start/end are UTC; original_start_time_zone is the anchor zone. recurrence uses the create tool's shape.

Inputs: event_id, message_id.

outlook_get_mail_tipsB
Read-only

Pre-send check for recipients: out-of-office, delivery limits, mailbox-full warnings.

Inputs: emails (required).

outlook_get_taskA
Read-only

Get full To Do task details: notes (body), checklist items, due, recurrence flag.

Use this for one task's sub-steps and notes; use outlook_list_tasks for overviews. checklist_items are ordered unchecked-first, matching the To Do client. list_id is only needed when the task lives in a non-default list.

Inputs: task_id (required), list_id.

outlook_list_attachmentsB
Read-only

List attachments on a message — returns IDs, names, sizes, and content types.

Inputs: message_id (required).

outlook_list_calendarsA
Read-only

List all calendars available to the authenticated user (primary + secondary).

Inputs: no named parameters.

outlook_list_categoriesA
Read-only

List the user's master category definitions (names + colors).

Provides the valid values for outlook_categorize_message.

Inputs: no named parameters.

outlook_list_contactsA
Read-only

List contacts with cursor pagination.

Use for one-shot queries; use outlook_list_contacts_delta for polling/recurring agents.

Inputs: count, cursor.

outlook_list_contacts_deltaA
Read-only

List only contact changes since the last call.

Use this for polling/recurring agents — typically 10x cheaper than outlook_list_contacts after the first call. Use outlook_list_contacts for one-shot queries.

Example: first call: outlook_list_contacts_delta(); next: outlook_list_contacts_delta(delta_token=). is_deleted=True items are tombstones (drop cached payload). has_more=True means drain immediately by passing the returned delta_token back.

Inputs: page_size, delta_token.

outlook_list_draftsB
Read-only

List messages in the Drafts folder with cursor pagination.

Inputs: count, cursor.

outlook_list_eventsA
Read-only

List calendar events in a date range (expands recurring instances).

Use for one-shot queries; use outlook_list_events_delta for polling/recurring agents.

Pass concise=True for day-at-a-glance scans: drops organizer, response_status, type and show_as; adds is_organizer and attendees_count; spells is_online as is_online_meeting.

calendar: a display name or an ID from outlook_list_calendars; omit for the default calendar. A cursor continues the listing it came from.

Inputs: days, after, count, before, +3 more.

outlook_list_events_deltaA
Read-only

List only calendar event changes within a window since the last call.

Use this for polling/recurring agents — typically 10x cheaper than outlook_list_events after the first call. Use outlook_list_events for one-shot queries.

Example: first call: outlook_list_events_delta(start="2026-05-22T00:00:00Z", end="2026-05-29T00:00:00Z"); next: outlook_list_events_delta(delta_token=). start/end (ISO 8601) required on first call only; the cursor encodes the window thereafter. is_deleted=True items are tombstones. has_more=True means drain immediately.

Inputs: end, start, page_size, delta_token.

outlook_list_foldersA
Read-only

List mail folders with message counts, parent_id, and child count.

Default is top-level only; pass recursive=True to walk the full tree, each folder with the path that folder arguments accept.

Inputs: cursor, recursive.

outlook_list_inboxA
Read-only

List messages in one folder with structured filters (read, sender, date, category, Focused).

Use this for folder-scoped browsing; use outlook_search_mail for KQL full-text search across all folders. For polling/recurring agents use outlook_list_inbox_delta (typically 10x cheaper after the first call).

Example: outlook_list_inbox(folder="Junk Email", unread_only=True, count=5) folder accepts display names, well-known names ("inbox", "junkemail"), or Graph IDs — prefer names. Pass concise=True to drop large fields (preview, categories) — ~10x fewer tokens. Pass uncategorized_only=True to return only messages with no categories assigned. after/before take ISO 8601 or a relative offset — 7d is seven days ago, +7d is seven days from now.

Inputs: skip, after, count, before, +7 more.

outlook_list_inbox_deltaA
Read-only

List only inbox changes since the last call.

Use this for polling/recurring agents — typically 10x cheaper than outlook_list_inbox after the first call. Use outlook_list_inbox for one-shot snapshots.

Example: first call: outlook_list_inbox_delta(); next: outlook_list_inbox_delta(delta_token=). is_deleted=True items are tombstones (drop cached payload). has_more=True means drain immediately by passing the returned delta_token back.

Inputs: folder, page_size, delta_token.

outlook_list_inbox_overridesA
Read-only

List the user's Focused Inbox per-sender override rules.

Each override forces mail from a given sender into Focused or Other regardless of Graph's inference.

Inputs: no named parameters.

outlook_list_task_attachmentsA
Read-only

List attachments on a To Do task (id, name, size, content_type) with pagination.

Use outlook_download_task_attachment with an id from here to save the content. has_more=True means pass next_cursor back for the next page.

Inputs: task_id (required), count, cursor, list_id.

outlook_list_task_listsA
Read-only

List all Microsoft To Do task lists for the current user.

Inputs: no named parameters.

outlook_list_tasksC
Read-only

List tasks in a To Do list with optional status filter.

status: "notStarted", "inProgress", or "completed".

Inputs: count, cursor, status, list_id.

outlook_list_threadA
Read-only

List all messages in a conversation thread, chronological order.

Needs conversation_id from a message's metadata. Pass concise=True to drop large fields (quoted prior-message text in each preview) — ~10x fewer tokens on long reply chains.

Inputs: conversation_id (required), count, concise.

outlook_mark_readA
Idempotent

Mark a single message as read or unread (set is_read=True or False).

Inputs: is_read (required), message_id (required).

outlook_move_messageA

Move a message to another folder (removes from source).

Use outlook_copy_message to duplicate without removing the source. For deletion use outlook_delete_message (not move to "deleteditems"). folder accepts display names, well-known names ("inbox", "archive", "deleteditems"), or Graph IDs — prefer names.

Inputs: folder (required), message_id (required).

outlook_read_messageA
Read-only

Get one full message by ID or Message-ID (<abc@example.com>).

format is "text", "html", or "full" (the stored body, usually HTML, as body and body_html). Pass include_deferred_send=True to also return the scheduled-send time (PR_DEFERRED_SEND_TIME) as deferred_send_datetime — useful when recreating a delayed draft. Pass concise=True to drop large fields (body, body_html) and return a 200-char body_preview — ~10x fewer tokens for triage scans. include_sender_auth=True adds sender_authentication: did Microsoft verify the From domain?

Inputs: message_id (required), format, concise, include_sender_auth, +1 more.

outlook_read_messagesA
Read-only

Bulk read up to 20 messages by ID via $batch — use NOT N outlook_read_message calls.

Per-message shape in messages matches outlook_read_message byte-for-byte for the same (format, concise, include_deferred_send, include_sender_auth). Ordering follows input message_ids. Returns {messages, failures, requested, succeeded, failed} — 404s on some IDs are surfaced in failures without failing the whole call (partial-failure tolerant).

Example: outlook_read_messages(message_ids=[id1, id2, id3], concise=True) Hard cap of 20 (Graph $batch limit).

Inputs: message_ids (required), format, concise, include_sender_auth, +1 more.

outlook_reclassify_messageA

Reclassify ONE message's Focused/Other placement. classification is "focused" or "other".

Use this to fix a single message; use outlook_set_inbox_override for a sticky rule that affects future messages from the same sender.

Inputs: message_id (required), classification (required).

outlook_remove_draft_attachmentA
Destructive

Remove a single attachment from a draft message by attachment ID.

Inputs: draft_id (required), attachment_id (required).

outlook_remove_event_attachmentA
Destructive

Remove one attachment from an event (IDs from outlook_get_event's attachments).

Inputs: event_id (required), attachment_id (required).

outlook_rename_folderA
Idempotent

Rename a user-created mail folder by ID.

Inputs: name (required), folder_id (required).

outlook_replyB
Destructive

Reply (or reply-all) to an email message.

Use this for email; use outlook_rsvp for calendar meeting invites.

Inputs: body (required), message_id (required), is_html, reply_all, +1 more.

outlook_rsvpA
Destructive

RSVP to a calendar meeting invite. response is "accept", "decline", or "tentative".

Use this for meeting invites; use outlook_reply to reply to a regular email message.

Inputs: event_id (required), response (required), message.

outlook_search_contactsA
Read-only

Search contacts by name or email using KQL query syntax.

phone (instead of query) finds a number written any way, with or without country code.

Inputs: count, phone, query.

outlook_search_mailA
Read-only

Full-text search mail with KQL across all folders (or one, if folder is set).

Use this for "find emails about X"; use outlook_list_inbox for structured filters scoped to a single folder.

Example: outlook_search_mail(query="from:sarah@acme.com received>=2026-01-01", count=10) query is Microsoft KQL (from:, subject:, received>=, hasattachment:true, AND/OR/NOT). Operators must be UPPERCASE — lowercase and is matched as a literal term. Two terms with no operator between them broaden the search; use AND explicitly to narrow. Pass concise=True to drop large fields (preview, categories) — ~10x fewer tokens.

Inputs: query (required), count, cursor, folder, +1 more.

outlook_send_draftA
Destructive

Send an existing draft (pair with outlook_create_draft for human-review send flow).

Inputs: draft_id (required).

outlook_send_messageA
Destructive

Send an email immediately, no human review.

For human-review workflows use outlook_create_draft + outlook_send_draft instead. For replying to an existing message use outlook_reply; for calendar invites use outlook_rsvp. Pass reply_to to route recipient replies to a different address (e.g. a shared team alias).

Inputs: to (required), body (required), subject (required), cc, +6 more.

outlook_send_with_attachmentsA
Destructive

Send an email with file attachments; auto-switches to upload-session for files >3MB.

attachment_paths resolve inside the configured attachments directory (attachments_dir, an attachments folder in the settings directory by default) — a bare filename is looked up there, and a path outside it is refused. attachments: inline files [{name, content_base64, content_type?}], up to 3MB each. Pass reply_to to route replies to a different address.

Inputs: to (required), body (required), subject (required), cc, +6 more.

outlook_set_inbox_overrideA
Idempotent

Create or update a sticky Focused/Other rule for a sender (upsert, case-insensitive).

Use this to permanently change classification for FUTURE messages from a sender; use outlook_reclassify_message to fix ONE existing message.

Example: outlook_set_inbox_override(sender_email="marketing@acme.com", classify_as="other") Returns status: "created" or "updated".

Inputs: classify_as (required), sender_email (required).

outlook_update_checklist_itemA
Idempotent

Update a checklist item (partial patch — only provided fields change).

is_checked=True marks a sub-step done; Graph maintains the checked timestamp from it. Renaming passes display_name.

Inputs: task_id (required), checklist_item_id (required), list_id, is_checked, +1 more.

outlook_update_contactA

Update an existing contact (partial patch — only provided fields change).

A text field passed as "" is cleared; job_title is the job, company the employer. An address takes the shape outlook_get_contact returns — any subset of {"street", "city", "state", "postal_code", "country_or_region"} — and REPLACES that whole address, so pass back every part you want to keep. Omit it to leave it untouched. phone_type ("mobile", "business", "home") picks the field; business/home REPLACE that list. clear_phones empties those types: phone_type="business", clear_phones=["mobile"] moves it. title is the name prefix ("Dr.", "Ms."), shown in the display name — not the job. birthday is a date, YYYY-MM-DD. categories REPLACES the whole list ([] clears it). email REPLACES every address; add_emails/remove_emails change only those (3 at most).

Inputs: contact_id (required), email, phone, title, +15 more.

outlook_update_draftA

Update an existing draft (partial patch).

Pass is_html=True when body is HTML — required when overwriting a draft originally composed as HTML (consumer Outlook rejects Text-over-HTML PATCH). Pass reply_to=[...] to overwrite Reply-To; reply_to=[] to clear it. Pass deferred_send_datetime (ISO 8601) to set the scheduled-send time; empty string clears it.

Inputs: draft_id (required), cc, to, body, +5 more.

outlook_update_eventA
Destructive

Update fields on an existing event (partial patch — only provided fields change).

recurrence takes the same shapes as outlook_create_event and converts a single event into a series, or replaces an existing series' pattern. Omit it to leave any recurrence alone; pass remove_recurrence=True to turn a series back into a single event, keeping the first occurrence's time (the two are mutually exclusive). attendees REPLACES the whole guest list (Graph has no add-one operation) and sends invitations to everyone on it plus cancellations to anyone dropped — pass the full intended list; [] removes everyone. is_all_day REQUIRES start and end in the same call, both on midnight boundaries. Patching a time keeps the zone the event is anchored in; pass timezone (with start and end) to re-anchor it somewhere else. A start, end or recurrence patch to a series with edited or deleted occurrences is refused, since Graph would discard them. Omitting an argument leaves it unchanged, so False and [] are instructions, not absences. show_as is Outlook's "Show as" — same values as outlook_create_event — and patches on its own; unlike is_all_day it needs nothing resent alongside it. key patches on its own too. is_online=True adds an online meeting, as on create (check is_online in the result); False is refused, because Graph keeps an online meeting once it exists.

Inputs: event_id (required), end, key, body, +10 more.

outlook_update_taskB

Update fields on a To Do task (partial patch — only provided fields change).

Inputs: task_id (required), due, body, title, +2 more.

outlook_upload_task_attachmentA

Attach a local file to a To Do task via inline base64 POST (1 byte – 20 MiB).

file_path resolves inside the configured attachments directory. Larger files are refused up front: Graph caps the request body at 30 MB and base64 inflates the file 4/3, so 20 MiB is the honest ceiling.

Inputs: task_id (required), file_path (required), list_id.

outlook_whoamiA
Read-only

Get the authenticated user's profile (display name, email, ID).

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 71 tools

    Disambiguation4/5

    Most tools have sharply distinct purposes, and descriptions actively cross-reference alternatives (list_inbox vs search_mail vs list_inbox_delta; reply vs create_draft/send_draft; reclassify_message vs set_inbox_override; rsvp vs reply). A few boundaries are softer — send_message vs send_with_attachments, attach_to_draft vs attach_to_event, and the overlapping delta tools vs changes_since — but documentation makes the intended choice clear.

    Naming Consistency4/5

    Nearly every tool carries the outlook_ prefix with a verb_noun form (create_event, list_categories, update_contact, download_task_attachment), which is highly predictable. Minor deviations are bare-verb or noun-less names like outlook_reply, outlook_forward, outlook_whoami, outlook_auth_status, outlook_rsvp, and outlook_changes_since.

    Tool Count2/5

    71 tools is far beyond a comfortable surface, even for a full Outlook client spanning mail, calendar, contacts, tasks, folders and attachments. Considerable duplication could be consolidated — three near-identical delta tools plus changes_since, and parallel attach/remove-attachment families for drafts, events and tasks.

    Completeness5/5

    Coverage is close to exhaustive: CRUD for messages, drafts, events, contacts, tasks, checklist items, folders and attachments, plus categories, Focused Inbox overrides, delta sync, batch triage and mail tips. Only minor gaps exist (e.g. no delete option in batch triage, no task-list create/delete, no inbox rules/out-of-office configuration).

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      22 consolidated MCP tools for email, calendar, contacts, folders, rules, categories, and settings with safety controls (dry-run preview, rate limiting, recipient allowlists) and MCP annotations on every tool. Works with personal Outlook.com and work/school Microsoft 365 accounts.
      22
      773 npm
      40
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Comprehensive MCP server for local Microsoft Outlook automation, providing 64 tools across email, calendar, contacts, tasks, notes, and Exchange features on both Windows and macOS.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for sending and managing Microsoft Outlook email via the Microsoft Graph API, including drafts, replies, contacts, and directory search.
      89 npm
      MIT