Skip to main content

outlook-desktop-mcp-plus

PyPI Python Platform

Maintained by Alexander Rolli. This is a fork of outlook-desktop-mcp by Andreas Martin Aanerud (see Credits). It includes fixes from upstream pull requests that were never merged, along with locale-safe dates, draft tools, New Outlook for Mac support, reconnecting to Outlook after a restart, faster mail listing on Windows, and compact JSON output. It works as a drop-in replacement: the outlook-desktop-mcp command and the outlook_desktop_mcp Python module keep their names. Uninstall the original package first, since both packages install the outlook-desktop-mcp command.

Turn your running Outlook Desktop into an MCP server. No Microsoft Graph API, no Entra app registration, no OAuth tokens — just your local Outlook and the authentication you already have.

Any MCP client (Claude Code, Claude Desktop, etc.) can then send emails, manage your calendar, create tasks, handle attachments, and more — all through your existing Outlook session.

Quick Start

1. Install (requires Python 3.12+). The recommended way is uv, which installs the server in its own environment and puts the commands on your PATH:

uv tool install outlook-desktop-mcp-plus
Other ways to install, and how to update

With pipx:

pipx install outlook-desktop-mcp-plus

With pip, inside a virtual environment, or on Windows with the python.org installer:

pip install outlook-desktop-mcp-plus

On macOS with Homebrew Python, a plain pip install fails with externally-managed-environment. Use uv or pipx instead.

To update with uv:

uv tool install --refresh --upgrade outlook-desktop-mcp-plus

--refresh makes uv check PyPI again instead of using its cached index. Without it, a release from the last few minutes can show up as "no version found".

2. Register with Claude Code:

claude mcp add outlook-desktop -- outlook-desktop-mcp-plus

3. Open Outlook and start a Claude Code session. That's it — tools are available immediately.

How It Works — Platform Routing

When the server starts, it checks which operating system it is running on and takes one of two paths:

                     outlook-desktop-mcp-plus starts
                                  |
                          sys.platform check
                         /                  \
                   "win32"                "darwin"
                      |                      |
              ┌───────┴────────┐    ┌────────┴────────┐
              │  server.py     │    │  server_mac.py   │
              │  COM Bridge    │    │  AppleScript     │
              │  (29 tools)    │    │  Bridge          │
              │                │    │  (22 tools)      │
              └───────┬────────┘    └────────┬─────────┘
                      |                      |
              OUTLOOK.EXE via         Microsoft Outlook
              COM / STA thread        via osascript
                      |                      |
              Exchange / M365         Exchange / M365

Both paths use your locally running Outlook app and its existing authenticated session. No cloud credentials, no Graph API tokens — the server inherits whatever account Outlook is signed into.

Why two paths?

Windows Outlook (Classic) exposes a rich COM automation interface — the Outlook Object Model (MSOUTL.OLB). This has been the standard way to programmatically control Outlook on Windows for over 20 years. It provides deep access to mail rules, categories, MAPI properties, and the full folder hierarchy.

Mac Outlook does not support COM. Instead, it exposes an AppleScript dictionary that can be driven via the osascript command. The AppleScript interface covers the core operations — email, calendar, tasks — but does not expose rules, categories, or certain advanced MAPI features. This is a limitation of what Microsoft chose to include in Outlook for Mac's scripting dictionary, not a limitation of this project.

The server is structured as two parallel implementations with identical tool names and signatures, so MCP clients see the same interface regardless of platform. Tools that are not available on a given platform are simply not registered.

Requirements

Windows

  • Outlook Desktop (Classic) — the OUTLOOK.EXE that comes with Microsoft 365 / Office. The new "modern" Outlook (olk.exe) does not support COM
  • Python 3.12+ (x64 or ARM64)
  • Outlook must be running when the MCP server starts

Both x64 and ARM64 Windows are supported. On ARM64, all dependencies (pywin32, mcp, pydantic-core, cryptography, cffi, rpds-py) have prebuilt win_arm64 wheels — see the ARM64 install notes below for the one extra pip flag you need.

Outlook "Programmatic Access" security prompts

When the MCP server first touches Outlook's COM API, Outlook may show a dialog: "A program is trying to access email address information stored in Outlook" (the Object Model Guard / Programmatic Access prompt). This is Outlook's protection against malicious automation.

