outlook-mcp
Manage a personal Microsoft Outlook account through typed MCP tools for mail, calendar, contacts, folders, and To Do.
Check authentication and identity (
outlook_auth_status,outlook_whoami).Read, search, list, bulk-read, and delta-sync mail; inspect threads and folders.
Send, reply, forward, draft, schedule delayed delivery, and attach files to email.
Triage mail: move/copy, soft/hard delete, flag, categorize, mark read/unread, reclassify Focused Inbox, and manage per-sender overrides.
Create, rename, and delete mail folders; batch-triage up to 20 messages.
Read, create, update, delete, and RSVP to calendar events; attach/remove event files; list calendars.
List, search, get, create, update, delete, and delta-sync contacts.
Manage To Do lists, tasks, checklist items, and task attachments.
Get category definitions and pre-send mail tips.
Writes can be restricted via
read_onlyandallow_categories; attachment paths are confined toattachments_dir.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@outlook-mcp Show me my unread emails from today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
outlook-mcp
MCP server for Microsoft Outlook personal accounts via Microsoft Graph API.
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, optionalread_onlymode, 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
Claude Code —
claude mcp add outlook -- outlook-mcpCursor — MCP-compatible
Any MCP client — it's a standard stdio MCP server, with an opt-in streamable-HTTP transport for clients that cannot spawn a local process
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.
duealso takes+7dornow.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
startandendtake+2h,nowor7d, like every other date, and the reply shows the time each became.Online meetings (1.32):
outlook_update_eventcan add an online meeting to an existing event. Some personal accounts ignoreis_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, runoutlook-mcp authonce (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/contactsMail 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: truein config to block all write operations. Note this limits the tools, not the token -- see Whatread_onlydoes 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:
7dis seven days ago,+7dis seven days from now,nowis 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_tokenis caller-held state, so it is untrusted input. Every URL that would carry a Graph bearer token is parsed and required to be https ongraph.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_folderandcatch_upship 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=Trueto 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×. Onoutlook_list_eventsthe trade is different and smaller:organizer,response_status,type,show_asandkeycome off,is_organizerandattendees_countare added, andis_onlineis spelledis_online_meeting, so a concise scan cannot tell a recurring occurrence from a one-off. Defaultconcise=Falsepreserves 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.OutlookMCPErrorsubclasses 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:
Go to azure.microsoft.com/free and sign up with your personal
@outlook.comaccount. Requires a credit card for identity verification but won't charge you. This creates a proper Azure AD tenant.
Register the App
Go to App Registrations and sign in with your
@outlook.comaccount.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
Click Register. Copy the Application (client) ID from the overview page.
Go to Authentication (Preview) → Settings tab → toggle "Allow public client flows" to Yes → Save.
Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions → add:
Mail.ReadWrite,Mail.SendCalendars.ReadWriteContacts.ReadWrite,Tasks.ReadWriteMailboxSettings.ReadUser.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-mcpTo 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 syncConfigure
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 --jsonRestart 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 checkoutYou'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 statusIf 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-mcpYour 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 authThe 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 |
| 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 |
| List messages in a folder. |
| Get full message by ID, or by its Message-ID header value ( |
| Bulk read up to 20 messages by ID via Graph |
| Search mail using KQL query. Optionally scope to a folder by name, path or ID. A |
| List mail folders with counts, |
| List only inbox changes since the last call. |
| One structured "since last call" digest composing mail/events/contacts deltas. Returns counts + |
| Opt-in ( |
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 |
| Send email. Supports TO/CC/BCC, HTML or Markdown body, importance level, |
| Reply or reply-all to a message, the text above the quoted original. Plain text keeps its paragraphs, line breaks and |
| 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, , 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 |
| Move a message to a folder by name, path or ID. |
| Delete a message. Soft delete (Deleted Items) by default. |
| Set follow-up flag: |
| Set categories on a message. |
| Mark a message as read or unread. |
| Move a message between Focused Inbox and Other ( |
| List Focused Inbox per-sender override rules. |
| Upsert a per-sender Focused 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 |
| List inbox rules in execution order, with conditions, exceptions and actions, and whether Exchange reports an error applying the rule. |
| Create a rule from sender/subject/body/attachment conditions and move, copy, mark-read, delete, forward, categorize or stop-processing actions. |
| 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 |
| 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:
Ask for the write scope at sign-in. Set
mailbox_settings_write: truein your config. The default read-write consent asks forMailboxSettings.Readonly, so without this every rule write answersErrorAccessDeniedno matter what the app registration allows.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.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.
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 |
| List events in a date range. Expands recurring events. Each event carries |
| Get full event details: attendees, body, online meeting URL, recurrence, |
| Find the events whose |
| List only event changes inside a window since the last call. |
Calendar Write
Tool | Description |
| Create event with location and attendees. |
| Update event fields (subject, time, location, body, attendees, all-day, |
| Delete a calendar event. |
| RSVP to an event: |
| Attach files to an event — an e-ticket on a flight, say. |
| Remove one attachment from an event, by the ID |
Contacts
Tool | Description |
| List contacts with cursor pagination. Summaries carry |
| Search contacts by name or email. |
| Get full contact details by ID, including |
| Create a new contact. |
| Update contact fields, including |
| Delete a contact. |
| Opt-in ( |
| List only contact changes since the last call. Deletes come back as |
To Do
Tool | Description |
| List To Do lists, with |
| List tasks with status filter and pagination. |
| Get full task details: notes ( |
| Create task with due date, importance, recurrence. |
| 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. |
| Mark task as completed. |
| Delete a task. |
| Add a checklist item (sub-step) to a task. |
| Update a checklist item — mark done ( |
| Delete a checklist item from a task. |
| List attachments on a To Do task (id, name, size, content_type) with pagination. |
| Download a task attachment's content to a local file (confined to |
| Attach a local file (from |
| Remove an attachment from a To Do task. |
Drafts
Tool | Description |
| List draft messages with pagination. |
| Create a draft, with an HTML ( |
| Update draft fields. Accepts |
| Send an existing 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 widenattachments_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 fromattachments_dirand downloads write into it, so neither can sweep arbitrary files off disk. (Downloads are nottodo_write-gated — they are reads, likeoutlook_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=Trueon 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.attachmentsonoutlook_send_with_attachmentsandoutlook_attach_to_drafttakes 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_attachmentandoutlook_set_contact_phototake paths only.
Tool | Description |
| List attachments on a message. |
| Download an attachment and save decoded bytes into |
| Opt-in ( |
| Send a message with attachments read from |
| Add attachments from |
| 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 |
| Create mail folder (top-level, or nested under |
| Rename a mail folder, by ID. |
| Delete a mail folder by ID (refuses well-known folders). |
Threading and Batch
Tool | Description |
| Get all messages in a conversation thread. |
| Copy a message to another folder (name, path or ID). |
| Batch move/flag/categorize/mark_read (max 20 per call). Single Graph |
User and Admin
Tool | Description |
| Get current user profile. |
| List available calendars, including |
| List category definitions with colors. |
| 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 |
|
| Today's events, unread mail and tasks due, in the cheapest order — one scan each, |
|
| One cheap scan of a folder, sorted into reply / archive / junk, applied with a single |
|
| 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 |
|
|
| Azure AD application (client) ID. Required for auth. |
|
|
| Azure AD tenant. Use |
|
|
| 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. |
|
|
| IANA timezone (e.g. |
|
|
| When |
|
|
| When |
|
|
| When |
|
|
| 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 |
|
|
| Optional. Restrict write tools to specific categories (see below). Empty list = all writes allowed when |
|
|
| 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 |
| Nonempty string | Supplies |
| Nonempty string | Supplies |
| Nonempty string | Overrides |
| IANA timezone | Overrides |
|
| May enable a restriction; cannot disable one |
|
| May enable read-only consent; requires effective |
| JSON array of category names | May narrow the permitted categories; cannot widen them |
| Directory path | Must resolve to the configured directory or a descendant |
|
| 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 serveThe 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
subPathavoids that symlink, but must still belong to the server UID and have mode0400or0600;subPathalone does not fix ownership. For a non-root server, an init container can copy the projected key into a writableemptyDiras the server UID with mode0400, then the application mounts that prepared directory read-only. Recreate the Pod after rotation to refresh the copy orsubPathmount; subPath mounts do not receive Secret updates.Docker: Swarm secrets default to root-owned, world-readable files, which are refused. Set the secret's
uidto the server UID,gidto its group andmodeto0400. For Compose secrets backed by a local file,uid,gidandmodeare ignored: prepare a regular host file with the matching container UID and mode0400, and mount it read-only. SetOUTLOOK_MCP_HTTP_TOKEN_FILEto 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_TOKENorOUTLOOK_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 carryAuthorization: Bearer <token>or gets401. The token is one value of at least 32 characters fromA–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_HOSTSoptionally adds comma-separated hostnames or IPs, with an optional port (for examplemcp.example.comormcp.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 sendHost: 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 andsaved_tostay on the server, and a path refusal may name the server’s absolute attachments directory. Inlineattachmentsandas_content=Truecarry the bytes in the call instead (see Attachments).It is stateless. The server issues no
Mcp-Session-Idand 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 runoutlook-mcp authwhere 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_onlyis a line in a text file. Anything able to edit~/.outlook-mcp/config.jsonturns 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:
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.Point
client_idat it and set both keys:{ "client_id": "<the read-only app>", "read_only": true, "read_only_consent": true }Run
outlook-mcp auth. Withread_only_consentthe 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 |
| 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) |
| move, delete (soft), flag, categorize, mark read, copy, batch, reclassify and set/delete Focused Inbox overrides | Moderate — reversible except hard delete |
| create/rename/delete folder | Moderate |
| create/update/delete inbox rule | Dangerous — rules run server-side, so one keeps moving, forwarding or deleting mail with every client closed |
| send, reply, forward, send_draft, send_with_attachments | Dangerous — sends email on your behalf |
| create/update/delete event, RSVP, attach/remove event files | Moderate — your own calendar, but |
| create/update/delete contact, set contact photo | Moderate — your own contacts, but with the opt-in |
| 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 |
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.comandlogin.microsoftonline.com.Token storage. OAuth tokens are persisted via
azure-identity'sTokenCachePersistenceOptions. 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 byuv tool install), the server refuses to persist tokens unlessallow_unencrypted_token_cacheistrue; with it, they fall back to a0600plaintext file at~/.IdentityService/and the MCP logs a one-time warning at startup. For encrypted storage on Linux, installpython3-gi gnome-keyring libsecret-1-0and 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
0700and the config file0600, and a loose mode on the file is repaired on load. On Windows those POSIX modes cannot be enforced —os.chmodthere 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-mcpRequirements: 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 toolsoutlook_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_eventADestructive
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_statusARead-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_messageBIdempotent
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_sinceARead-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_eventADestructive
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_itemBDestructive
Delete a checklist item from a To Do task.
Inputs: task_id (required), checklist_item_id (required), list_id.
outlook_delete_contactCDestructive
Delete a contact by ID.
Inputs: contact_id (required).
outlook_delete_draftCDestructive
Delete a draft message by ID.
Inputs: draft_id (required).
outlook_delete_eventADestructive
Delete a calendar event by ID (cancels and notifies attendees if you're the organizer).
Inputs: event_id (required).
outlook_delete_folderADestructive
Delete a user-created mail folder by ID; refuses well-known folders (inbox, sentitems).
Inputs: folder_id (required).
outlook_delete_inbox_overrideBDestructive
Delete a Focused Inbox per-sender override rule by its ID.
Inputs: override_id (required).
outlook_delete_messageADestructive
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_taskCDestructive
Delete a task from a Microsoft To Do list.
Inputs: task_id (required), list_id.
outlook_delete_task_attachmentCDestructive
Remove an attachment from a To Do task.
Inputs: task_id (required), attachment_id (required), list_id.
outlook_download_attachmentAIdempotent
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_attachmentAIdempotent
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_keyARead-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_messageBIdempotent
Set the follow-up flag on a message. status is "flagged", "complete", or "notFlagged".
Inputs: status (required), message_id (required).
outlook_forwardCDestructive
Forward an existing message to new recipients, with optional comment.
Inputs: to (required), message_id (required), comment, is_markdown.
outlook_get_contactBRead-only
Get one full contact by ID.
Inputs: contact_id (required).
outlook_get_eventARead-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_tipsBRead-only
Pre-send check for recipients: out-of-office, delivery limits, mailbox-full warnings.
Inputs: emails (required).
outlook_get_taskARead-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_attachmentsBRead-only
List attachments on a message — returns IDs, names, sizes, and content types.
Inputs: message_id (required).
outlook_list_calendarsARead-only
List all calendars available to the authenticated user (primary + secondary).
Inputs: no named parameters.
outlook_list_categoriesARead-only
List the user's master category definitions (names + colors).
Provides the valid values for outlook_categorize_message.
Inputs: no named parameters.
outlook_list_contactsARead-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_deltaARead-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_draftsBRead-only
List messages in the Drafts folder with cursor pagination.
Inputs: count, cursor.
outlook_list_eventsARead-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_deltaARead-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_foldersARead-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_inboxARead-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_deltaARead-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_overridesARead-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_attachmentsARead-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_listsARead-only
List all Microsoft To Do task lists for the current user.
Inputs: no named parameters.
outlook_list_tasksCRead-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_threadARead-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_readAIdempotent
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_messageARead-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_messagesARead-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_attachmentADestructive
Remove a single attachment from a draft message by attachment ID.
Inputs: draft_id (required), attachment_id (required).
outlook_remove_event_attachmentADestructive
Remove one attachment from an event (IDs from outlook_get_event's attachments).
Inputs: event_id (required), attachment_id (required).
outlook_rename_folderAIdempotent
Rename a user-created mail folder by ID.
Inputs: name (required), folder_id (required).
outlook_replyBDestructive
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_rsvpADestructive
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_contactsARead-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_mailARead-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_draftADestructive
Send an existing draft (pair with outlook_create_draft for human-review send flow).
Inputs: draft_id (required).
outlook_send_messageADestructive
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_attachmentsADestructive
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_overrideAIdempotent
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_itemAIdempotent
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_eventADestructive
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_whoamiARead-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
Scored across 71 tools
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.
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.
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.
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
Related MCP Connectors
A MCP server that works with Outlook Calendar to manage event listing, reading, and updates.
A MCP server for Outlook email that lets you search, read, and draft emails and replies.
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
Related MCP Servers
- AlicenseAqualityBmaintenance22 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.22773 npm40MIT
- AlicenseNot gradedqualityDmaintenanceComprehensive MCP server for local Microsoft Outlook automation, providing 64 tools across email, calendar, contacts, tasks, notes, and Exchange features on both Windows and macOS.1MIT
- AlicenseAqualityDmaintenanceAn MCP server that provides 49 tools to access Microsoft Outlook for Mac, enabling management of mail, calendar, contacts, tasks, and notes via AppleScript.499MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for sending and managing Microsoft Outlook email via the Microsoft Graph API, including drafts, replies, contacts, and directory search.89 npmMIT