Outlook MCP

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.

---

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 77 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.

---

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 77 discrete tools (71 load by default; the four rule tools, document reader and MIME export are opt-in) so the agent can compose its own workflow — read, triage, write, schedule, track tasks — without hardcoded macros.

Works With

• [OpenClaw](https://openclaw.ai) — native MCP support, available via ClawHub
• [Claude Code](https://claude.com/claude-code) — claude mcp add outlook -- outlook-mcp
• [Cursor](https://cursor.com) — 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.

• 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.
• Attachments as text (1.28): PDFs, spreadsheets and text files come back as readable text, parsed in a separate process with memory and time limits. Off unless you turn it on. Since 1.31.2 it requires pypdf 6.21.4, which fixes seven ways a crafted PDF could hang a read or use too much memory.
• 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.
• Mail (1.27–1.28): write in Markdown, and replies keep their formatting and the quoted original. Start a draft as a reply or forward, name folders by path (Inbox/Travel/Flights), and see whether Microsoft verified a sender. Reading a message as text returns plain text, not the HTML behind it (1.31.1).
• 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

77 tools across 14 categories. 71 load by default; the four rule tools, document reader and MIME export 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 (7) -- list, search, get, create, update, delete, delta-sync changes
• 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