You have three options:

  1. Click "Allow access for 10 minutes" every time you start a session. Fine for casual use.

  2. Get the antivirus status to "Valid" in File > Options > Trust Center > Trust Center Settings > Programmatic Access. When that line reads Valid, the "Never warn me about suspicious activity" radio becomes selectable and the prompts go away. On most personal machines with current Defender this works out of the box.

  3. Apply the registry policy in docs/suppress-outlook-oom-prompts.reg. From an elevated PowerShell or Command Prompt (Win+X → Terminal (Admin)), run:

    reg import "C:\path\to\outlook-desktop-mcp-plus\docs\suppress-outlook-oom-prompts.reg"
    

    Then fully quit Outlook (check Task Manager for stray OUTLOOK.EXE processes) and reopen it. This writes AdminSecurityMode=3 and approves all PromptOOM* categories under HKLM\Software\Policies\Microsoft\Office\16.0\Outlook\Security, which Outlook honors regardless of AV status. On Intune/MDM-managed corporate devices, HKCU\Software\Policies\...\Outlook is locked and the HKLM keys may be overwritten on next policy sync — if reg import fails or the prompts come back, ask IT to push the equivalent settings via Group Policy.

Windows 11 ARM64 note: Defender does not register with Outlook's IOfficeAntiVirus interface on ARM64, so Trust Center shows "Antivirus status: Invalid" and the "Never warn me about suspicious activity" radio stays greyed out even when Outlook is launched as Administrator. Option 2 is unavailable on ARM64; the reg import from option 3 is the only durable suppression path.

macOS

  • Microsoft Outlook for Mac — version 16.x or later
  • Python 3.12+
  • Outlook must be running when the MCP server starts

Required macOS permissions

The first time a tool runs, macOS will show two permission prompts that you must approve:

  1. Privacy & Automation — a system dialog asks: "python3.12 wants to control Microsoft Outlook". Click Allow to let the server send AppleScript commands to Outlook.

  2. Accessibility — to read your Exchange/M365 inbox, the server uses macOS UI scripting (System Events). This requires Accessibility access for python3.12:

    • Open System Settings > Privacy & Security > Accessibility
    • Find python3.12 in the list (it appears after the first prompt)
    • Toggle it on

    Without Accessibility enabled, calendar, tasks, and local folder tools will work, but listing Exchange inbox messages will return empty results.

Both permissions are one-time setup — macOS remembers them for future sessions.

Available Tools by Platform

Email

Tool Windows macOS Description
send_email yes yes Send an email with To/CC/BCC, plain text or HTML body
save_draft yes yes Save an email to the Drafts folder without sending (human review workflow)
list_drafts yes yes List drafts in the Drafts folder with pagination (newest first)
read_draft yes yes Read full content of a specific draft by ID (body, recipients, attachments)
send_draft yes yes Send an existing draft by ID (moves to Sent Items automatically)
list_emails yes yes List recent emails from any folder, with optional unread filter
read_email yes yes Read full email content by entry ID or subject search
search_emails yes yes Full-text search across email subjects and bodies
reply_email yes yes Reply or reply-all, preserving the conversation thread
mark_as_read yes yes Mark a specific email as read
mark_as_unread yes yes Mark a specific email as unread
move_email yes yes Move an email to Archive, Trash, or any folder
list_folders yes yes Browse the folder hierarchy with item counts

Calendar

Tool Windows macOS Description
list_events yes yes List upcoming events within a date range
get_event yes yes Read full event details by entry ID
create_event yes yes Create a personal calendar appointment
create_meeting yes yes Create a meeting and send invitations to attendees
update_event yes yes Modify an existing event's subject, time, location, etc.
delete_event yes yes Delete an appointment or cancel a meeting
respond_to_meeting yes — Accept, decline, or tentatively accept a meeting invite
search_events yes yes Search calendar events by keyword within a date range

Tasks

Tool Windows macOS Description
list_tasks yes yes List pending or completed tasks, sorted by due date
get_task yes yes Read full task details including body and completion status
create_task yes yes Create a new task with subject, due date, importance
complete_task yes yes Mark a task as complete
delete_task yes yes Remove a task

Attachments

Tool Windows macOS Description
list_attachments yes yes List all attachments on an email or calendar event
save_attachment yes yes Download an attachment to a local directory

Categories, Rules, Out of Office (Windows only)

These tools rely on COM-specific APIs (MAPI property accessors, the Rules object model, and the Categories collection) that Outlook for Mac does not expose through AppleScript.

