office-outlook-mcp

MCP server for Outlook / Microsoft 365 — mail, folders, calendar, contacts and tasks, with confirmation-gated sending.

This project was developed and is maintained by AI (Claude Code). Use at your own discretion.

How it authenticates

Outlook Web holds its access token in memory and sends it as Authorization: Bearer …. This server snapshots that header from your signed-in browser tab through the fetchproxy bridge, then talks to https://outlook.office.com/api/v2.0 with ordinary server-side requests.

The browser is needed only to mint the token (~25h), never to make a call. That is the whole design: no Azure app registration, no admin consent, and no browser on the request path.

Tokens are cached at ~/.office-outlook-mcp/token.json (0600), so a restart does not re-capture.

Install

npm i -g @chrischall/office-outlook-mcp

Requires the ContextMint Bridge browser extension, installed from its releases: in Chrome, unzip the chrome build and load it unpacked (chrome://extensions → Developer mode → Load unpacked). Safari is not available yet — it will ship inside the ContextMint app, which has no public download — so use Chrome for now.

ContextMint Bridge is the fetchproxy browser extension under its new name, from the same maintainer — fetchproxy's own README (#extension) points to it. Its source is public at nullnet-app/contextmint-bridge: build it yourself, or check a release zip against the .sha256 file published beside it (shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256).

The extension, fpx and this server are compatible by fetchproxy protocol number (currently protocol 4), not by matching package versions. Keep the bridge and fpx current — a mismatch fails with an error naming both protocol numbers. Also install @fetchproxy/cli:

npm i -g @fetchproxy/cli

The first capture prints a 6-digit pair code to approve in the ContextMint Bridge popup; the grant persists.

Install in opencode

opencode reads MCP servers from opencode.json (project) or ~/.config/opencode/opencode.json (global):

{
  "mcp": {
    "servers": {
      "outlook": {
        "type": "local",
        "command": ["npx", "-y", "@chrischall/office-outlook-mcp"]
      }
    }
  }
}

That one file serves opencode 2 and current opencode 1 — verified live on 2.0.11, 1.18.31 and 1.18.28, which all connect from it.

Two things worth knowing, both measured rather than assumed:

• Never carry both config shapes in one file. Older opencode 1 wants the servers directly under mcp ("mcp": { "outlook": { … } }), and the temptation is to write both so either version finds one. Do not: given a sibling key beside servers, opencode 2 parses the file — it still shows up in opencode debug config — and then reports "No MCP servers configured". No error, no warning, every server silently gone.
• An opencode 1 old enough to reject servers says so loudly (Configuration is invalid at …), so if you see that, switch that machine to the flat shape rather than combining them.

opencode 2 talks to a background service, so opencode reload before opencode mcp list after editing config.

Configuration

Everything is optional — with nothing set, the server captures from the browser.

Tools

Read — outlook_list_folders, outlook_list_messages, outlook_get_message, outlook_get_unread, outlook_list_attachments, outlook_get_attachment, outlook_list_events, outlook_get_event, outlook_list_calendars, outlook_find_meeting_times, outlook_get_schedule, outlook_get_profile, outlook_get_mailbox_settings, outlook_list_contacts, outlook_list_people, outlook_list_categories, outlook_list_tasks

Write (ask you to confirm first — see Confirmations) — outlook_send_mail, outlook_create_draft, outlook_mark_read, outlook_update_message, outlook_move_message, outlook_create_event, outlook_update_event, outlook_respond_to_invite, outlook_delete_event, outlook_reply. Three skip the confirmation when nothing reaches anyone else: outlook_reply with draftOnly: true (the reply stays in Drafts), outlook_respond_to_invite with sendResponse: false, and outlook_delete_event on your own appointment with no attendees or on a meeting the organizer already cancelled (in each, only your calendar changes).

Meetings — outlook_find_meeting_times asks Outlook's Scheduling Assistant for slots when everyone is free, and outlook_get_schedule shows each person's busy blocks. Each suggested slot carries createEventArgs, which outlook_create_event accepts unchanged. outlook_create_event and outlook_update_event attach a Microsoft Teams meeting by default and return its join link; pass teamsMeeting: false to leave it off. Only the organizer can update a meeting. outlook_respond_to_invite accepts, tentatively accepts or declines an invite, by its message id or its event id. outlook_delete_event deletes an event you organize — one occurrence by the occurrence's id, or the whole series by its series master's id — and sends any attendees a cancellation; for an invite you received it refuses and points you at declining instead. outlook_list_events and outlook_get_event show what that decision needs in every view: MyResponse, ResponseRequested, IsOrganizer, IsCancelled, Type (SingleInstance, Occurrence, Exception or SeriesMaster), ShowAs and IsAllDay, plus SeriesMasterId in the full view.

Diagnostics — outlook_healthcheck

Every read tool takes view: compact | full | raw, defaulting to compact. Mutating tools write nothing until you confirm (bar the cases above) — see Confirmations. The preview shows exactly what would be sent (action, method, path and body). (outlook_create_event first reads the mailbox time zone, so its preview can name the zone it would book in; that is the one read a preview makes.)

Mail and event text is written by other people, so outlook_list_messages, outlook_get_message, outlook_get_unread, outlook_get_attachment, outlook_list_events, outlook_get_event, outlook_find_meeting_times and outlook_get_schedule wrap every result (all views) in an untrusted-content envelope — untrusted_content: true plus a note telling the model to treat the text as data, never instructions (a view: raw record that carries its own untrusted_content/note key is nested under data, so it cannot overwrite the envelope). outlook_reply returns a sent reply's subject — the original sender's text — inside the same envelope. On a client that cannot show a confirmation prompt, the confirmToken is still something the model passes back itself, so keep MCP_CONFIRM_MODE=ask-user (the default) and approve each preview in chat — or use a client that asks you before running non-read-only tools — as the real guard on outbound sends.

Triage loop

An agent can work through new mail end to end without opening Outlook:

1. Read the batch — outlook_get_unread returns the unread messages in a folder (default inbox), newest first, each with its plain-text body, in one call. It does not mark anything read. Each item has a kind: mail, meetingRequest, meetingCancelled or meetingResponse; requests and cancellations also carry the linked event (time, organizer, your current response) — or, when the meeting is no longer on your calendar (already declined, cancelled or deleted), a hint saying there is nothing to respond to. to and cc list at most 20 addresses, with toCount/ccCount when there are more.
2. Act on each item —
   • an invite: outlook_respond_to_invite with the message id and accept, tentative or decline (and an optional comment). Once you respond, Outlook moves the invite message to Deleted Items under a new id, so an answered invite is already filed — skip steps 3 and 4 for it (its old id would 404);
   • a message that needs an answer: outlook_reply (reply, replyAll or forward), or draftOnly: true to leave it in Drafts for you to review;
   • a request for a meeting: outlook_find_meeting_times for the attendees, then pass the chosen slot's createEventArgs to outlook_create_event;
   • an attachment to read: outlook_get_attachment.
3. File it — outlook_update_message flags, categorises (names from outlook_list_categories) and marks read up to 50 messages in one call; outlook_move_message moves one to another folder.
4. Mark it handled — outlook_mark_read (or isRead: true on outlook_update_message) on the plain mail you handled, so the next outlook_get_unread returns only what is still new. Answered invites are already out of the inbox (see step 2).

Replies, forwards, invite responses and new meetings reach other people, so each asks you to confirm first — except a reply saved with draftOnly: true (it stays in Drafts until you send it) and an invite response with sendResponse: false (only your calendar changes; the organizer is not told).

Confirmations

Every write asks you to confirm before anything is sent or changed (except a draft-only reply and a silent invite response — see Tools). A client that can show a confirmation prompt (Claude Code) shows one. On a client that cannot, the first call does nothing and returns a confirmation-required preview plus a confirmToken; only a repeat call with that token performs the write. The token is single-use, expires, and is bound to the exact arguments — change anything between the two calls and it is refused (DRAFT_CHANGED) with a fresh preview.

Things worth knowing

• Fields are PascalCase (ReceivedDateTime, IsRead). This is the Outlook REST API, not Graph — a Graph snippet silently returns nothing.
• outlook_get_message returns a plain-text body by default, measured 9.4× smaller than the HTML; pass html: true for the original.
• outlook_list_events uses the calendar view, which expands recurring series. /me/events does not, which is why it is not exposed as-is.
• Time zones are Windows names (Eastern Standard Time), not IANA.
• search and unreadOnly cannot be combined; the API rejects $search alongside $filter, so the tool refuses before making a doomed request.
• Moving a message assigns it a new id.
• outlook_list_events returns times in the mailbox's own time zone unless timeZone overrides it. The API itself defaults to UTC, which silently reads as a four-hour error on an Eastern mailbox.
• Contact phone fields are MobilePhone1, not Graph's MobilePhone. The v2.0 Contact type rejects the Graph name with a 400.

The lightweight alternative

If you only need Outlook access from Claude Code on this machine, the skills/outlook-fpx access skill in this repo does the same reads with fpx + curl and no server at all. The MCP earns its keep when you want typed tools, confirmation-gated writes, or reach from claude.ai.

Development

npm install
npm run build
npm test              # typecheck + suite
npm run test:coverage # CI's gate

Request shapes are pinned in docs/OUTLOOK-API.md, all verified against a live mailbox.

License

MIT