new-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., "@new-outlook-mcp find the email where Sarah sent the budget spreadsheet last week"
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.
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-mcpThe 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 |
| |
Attachments |
|
Calendar |
|
Drafts |
|
Status |
|
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:
Architecture: data flow, modules, schema, adding a source.
HxStore notes and legacy notes: the two Outlook formats.
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 testsAll 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:
hshore29/pyolk: Outlook for Mac 2016+
Outlook.sqliteand.olk15*structures.thomasmaerz/olk15-export: legacy message sources and attachment blocks.
ukd1/hxstore-reverse-engineering: HxStore header, block checksums, LZ4 payloads and
hxprobe.mitchell-johnson/hxstore-decode: HxStore pages and the
Files/layout.ourostack/teamscrawl,
docs/outlook-store.md: calendar event and detail objects.
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 toolsarchive_statusBRead-onlyIdempotent
Archive size, date coverage per source (legacy, hxstore) and the last sync per source.
Inputs: no named parameters.
calendar_freebusyBRead-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.
diagnoseARead-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_slotsCRead-onlyIdempotent
Find free slots of a given length in my own calendar.
Inputs: start (required), duration_minutes (required), end, timezone, +4 more.
find_similarBRead-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_attachmentARead-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_eventARead-onlyIdempotent
Full details of one event: times, attendees and responses, body, meeting link, recurrence.
Inputs: event_id (required), timezone.
get_emailARead-onlyIdempotent
Get one email: metadata, attachment list and plain-text body (paged with offset).
Inputs: email_id (required), offset, max_chars, include_headers.
get_threadARead-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_attachmentsARead-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_eventsBRead-onlyIdempotent
List calendar event occurrences in a date range (recurring events are expanded).
Inputs: start (required), end, limit, account, +3 more.
list_foldersARead-onlyIdempotent
List folders with message counts and date ranges.
Inputs: no named parameters.
list_recentCRead-onlyIdempotent
List the newest archived emails. freshness and warning work as in search_emails.
Inputs: days, limit, folder, account.
meeting_prepBRead-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_calendarCRead-onlyIdempotent
Search calendar events.
Inputs: query (required), limit, date_to, timezone, +1 more.
search_emailsARead-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_filesARead-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.
semantic_searchARead-onlyIdempotent
Find emails and attachments by meaning. Each result is one email with the best matching passage as
its snippet, match says whether that passage is the subject, the body or an attachment, and
matched says whether meaning, keywords or both found it.
Inputs: query (required), mode, limit, folder, +6 more.
sync_nowAIdempotent
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
Scored across 22 tools
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.
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).
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.
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
Related MCP Connectors
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Read and search folders on your own computer with explicit consent. Files are never uploaded.
Give Claude a second brain for your notes, tasks and contacts. OAuth; it can't delete anything.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA 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 npm46MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceLets 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.1MIT