Tool Windows macOS Description
list_categories yes — List all available color categories in Outlook
set_category yes — Set or clear categories on any email, event, or task
list_rules yes — List all mail rules with enabled/disabled status
toggle_rule yes — Enable or disable a mail rule by name
get_out_of_office yes — Check whether Out of Office auto-reply is on or off

Total: 33 tools on Windows, 26 tools on macOS.

Architecture Details

Windows: COM Bridge (com_bridge.py)

All Outlook COM operations run on a dedicated thread using the Single-Threaded Apartment (STA) model, as required by COM. The async MCP event loop dispatches tool calls to this thread via a queue and awaits results, keeping COM threading rules respected and the MCP protocol non-blocking.

MCP tool call (async)
  → bridge.call(func, args)
    → queued to STA thread
      → func(outlook, namespace, args) executes on COM thread
    → result returned via threading.Event
  → JSON response back to MCP client

Each tool's inner function receives the live Outlook.Application and MAPI.Namespace COM objects and works directly with the Outlook Object Model — GetItemFromID, CreateItem, Items.Restrict with DASL filters, and so on.

macOS: AppleScript Bridge (applescript_bridge.py)

Each tool call builds an AppleScript string and executes it as a subprocess via osascript. There is no persistent connection — every call is stateless.

MCP tool call (async)
  → build AppleScript string
    → asyncio.create_subprocess_exec("osascript", "-e", script)
    → parse stdout text into structured data
  → JSON response back to MCP client

Each tool constructs a single AppleScript that fetches all needed data in one osascript call (no per-message subprocess loops). Results come back as delimited text, which the server parses into the same JSON structure the Windows server produces.

Key differences from Windows:

  • Entry IDs on macOS are numeric (e.g. 42), not hex strings. They identify items within their folder context.
  • Folder references use AppleScript's locale-independent keywords (inbox, sent items, drafts, deleted items) rather than localized folder names.
  • Search uses AppleScript's whose clause (e.g. messages whose subject contains "query") instead of DASL filters.
  • User input is escaped for safe embedding in AppleScript strings to prevent script injection.

Install from Source

Windows (x64)

git clone https://github.com/lord-helicon/outlook-desktop-mcp-plus.git
cd outlook-desktop-mcp-plus
python -m venv .venv
.venv\Scripts\activate
pip install pywin32 "mcp[cli]" -e .
python .venv\Scripts\pywin32_postinstall.py -install

Register from source using the launcher script:

claude mcp add outlook-desktop -- powershell.exe -Command "& 'C:\path\to\outlook-desktop-mcp-plus\outlook-desktop-mcp.cmd' mcp"

Windows (ARM64)

The [cli] extra of mcp transitively pulls in cryptography, and pip's default resolver may pick a version that lacks a win_arm64 wheel — which then fails to build because it requires a Rust toolchain plus OpenSSL. Install without the cli extra and force wheels-only resolution:

git clone https://github.com/lord-helicon/outlook-desktop-mcp-plus.git
cd outlook-desktop-mcp-plus
& "C:\Program Files\Python312-arm64\python.exe" -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install --only-binary=:all: pywin32 mcp
python -m pip install --no-deps -e .
python .venv\Scripts\pywin32_postinstall.py -install

The base mcp package is sufficient for running the stdio server — the [cli] extra is only needed for the mcp developer CLI tools (mcp dev, mcp inspector), which aren't used at runtime.

Register from source the same way as x64:

claude mcp add outlook-desktop -- powershell.exe -Command "& 'C:\path\to\outlook-desktop-mcp-plus\outlook-desktop-mcp.cmd' mcp"

macOS

git clone https://github.com/lord-helicon/outlook-desktop-mcp-plus.git
cd outlook-desktop-mcp-plus
python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]" -e .

Register from source:

claude mcp add outlook-desktop -- /path/to/outlook-desktop-mcp-plus/.venv/bin/outlook-desktop-mcp-plus

Usage Examples

Once registered, just talk to Claude naturally:

  • "Show me my 10 most recent inbox emails"
  • "Read the email from Taylor about MLADS"
  • "Send an email to alice@example.com about the project update"
  • "What's on my calendar this week?"
  • "Create a meeting with bob@example.com tomorrow at 2pm for 30 minutes"
  • "Save the attachment from that email to my Downloads folder"
  • "Create a task to review the quarterly report, due Friday, high importance"
  • "Mark that email as read and move it to archive"

