Skip to main content
Glama

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), or

    • some 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 identity

gh 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 check

npm 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_attachment accepts C:\... paths, and OUTLOOK_TOKEN_COMMAND runs through cmd.exe.

  • Time zones: user-facing zones are IANA names (e.g. Europe/London), resolved via Node's bundled ICU, so Intl works 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 use cross-env, so npm test / npm run test:live work in cmd and PowerShell as well as POSIX shells.

  • macOS: install the Azure CLI with brew install azure-cli if 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

OUTLOOK_ACCESS_TOKEN

No — restart with a new token when it expires (~1 h)

Token file

OUTLOOK_TOKEN_FILE (raw token or JSON with accessToken/access_token)

Re-read when expired or rejected

Command

OUTLOOK_TOKEN_COMMAND (prints a token or JSON)

Re-run when expired or rejected

OWA cookie (experimental, untested)

OUTLOOK_COOKIE (+ OUTLOOK_CANARY)

No

Azure CLI (default)

OUTLOOK_AZ_TENANT optional

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

OUTLOOK_AUTH

auto

Force a source: azure-cli, token, token-file, command, cookie

OUTLOOK_READ_ONLY

off

1 registers only the 15 read-only tools

OUTLOOK_TIMEZONE

mailbox setting

Windows time zone ID (e.g. GMT Standard Time) for times given without an offset

OUTLOOK_MAX_DOWNLOAD_MB

25

Maximum attachment size for downloads and uploads

OUTLOOK_REQUEST_TIMEOUT_MS

30000

Per-request timeout

OUTLOOK_ORIGIN

https://outlook.cloud.microsoft

OWA origin

OUTLOOK_ATTACHMENTS_ORIGIN

https://attachments.office.net

Attachment download host

OUTLOOK_ANCHOR_MAILBOX

from token (PUID:…@tenant)

Override the X-AnchorMailbox routing header

OUTLOOK_DEBUG

off

1 logs each request (action and status only) to stderr

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

list_messages

Folder listing, newest first; filter = unread / flagged / toOrCcMe; paging via offset/nextOffset

search_messages

Text, sender, recipient, subject, date range, category, unread/flagged/attachments. See Search below

get_message

Full message as text (default) or sanitized HTML, recipients, attachment list. Does not mark read unless asked

get_thread

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 IANA timeZone argument 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; add after to search further back cheaply.

  • Meeting invitations. Creating an event with attendees always emails invitations — Exchange ignores "don't send" for new meetings. update_event and delete_event notify attendees unless notifyAttendees: 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=1 removes 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 construction

The 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 record

Troubleshooting

Symptom

Fix

Azure CLI could not issue an Outlook token

Run az login — with a work/school account that has no Azure subscription, use az login --allow-no-subscriptions

az not found on Windows

Install with winget install Microsoft.AzureCLI (or the MSI), then reopen the terminal so az.cmd is on PATH

token is for Microsoft Graph

Request the token with --resource https://outlook.office.com

Outlook rejected the credentials … (HTTP 401)

Token expired or lacks mailbox access; with a static token, supply a fresh one

returned an HTML page instead of JSON

Not authenticated (often cookie mode); use a bearer token

… (the service rejected the request shape)

A payload the service does not accept; please report it with OUTLOOK_DEBUG=1 output

License

MIT

Available Tools

40 tools
add_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 contactA
Destructive

Delete a personal contact (moved to Deleted Items unless permanent).

Inputs: id (required), permanent.

delete_eventDelete or cancel eventA
Destructive

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 folderA
Destructive

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 messagesA
Destructive

Delete messages. By default they are moved to Deleted Items (recoverable); permanent deletion cannot be undone.

Inputs: ids (required), permanent.

download_attachmentDownload attachmentA
Read-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 contactB
Read-only

Get all details of a personal contact.

Inputs: id (required).

get_eventGet eventA
Read-only

Get full event details: description, attendees with their responses, organizer, online meeting link, recurrence master.

Inputs: id (required), format, maxBodyChars.

get_mailbox_infoMailbox infoA
Read-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 messageA
Read-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 conversationA
Read-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 attachmentsC
Read-only

List the attachments of a message, event or contact.

Inputs: id (required).

list_calendarsList calendarsB
Read-only

List the mailbox's calendars (the default one is wellKnownName "calendar").

Inputs: no named parameters.

list_categoriesList categoriesA
Read-only

List the mailbox's category names and colors (for categorize_messages and events).

Inputs: no named parameters.

list_contactsList contactsA
Read-only

List personal contacts alphabetically. Use search_people to find people by name, including the organization directory.

Inputs: limit, folder, offset.

list_eventsList eventsA
Read-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 foldersA
Read-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 messagesA
Read-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 attachmentA
Destructive

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 messagesA
Read-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 peopleA
Read-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

    B3.4/5.0

    Scored across 40 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      7
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Reads 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.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 PyPI
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      26
      136 npm
      MIT