Skip to main content
Glama
new-outlook-mcp

new-outlook-mcp

by michalhron

A local, read-only MCP server that lets Claude search and read your Outlook for Mac mail and calendar. It works only from files Outlook already keeps on your Mac. It uses no online API.

Why it exists

Three things changed at once:

  • New Outlook for Mac has no AppleScript, so the usual way to script Outlook is gone.

  • Legacy Outlook for Mac can no longer connect to Exchange Online, because Microsoft retired EWS in October 2026.

  • The Microsoft 365 (Graph) connector needs an administrator to grant consent. Many universities and companies do not grant it, and some offer no IMAP either.

Outlook still keeps a lot on disk: the frozen archive of the legacy client, New Outlook's cache, and cached attachments. This project copies those files, decodes them into its own searchable archive, and gives Claude read-only tools over that archive. It never talks to Microsoft's servers and never reuses Outlook's tokens.

Related MCP server: Outlook Classic MCP server

What you get

How it works

Every sync copies Outlook's database files to a private folder and parses the copy. Nothing ever writes to Outlook's folders. The only network requests are the ICS links you add and the one-time model download for search by meaning.

Search by meaning

Keyword search needs the words that are in the message. Search by meaning needs only a description. Ask for "the email where someone suggested reframing the hype paper" and it can find a message that never uses the word reframing. A question in English finds Czech, Danish, Dutch or Finnish mail.

It runs on your Mac with a local model and adds two tools, semantic_search and find_similar, plus a hybrid mode for search_emails. Hybrid search ranks by meaning and by keywords and merges the two lists, so exact names and paraphrases both come up. Each result shows the passage that matched, whether in the body, the subject or an attachment. Setup is one command, new-outlook embed --download. Details in docs/semantic-search.md.

Quick start

Requires macOS, Python 3.12 or newer, and pipx.

pipx install 'new-outlook-mcp[watch,semantic] @ git+https://github.com/michalhron/new-outlook-mcp.git'

new-outlook backup-legacy ~/new-outlook-legacy-backup
new-outlook sync --source legacy --legacy-dir ~/new-outlook-legacy-backup
new-outlook sync --source hxstore
new-outlook launchd install --watch      # near-live sync
new-outlook embed --download             # optional: search by meaning

claude mcp add new-outlook -- new-outlook-mcp

The full walk-through, including the macOS permission prompt and Claude Desktop, is in docs/getting-started.md. To check the import on your Mac first, see docs/validation.md.

Tools at a glance

Area

Tools

Mail

search_emails, semantic_search, find_similar, get_email, get_thread, list_recent, list_folders

Attachments

list_attachments, get_attachment, search_files

Calendar

list_calendar_events, get_calendar_event, search_calendar, calendar_freebusy, find_free_slots, meeting_prep

Drafts

create_draft (opens a draft in Outlook, with attachments if you give any), create_reply_draft (a draft answering an archived email), create_event_draft (opens an .ics file)

Status

archive_status, sync_now, diagnose

Parameters and examples: docs/tools.md.

Documentation

Using it:

  • Getting started: install, permissions, first sync, connecting Claude, the watcher, configuration.

  • Tool reference: every tool and its parameters, keyword search syntax.

  • Search by meaning: set up, use, and how chunking, embedding and hybrid ranking work.

  • Calendar: sources, the published ICS feed, timezones, free time.

  • Safety and privacy: what the project does with your mail, privacy scopes, purging.

  • Data sources: what each Outlook source holds, how they merge, orphan files, changing institutions.

  • Checking the import: validate, experiments, coverage, status.

  • Limitations and maintenance: known gaps, and what to do when an Outlook update breaks the import.

Changing the code:

Development

python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
.venv/bin/ruff check --select F,E9,B --ignore B008,B905 src tests

All test data is synthetic. Never commit real mailbox files.

Credits and prior work

Microsoft documents neither format. This project builds on people who looked first, all under the MIT license:

The decoders here were written for this project from those descriptions and checked on real stores. Where our findings differ (for example the block header length), docs/hxstore-notes.md says so.

License

MIT

Available Tools

22 tools
archive_statusB
Read-onlyIdempotent

Archive size, date coverage per source (legacy, hxstore) and the last sync per source.

Inputs: no named parameters.

calendar_freebusyB
Read-onlyIdempotent

My own busy blocks and free time within working hours. Other people's calendars are not available.

Inputs: start (required), end, timezone, weekdays, +2 more.

create_draftA

Open a prefilled draft in Outlook, even if another app is the default mail app. It never sends: the user reviews and sends the draft manually. route says how it was opened and attachments_in_draft whether the files really are in it. If that is false, tell the user to drag them in from Finder.

Inputs: to (required), cc, bcc, body, +2 more.

create_event_draftA

EXPERIMENTAL. Open a new-event draft (.ics) in Outlook for the user to review and save. It does not add, change or delete anything in the calendar and sends no invitations.

Inputs: start (required), subject (required), end, body, +4 more.

create_reply_draftA

Open a draft answering an archived email, with recipients, Re: subject and the original quoted. It never sends: the user reviews and sends it. It is a new message, not linked to the thread (in_thread is false), because Outlook offers no way to reply to a recent message by script: tell the user.

Inputs: email_id (required), body, reply_all, attachments, +1 more.