Windows-only examples:

  • "What categories do I have? Set this email to 'Follow-up'"
  • "List my mail rules"
  • "Am I set as Out of Office?"

Why Not Microsoft Graph?

Microsoft Graph outlook-desktop-mcp-plus
Entra app registration Required Not needed
Admin consent Required for mail permissions Not needed
OAuth token management You handle refresh tokens Not needed
Tenant configuration Required Not needed
Works offline / cached No Yes (reads from local cache)
Setup time 30-60 minutes 2 minutes
Auth requirement Your own OAuth flow Outlook is open

Project Structure

outlook-desktop-mcp-plus/
  src/outlook_desktop_mcp/
    entrypoint.py            # Platform detection → routes to correct server
    server.py                # Windows MCP server (29 tools, COM automation)
    server_mac.py            # macOS MCP server (22 tools, AppleScript)
    com_bridge.py            # Async-to-COM threading bridge (Windows)
    applescript_bridge.py    # Async osascript execution (macOS)
    tools/
      _folder_constants.py   # Outlook enums and constants (Windows)
    utils/
      formatting.py          # Email/event/task data extraction (Windows)
      errors.py              # COM error formatting (Windows)
      applescript_helpers.py # AppleScript escaping, date formatting (macOS)
  tests/
    phase1_com_test.py       # Email COM validation
    phase3_mcp_test.py       # Email MCP test
    calendar_com_test.py     # Calendar COM validation
    calendar_mcp_test.py     # Calendar MCP test
    extras_com_test.py       # Tasks/attachments/categories/rules/OOF COM test
    extras_mcp_test.py       # Tasks/attachments/categories/rules/OOF MCP test
  outlook-desktop-mcp.cmd   # Windows launcher script
  pyproject.toml

Contributing

See CONTRIBUTING.md for the branching strategy and development setup.

Credits

outlook-desktop-mcp-plus is maintained by Alexander Rolli.

It is a fork of outlook-desktop-mcp, created by Andreas Martin Aanerud, who wrote the original Windows (COM) and macOS (AppleScript) server. This fork has been modified since then; the git history records every change.

The fork also includes work from these contributors' pull requests to the original project:

  • Martin Wehner: COM error guards when walking folders (#16)
  • Nao179: draft tools (#23)
  • accesstechnology-mike: draft reply, ported from #21
  • José Ángel Galindo Duarte: locale-safe AppleScript dates (#25)
  • edwadjei: batched AppleScript fetches on macOS (#34)
  • andrey-vk: locale-safe date filters on Windows (#35)
  • Jacob (jfviberg): calendar targeting and the Move() fix (#37)
  • joekwong-uk: New Outlook for Mac findings (issue #29)

License

GNU Affero General Public License v3.0, the same license as the original project. See the LICENSE file.

Metadata

Release files for outlook-desktop-mcp-plus 0.4.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for outlook-desktop-mcp-plus 0.4.4
File Size Uploaded Provenance Actions
outlook_desktop_mcp_plus-0.4.4.tar.gz 107.8 kB With provenance Details for outlook_desktop_mcp_plus-0.4.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for outlook-desktop-mcp-plus 0.4.4
File Interpreter ABI Platform Actions
outlook_desktop_mcp_plus-0.4.4-py3-none-any.whl Python 3 none any Details for outlook_desktop_mcp_plus-0.4.4-py3-none-any.whl

Total release size: 185.9 kB

Release files / outlook_desktop_mcp_plus-0.4.4.tar.gz

Download URL outlook_desktop_mcp_plus-0.4.4.tar.gz
Size 107.8 kB
Tags Source
SHA-256 checksum
How to use checksums
ab53da4f0194a5dfbe4f44003f529d5f242c3754ed42bcc8410b5a5892ab5c9f
BLAKE2b-256 checksum
How to use checksums
32f5aab6b5a4ddd28a07fb8b47e56f4fafe3f481613281498429a2bacb8cdebd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / outlook_desktop_mcp_plus-0.4.4-py3-none-any.whl

Download URL outlook_desktop_mcp_plus-0.4.4-py3-none-any.whl
Size 78.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2c6cb4159c0e954abe36a2846f19ac3ccf851c695384a191a12023339f745d12
BLAKE2b-256 checksum
How to use checksums
4c9113d4d0c98346ee9551691853cbc3bc2d2ed191049dbc58ab4b001f138cc9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for outlook-desktop-mcp-plus 0.4.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for outlook_desktop_mcp_plus-0.4.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page