MCP server for Outlook personal accounts (Hotmail/Outlook.com) via Microsoft Graph API
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.
One-click editor setup isn’t available for this listing yet — we don’t have a confirmed install command, and we’d rather show nothing than point your editor at the wrong package or host. Follow the project’s own setup instructions, linked above.
Manual Client & Custom JSON ConfigExpand JSON ▾
No confirmed setup config for this listing yet. We only publish a config block when the install details come from the project itself — its README, its docs, or a verified owner. We haven’t found those for outlook-mac-mcp, and we’d rather show nothing than a guess you’d paste into your client. Follow the project’s own setup instructions for the current steps.
Documentation Overview
outlook-mac-mcp
MCP server for Microsoft Outlook, built for personal Microsoft accounts (Hotmail, Outlook.com, Live) that run on the consumer infrastructure rather than Exchange Online — and are therefore not supported by the official "Claude for Outlook" add-in nor by the Microsoft 365 connector.
Backend: Microsoft Graph API with delegated, user-consented, least-privilege scopes.
Python, transport stdio, no telemetry.
Why not AppleScript
Community MCP servers for Outlook on Mac drive the app through AppleScript. That path only works with Legacy Outlook. In August 2026 Microsoft cancelled the planned AppleScript support in New Outlook, and the transition to New Outlook ends in October 2026. This project deliberately does not depend on it.
The reference environment for this project runs New Outlook (the "Legacy Outlook" toggle is present in the Outlook menu), where AppleScript automation is unavailable. This was the deciding factor.
Technical requirements
Runtime
| Component | Requirement | Notes |
|---|---|---|
| macOS | 13 Ventura or later | Keychain used for token storage |
| Python | 3.12+ | Managed with uv; dependencies pinned in uv.lock |
| MCP client | Any stdio client (Claude Desktop, Claude Code) | Tested against Claude Desktop |
| Network | HTTPS to login.microsoftonline.com and graph.microsoft.com only | No other outbound calls |
Microsoft account and app registration
| Item | Requirement |
|---|---|
| Account type | Personal Microsoft account (Hotmail / Outlook.com / Live) or work/school |
| App registration | One-time registration in Microsoft Entra ID (free; a personal account needs its own tenant, created via the Azure Portal) |
| Supported account types | "Accounts in any organizational directory and personal Microsoft accounts" |
| Authentication | Device-code flow (MSAL, public client, no client secret) |
| Authority | https://login.microsoftonline.com/consumers |
| Scopes requested by default | Mail.Read, Calendars.Read, Contacts.Read, offline_access, User.Read |
Scope added by OUTLOOK_MCP_ENABLE_CALENDAR_WRITE=true | Calendars.ReadWrite (see Optional: calendar write) |
| Admin consent | Not required — every scope above is user-consentable |
offline_access, openid and profile are reserved scopes: MSAL appends them
to every request on its own and raises if they are passed explicitly. They are
consented at the registration but never appear in the list the code asks for —
that consent is what yields the refresh token behind the Keychain cache.
The app registration may list broader permissions than the server requests. The token only ever carries the scopes the running configuration asks for: the write scope is requested only behind a config flag that is off by default, and turning it on triggers a new sign-in and consent prompt.
Not required
- Microsoft Outlook desktop app (the server talks to Graph, not to the app)
- Exchange Online / Microsoft 365 business tenant
- Accessibility or Automation permissions on macOS
- Node.js, Bun, or any non-Python runtime
Validated environments
Ordered chronologically by validation date (oldest first).
| Version | OS | Python | MCP client | Account type | Outlook app installed | Status |
|---|---|---|---|---|---|---|
| 0.1.0 | macOS 27.0 (Golden Gate), Apple M5 | 3.14.7 | Claude Desktop | Personal (@hotmail.com) | Outlook for Mac 16.112.4 (26090911), New Outlook, M365 Subscription — not used by the server | validated 2026-09-14 |
| 0.2.0 (calendar write on) | macOS 27.0 (Golden Gate), Apple M5 | 3.14.7 | Claude Desktop | Personal (@hotmail.com) | as above | validated 2026-09-15 |
| 0.9.0 (through delete_event) | macOS 27.0 (Golden Gate), Apple M5 | 3.14.7 | Claude Desktop | Personal (@hotmail.com) | as above | validated 2026-09-17 |
A row moves to validated only after the tools it names return correct results on that environment, against a real mailbox. Contributions of new rows are welcome — please include exact versions.
Validated tools
Sorted alphabetically by tool name. One shipped tool is not in this table yet — it has unit and respx coverage but no live validation against a real mailbox:
search_contacts— no contact exists in the test mailbox to search for yet.
| Tool | Validated | What was checked |
|---|---|---|
count_emails | 2026-09-15 | A received-time range covering one month returned an exact count. |
create_event | 2026-09-15, 2026-09-16, 2026-09-17 | Created a timed event and an all-day event; Graph accepted the all-day payload with the resolved zone's name, and both came back readable. A body from the preview was written to the created event correctly. An event with no body at all also succeeded, confirming the fix for Graph defaulting an unsent body to HTML. |
delete_event | 2026-09-17 | Deleted the event previewed under preview_event_deletion's token; confirmed removed from the calendar directly in Outlook. |
get_email | 2026-09-14 | Text body returned with the Prefer header honoured; the malformed id nope came back as ErrorInvalidIdMalformed and was mapped to InvalidRequestError. |
list_emails | 2026-09-15 | sort=oldest, limit=1 returned the folder's earliest email with an exact total; an exact-sender filter with sort=newest returned exactly one match, and Graph accepted the sender filter combined with $orderby without an InefficientFilter error. |
list_folders | 2026-09-17 | Discovered 100+ custom folders correctly, including several levels of nesting, each with accurate per-folder unread/total counts. Confirmed the documented limitation live: a Microsoft-managed folder with no well-known flag (Deleted Items) appeared in custom as expected, alongside genuine user-created folders. |
list_largest_emails | 2026-09-16 | Returned ranked results with real sizes from the extended property, skipped near zero. |
list_todays_events | 2026-09-15 | Returned zero events, exact, on a free day. |
list_unread_emails | 2026-09-14 | Reads a Hotmail inbox through Graph. |
list_upcoming_events | 2026-09-15 | Returned the matching events, earliest first; confirmed both an all-day event and a timed event mapped correctly in the resolved time zone. |
preview_event | 2026-09-15, 2026-09-16 | Summary and token for a timed and an all-day event; a body well under the truncation threshold showed in full, verbatim, in the preview. |
preview_event_deletion | 2026-09-17 | Showed the complete event (every field, unabbreviated) with the irreversibility warning before any deletion happened. |
preview_event_update | 2026-09-17 | A time change (10:00–10:30 -> 11:00–11:30) produced a diff summary showing only the changed field, old value -> new value. |
search_emails | 2026-09-14, 2026-09-15, 2026-09-17 | A term matching several emails returned an exact total; scope=subject and scope=sender each returned a narrower, still-exact subset; a term trying to break out of the phrase returned empty with no 400. Passing next_page_token back as page_token returned a genuinely different second page (a different date window, no items repeated from the first), with total/total_is_exact still accurate on that page. |
top_senders | 2026-09-15 | A full inbox scan hit the configured ceiling with coverage_is_complete=false; the client reported the partial coverage explicitly, as the description asks. |
update_event | 2026-09-17 | Applied the previewed time change (10:00–10:30 -> 11:00–11:30) exactly; the updated event reflected only that change. |
Every tool below has been validated against a real mailbox on the environment above;
search_contacts has unit and respx coverage but no live validation yet (see above).
Search quoting is additionally covered by a live positive-control check, see
Integration tests.
Scope
- v1 (read-only): unread emails, emails by folder (well-known or custom, by full path), search by term, read one email by id (body included), list folders, today's / upcoming events, contact search.
- v2: create and update calendar events — behind a config flag, off by default; delete calendar events — behind a second flag, off by default even when the first one is on; mark as read — not yet built.
- v3: send email — behind a config flag, off by default, with explicit per-call confirmation.
Tools
Read tools are always registered. The four tools marked v2, flagged register only
when OUTLOOK_MCP_ENABLE_CALENDAR_WRITE=true (see
Optional: calendar write). preview_event_deletion and
delete_event, marked v2, flagged + calendar delete, additionally need
OUTLOOK_MCP_ENABLE_CALENDAR_DELETE=true (see
Optional: calendar delete). Sorted alphabetically by tool name.
Related MCP Servers
Reviews
No reviews yet — be the first to share how this listing worked for you.
Frequently Asked Questions about Outlook Mac MCP
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/outlook-mac-mcp)HTML Embed
<a href="https://allmcps.com/mcp/outlook-mac-mcp"><img src="https://allmcps.com/api/badge/outlook-mac-mcp?style=directory" alt="Outlook Mac MCP on AllMCPs" /></a>