diagnoseA
Read-onlyIdempotent

Run when sync fails, results look stale or a tool errors: checks whether this server may read Outlook's files, whether the cache layout matches the decoder, archive age and the sync agents. Each problem comes with a fix to pass on to the user.

Inputs: check_layout.

find_free_slotsC
Read-onlyIdempotent

Find free slots of a given length in my own calendar.

Inputs: start (required), duration_minutes (required), end, timezone, +4 more.

find_similarB
Read-onlyIdempotent

Find emails similar in content to an email or to one attachment. Give exactly one of the two ids.

Inputs: limit, email_id, attachment_id.

get_attachmentA
Read-onlyIdempotent

Read an attachment from local storage. Never downloads from a server: if the file is not on this Mac, the result says so. Ids like 'orphan:12' are files that no archived message owns: their text stays available even after Outlook deletes the file.

Inputs: attachment_id (required), mode, offset, max_chars.

get_calendar_eventA
Read-onlyIdempotent

Full details of one event: times, attendees and responses, body, meeting link, recurrence.

Inputs: event_id (required), timezone.

get_emailA
Read-onlyIdempotent

Get one email: metadata, attachment list and plain-text body (paged with offset).

Inputs: email_id (required), offset, max_chars, include_headers.

get_threadA
Read-onlyIdempotent

Get the conversation containing a message, oldest first. Uses Message-ID/References/In-Reply-To, the Outlook conversation id, and falls back to the normalized subject.

Inputs: email_id (required), body_chars, max_messages, subject_fallback.

list_attachmentsA
Read-onlyIdempotent

List an email's attachments: name, type, size, and whether the file is on this Mac.

Inputs: email_id (required), include_inline.

list_calendar_eventsB
Read-onlyIdempotent

List calendar event occurrences in a date range (recurring events are expanded).

Inputs: start (required), end, limit, account, +3 more.

list_foldersA
Read-onlyIdempotent

List folders with message counts and date ranges.

Inputs: no named parameters.

list_recentC
Read-onlyIdempotent

List the newest archived emails. freshness and warning work as in search_emails.

Inputs: days, limit, folder, account.

meeting_prepB
Read-onlyIdempotent

Prepare for a meeting: event details, attendees, and recent email threads with them or on the topic.

Inputs: event_id (required), timezone, days_back, max_threads.

search_calendarC
Read-onlyIdempotent

Search calendar events.

Inputs: query (required), limit, date_to, timezone, +1 more.

search_emailsA
Read-onlyIdempotent

Search archived emails. Returns summaries with an id for get_email/get_thread. freshness says how current the archive is. If warning is present the archive may be missing newer mail: tell the user.

Inputs: mode, sort, limit, query, +10 more.

search_filesA
Read-onlyIdempotent

Search files in Outlook's Files/ cache that belong to no archived message (attachments and bodies of mail that has left the cache). Read one with get_attachment using its attachment_id ('orphan:'). Dates are file dates, not send dates. Use search_emails for mail itself.

Inputs: kind, limit, query, offset, +2 more.

sync_nowA
Idempotent

Import new mail and calendar data from local Outlook files into the archive. Reads copies of Outlook's files only. The one network access is the user's own published ICS feeds, if configured.

Inputs: source.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools have clearly distinct scopes: get_email/get_thread/list_attachments are reads of different resources, and semantic_search vs search_emails is disambiguated by 'by meaning' vs 'archived keyword search'. Minor overlap remains between semantic_search and find_similar, and between calendar_freebusy and find_free_slots, which an agent could confuse without careful reading.

    Naming Consistency3/5

    The dominant verb_noun pattern (list_attachments, create_reply_draft, search_calendar) is common, but several tools break it with noun-first or noun-only names like calendar_freebusy, meeting_prep, archive_status and diagnose. Also, get_email vs get_calendar_event use different subject-naming conventions (bare noun versus domain-prefixed).

    Tool Count4/5

    22 tools cover a broad domain (email, attachments, calendar, sync, diagnostics), and each appears to address a real workflow step. It is slightly heavy and could be trimmed by consolidating overlapping free/busy tools, but it is not excessive for the scope.

    Completeness4/5

    The read surface is thorough: search, retrieval, threads, attachments, orphan files, calendar, folders, sync status and diagnostics are all covered, with draft-based write operations. Gaps are mostly intentional (no send, no update/delete/move of mail or calendar events), which limits agents to read-plus-draft workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol tool that enables Claude to interact with Microsoft Outlook for macOS, allowing users to read/send emails, manage calendar events, and access contacts through natural language commands.
      123 npm
      46
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude to read and search mail in local Outlook classic via COM, and to create new draft, reply, and reply-all drafts for the user to review and send. It exposes no send, delete, or move capability, so messages can only be examined and drafted.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to query a local, read-only Apple Mail archive, letting them search messages by keyword, sender, subject, date or account and retrieve summaries, individual message bodies, pending action items and stored daily briefs. All tools are annotated read-only, so assistants can consult mail without sending, deleting, moving or editing anything.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets Claude and other MCP clients search years of messages in milliseconds, read threads, find mail needing a reply, draft answers in the user's voice, and clean up or file attachments, all locally on the Mac. Changes such as moving, flagging and sending are gated behind previews and an explicit click, so nothing leaves without approval.
      1
      MIT