outlook-mcp
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 summarize 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
An MCP server for Microsoft 365 Outlook — mail, calendar and contacts — that talks to the same internal JSON API the Outlook web app (OWA) uses: https://outlook.cloud.microsoft/owa/service.svc.
It does not use Microsoft Graph, EWS SOAP or a browser. Every tool call is a plain HTTPS request with a bearer token, so it works anywhere Node runs and needs no app registration or admin consent beyond what Outlook on the web already has.
40 tools: read, search, send, reply, forward, drafts, attachments, folders, flags, categories, calendar events and invitations, contacts, directory lookup
Authentication through the Azure CLI by default (tokens are refreshed automatically), or any token source you provide
Read-only mode for safe exploration
Compact, normalized JSON output (UTC times, SMTP addresses, text bodies by default)
Caveat: the OWA service API is undocumented and owned by Microsoft. It has been stable for years and is what several open-source clients use, but it can change without notice. See docs/OWA-API.md for exactly what was verified and how.
Requirements
Node.js 20 or newer — Windows, macOS and Linux are all supported
A Microsoft 365 (work or school) mailbox
One of:
the Azure CLI, signed in with
az login(recommended), orsome other way to obtain an access token for
https://outlook.office.com
Related MCP server: outlook-mcp
Install
From GitHub (with the GitHub CLI)
gh repo clone uukelele/outlook-mcp
cd outlook-mcp
npm install
npm run build
az login --allow-no-subscriptions # work/school accounts often have no Azure subscription
npm run check # verifies auth and prints your mailbox identitygh itself: winget install GitHub.cli on Windows, brew install gh on macOS, or your Linux package manager — then gh auth login once.
From a local copy
npm install
npm run build
az login # if not already signed in
npm run checknpm run check prints something like:
{ "ok": true, "auth": "azure-cli", "mailbox": "you@contoso.com", "displayName": "You", "timeZone": "GMT Standard Time", "inbox": { "total": 2535, "unread": 119 }, "readOnly": false }Platform notes
The server has no native dependencies and runs anywhere Node 20+ runs, including Windows ARM64. A few platform details are handled for you:
Windows: the Azure CLI is
az.cmd; the server invokes it through the shell automatically.download_attachmentacceptsC:\...paths, andOUTLOOK_TOKEN_COMMANDruns throughcmd.exe.Time zones: user-facing zones are IANA names (e.g.
Europe/London), resolved via Node's bundled ICU, soIntlworks the same on every platform. The mailbox's own zone stays a Windows zone ID, as Exchange expects.Line endings: the repo pins LF via
.gitattributes, and the test scripts usecross-env, sonpm test/npm run test:livework in cmd and PowerShell as well as POSIX shells.macOS: install the Azure CLI with
brew install azure-cliif you don't have it.
Add it to an MCP client
OpenCode (~/.config/opencode/opencode.jsonc on macOS/Linux, %USERPROFILE%\.config\opencode\opencode.jsonc on Windows; v2 config):
{
"mcp": {
"servers": {
"outlook": {
"type": "local",
"command": ["node", "/path/to/outlook-mcp/dist/index.js"],
"disabled": false
}
}
}
}Windows path form: "command": ["node", "C:\\path\\to\\outlook-mcp\\dist\\index.js"].
Claude Desktop / other clients (mcpServers format; the config file is claude_desktop_config.json — see your client's docs):
{
"mcpServers": {
"outlook": { "command": "node", "args": ["/path/to/outlook-mcp/dist/index.js"] }
}
}Add "environment" / "env" entries for any settings below, e.g. "OUTLOOK_READ_ONLY": "1".
Authentication
The server needs a bearer token whose audience is https://outlook.office.com. Microsoft Graph tokens do not work (the server detects them and says so). Sources, in the order they are tried when OUTLOOK_AUTH is unset:
Source | Setting | Refresh |
Static token |
| No — restart with a new token when it expires (~1 h) |
Token file |
| Re-read when expired or rejected |
Command |
| Re-run when expired or rejected |
OWA cookie (experimental, untested) |
| No |
Azure CLI (default) |
| Automatic |
The Azure CLI source runs az account get-access-token --resource https://outlook.office.com. Tokens are cached in memory until five minutes before expiry and refreshed once automatically if the service rejects one. Tokens are never logged or written to disk.
Configuration
Variable | Default | Purpose |
|
| Force a source: |
| off |
|
| mailbox setting | Windows time zone ID (e.g. |
|
| Maximum attachment size for downloads and uploads |
|
| Per-request timeout |
|
| OWA origin |
|
| Attachment download host |
| from token ( | Override the |
| off |
|
Tools
IDs returned by one tool can be passed to any other. Folders can be given as a well-known name (inbox, sent, drafts, trash, junk, archive, …), a display name, a path like Inbox/Projects, or an ID.
Mailbox — get_mailbox_info, list_categories
Folders — list_folders, create_folder, rename_folder, move_folder, delete_folder
Reading mail
Tool | Notes |
| Folder listing, newest first; |
| Text, sender, recipient, subject, date range, category, unread/flagged/attachments. See Search below |
| Full message as text (default) or sanitized HTML, recipients, attachment list. Does not mark read unless asked |
| Whole conversation, oldest first, each message showing only its new text |
Writing mail — send_message, create_draft, update_draft, send_draft, reply_message, forward_message
reply_message and forward_message send immediately unless send: false, which saves a draft and returns its ID. The original message is quoted automatically.
Triage (batched, with per-item results) — mark_messages_read, flag_messages, categorize_messages, move_messages, copy_messages, delete_messages
Attachments — list_attachments, download_attachment, add_attachment, remove_attachment
download_attachment returns text files as text, images as images and other files as an embedded resource; pass savePath to write the file to disk instead. Attachments can be added from a local path, base64 or plain text.
Calendar — list_calendars, list_events, get_event, create_event, update_event, delete_event, respond_to_event
Contacts & people — list_contacts, get_contact, create_contact, update_contact, delete_contact, search_people (organization directory and personal contacts)
Behavior worth knowing
Times. Results are UTC. Inputs with an offset (
2026-11-02T14:00:00Z,+01:00) are exact. Inputs without one are local time — in the IANAtimeZoneargument if given, otherwise in the mailbox's time zone, resolved by Exchange itself (daylight saving included).Search scans the newest messages of each folder (
scanLimit, default 1000 per folder) and matches subject, sender, recipient display names and the ~250-character preview. It does not search full bodies or attachment contents. Server-side search was investigated and is not reachable with these tokens — see docs/OWA-API.md. Results say when a folder was only partly scanned; addafterto search further back cheaply.Meeting invitations. Creating an event with attendees always emails invitations — Exchange ignores "don't send" for new meetings.
update_eventanddelete_eventnotify attendees unlessnotifyAttendees: false.Sending uses Exchange's normal submission path and keeps a copy in Sent Items, exactly like Outlook on the web.
Safety. Tools carry MCP annotations (
readOnlyHint,destructiveHint,openWorldHint) so clients can ask for confirmation. The server instructions tell the model to confirm before contacting other people and to prefer drafts.OUTLOOK_READ_ONLY=1removes every tool that changes anything.
Development
npm run build # compile to dist/
npm test # 73 offline tests (fake OWA endpoint, no network)
npm run test:live # 9 live tests against your mailbox — read-only by constructionThe offline tests check payloads against the request shapes that were verified on the live service, cover the client's retry/auth/error handling, and run the full MCP protocol over an in-memory transport. The live suite starts the server in read-only mode, so write tools do not exist during the run.
src/
index.ts CLI entry (stdio server, --check, --help)
server.ts wires config → auth → client → services → tools
config.ts environment settings
auth/ token sources (Azure CLI, command, file, static, cookie) and JWT helpers
owa/client.ts HTTP client: headers, envelope, refresh-on-401, throttling, error mapping
owa/builders.ts request payload builders (__type ordering, folder refs, recipients)
owa/normalize.ts raw OWA objects → compact JSON
owa/time.ts date/time parsing and time zone handling
services/ mail, folders, attachments, calendar, contacts, mailbox
tools/ MCP tool definitions
docs/OWA-API.md protocol notes and verification recordTroubleshooting
Symptom | Fix |
| Run |
| Install with |
| Request the token with |
| Token expired or lacks mailbox access; with a static token, supply a fresh one |
| Not authenticated (often cookie mode); use a bearer token |
| A payload the service does not accept; please report it with |
License
MIT
Available Tools
40 toolsadd_attachmentAdd attachmentB
Attach a file to a draft (or to an event/contact you own).
Inputs: id (required), attachment (required).
categorize_messagesCategorize messagesA
Set, add or remove categories on messages. See list_categories for the mailbox's category names.
Inputs: ids (required), categories (required), mode.
copy_messagesCopy messagesB
Copy messages to another folder; returns the IDs of the copies.
Inputs: ids (required), destination (required).
create_contactCreate contactC
Create a personal contact.
Inputs: notes, emails, folder, company, +14 more.
create_draftCreate draftA
Save a new email in Drafts without sending it. Returns the draft ID for update_draft, add_attachment and send_draft.
Inputs: cc, to, bcc, body, +4 more.
create_eventCreate eventA
Create a calendar event. If attendees are given this is a meeting and invitations are emailed to them immediately. Set isOnlineMeeting to add a Microsoft Teams link (if the tenant allows it).
Inputs: start (required), subject (required), end, body, +13 more.
create_folderCreate folderB
Create a mail folder, optionally inside another folder.
Inputs: name (required), parent.
delete_contactDelete contactADestructive
Delete a personal contact (moved to Deleted Items unless permanent).
Inputs: id (required), permanent.
delete_eventDelete or cancel eventADestructive
Delete an event. For meetings you organize, attendees are sent a cancellation unless notifyAttendees is false. To decline someone else's meeting, use respond_to_event instead.
Inputs: id (required), permanent, notifyAttendees.
delete_folderDelete folderADestructive
Delete a folder and everything in it. By default it is moved to Deleted Items; built-in folders cannot be deleted.
Inputs: folder (required), permanent.
delete_messagesDelete messagesADestructive
Delete messages. By default they are moved to Deleted Items (recoverable); permanent deletion cannot be undone.
Inputs: ids (required), permanent.
download_attachmentDownload attachmentARead-only
Download a file attachment. With savePath the file is written to disk; otherwise text files are returned as text, images as images, and other files as an embedded base64 resource (up to 10 MB).
Inputs: id (required), name, savePath, overwrite, +1 more.
flag_messagesFlag messagesC
Set the follow-up flag on messages.
Inputs: ids (required), status (required).
forward_messageForward emailB
Forward a message (with its attachments) to new recipients. Sends immediately unless send is false.
Inputs: id (required), to (required), cc, bcc, +4 more.
get_contactGet contactBRead-only
Get all details of a personal contact.
Inputs: id (required).
get_eventGet eventARead-only
Get full event details: description, attendees with their responses, organizer, online meeting link, recurrence master.
Inputs: id (required), format, maxBodyChars.
get_mailbox_infoMailbox infoARead-only
Get the signed-in user's name, email address, time zone (Windows ID, used for times given without an offset), storage quota, and inbox/drafts counts.
Inputs: no named parameters.
get_messageRead messageARead-only
Get a message with full body (a string; see bodyFormat), recipients and file attachments (inline images are only counted; list_attachments shows them). Does not mark it read unless markAsRead is true.
Inputs: id (required), format, markAsRead, maxBodyChars.
get_threadRead conversationARead-only
Get every message in a conversation (across folders), oldest first. Each body contains only the new text of that message, without quoted history.
Inputs: messageId, maxBodyChars, conversationId.
list_attachmentsList attachmentsCRead-only
List the attachments of a message, event or contact.
Inputs: id (required).
list_calendarsList calendarsBRead-only
List the mailbox's calendars (the default one is wellKnownName "calendar").
Inputs: no named parameters.
list_categoriesList categoriesARead-only
List the mailbox's category names and colors (for categorize_messages and events).
Inputs: no named parameters.
list_contactsList contactsARead-only
List personal contacts alphabetically. Use search_people to find people by name, including the organization directory.
Inputs: limit, folder, offset.
list_eventsList eventsARead-only
List calendar events (recurring events are expanded into occurrences) that overlap a time range, sorted by start. Defaults to the next 7 days from today (UTC). Returned times are UTC.
Inputs: end, limit, start, calendar, +1 more.
list_foldersList foldersARead-only
List mailbox folders with their paths, IDs, well-known names and item/unread counts. Use the returned path or ID wherever a folder is expected.
Inputs: kind, refresh.
list_messagesList messagesARead-only
List messages in a folder, newest first, with sender, subject, preview, read/flag state and IDs. Page with offset/nextOffset. Times are UTC.
Inputs: limit, order, filter, folder, +1 more.
mark_messages_readMark read/unreadB
Mark messages as read or unread (no read receipts are sent).
Inputs: ids (required), read (required).
move_folderMove folderB
Move a folder (with its contents) into another folder.
Inputs: folder (required), destination (required).
move_messagesMove messagesB
Move messages to another folder (e.g. archive). Message IDs stay valid after moving.
Inputs: ids (required), destination (required).
remove_attachmentRemove attachmentADestructive
Remove an attachment from a draft (or from an event/contact you own).
Inputs: attachmentId (required).
rename_folderRename folderC
Rename a folder.
Inputs: name (required), folder (required).
reply_messageReply to emailA
Reply (or reply-all) to a message. The original is quoted below your text. Sends immediately unless send is false, in which case a draft is saved and its ID returned.
Inputs: id (required), body (required), send, replyAll, +2 more.
respond_to_eventRespond to invitationA
Accept, tentatively accept or decline a meeting invitation, optionally with a message to the organizer.
Inputs: id (required), response (required), send, message.
search_messagesSearch messagesARead-only
Find messages by text, sender, recipient, subject, date, category, read/flag state or attachments. Works by scanning the newest messages of each folder (scanLimit per folder) and matching subject, sender, recipient display names and the ~250-character preview; it does not search full bodies or attachment contents. All given criteria must match. Searches all mail folders except Deleted Items, Junk, Drafts and Outbox unless folders is given.
Inputs: to, from, text, after, +9 more.
search_peopleSearch peopleARead-only
Find people by name or email address in the organization directory (global address list) and/or personal contacts. Useful for looking up someone's email address before sending.
Inputs: query (required), limit, source.
send_draftSend draftB
Send an existing draft (including reply/forward drafts).
Inputs: id (required).
send_messageSend emailA
Compose and immediately send a new email (a copy is saved in Sent Items). Use create_draft instead if the user wants to review it first.
Inputs: to (required), body (required), subject (required), cc, +4 more.
update_contactUpdate contactA
Update a personal contact. Only given fields change; an empty string clears a field and emails replaces all addresses.
Inputs: id (required), notes, emails, company, +14 more.
update_draftUpdate draftA
Change a draft's subject, body, importance or recipients. Recipient lists replace the existing ones; an empty list clears them.
Inputs: id (required), cc, to, bcc, +4 more.
update_eventUpdate eventA
Change an event you organize. Only given fields change; attendee lists replace the existing ones. For meetings, attendees are sent an update unless notifyAttendees is false.
Inputs: id (required), end, body, start, +12 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 40 tools
Tools are cleanly separated along resource+action lines: message read paths (list/search/get/get_thread), draft lifecycle (create/update/send_draft vs send_message/reply/forward), and folder/calendar/contact operations never collide. Near-overlaps like delete_messages vs move_messages or search_people vs list_contacts are explicitly disambiguated in the descriptions, and even attachment listing vs downloading is distinguished.
Every tool follows a strict snake_case verb_noun pattern (list_folders, get_message, create_event, delete_contact, mark_messages_read). Plurals and resource nouns are used consistently so the target object is always obvious from the name.
40 tools is well above the well-scoped range; the surface is large because it spans mail, drafts, folders, attachments, calendar, contacts and categories in one server. Each tool is individually justified, but the volume forces an agent to sift through a broad catalog for routine tasks.
Lifecycle coverage is strong: mail read/search/send/draft/reply/forward/flag/categorize/move/copy/delete, folder CRUD+move, attachment add/remove/list/download, event CRUD plus respond_to_event, and contact CRUD plus directory search. Remaining gaps are peripheral (inbox rules, out-of-office, creating/deleting categories or calendars, bulk event ops).
Maintenance
Related MCP Connectors
Manage Microsoft 365 email, calendar, contacts and inbox rules via the Graph API with OAuth 2.0.
Email, calendar and contacts for AI agents: Gmail, Microsoft 365 and IMAP accounts behind one API.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Read email/chat conversations, messages, contacts and teams; draft, send and update threads.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables interaction with Outlook Web through its internal API, supporting email search, folder listing, email retrieval, read state changes, calendar events, and reply drafts without Microsoft Graph or COM.71MIT
- FlicenseNot gradedqualityCmaintenanceReads and searches your local Microsoft Outlook desktop mailbox via COM, supporting folder listing, message/thread retrieval, attachment saving, bulk export, and draft creation without sending, requiring no OAuth or admin consent.-
- AlicenseNot gradedqualityBmaintenanceEnables headless reading of Microsoft 365 mail, calendar, Teams chats and channels, OneDrive, SharePoint and OneNote over Microsoft Graph using a single password-plus-TOTP sign-in. No app registration or admin consent is needed, since it brokers pre-consented first-party clients from one FOCI refresh token.307 PyPI2MIT
- AlicenseAqualityBmaintenanceEnables Claude, Codex and other MCP clients to browse folders, search, read, send, reply to, forward, move, flag and delete Microsoft 365 / Outlook.com mail through the Microsoft Graph API, including attachment downloads, newsletter unsubscribe and inbox rules. Signs in with the OAuth device code flow and keeps the refresh token in the OS keychain, with an optional read-only mode that removes every mutating tool.26136 npmMIT