Outlook MCP Server (win32com)

An MCP server that controls the Microsoft Outlook desktop app through COM automation (win32com). It does not use Microsoft Graph — there is no Azure app registration, no OAuth, no API keys. It operates on whatever account(s) your local Outlook client is already signed into, which makes it ideal for corporate environments where Graph API access is locked down.

Requirements

• Windows (COM automation is Windows-only)

• Classic Outlook desktop installed and configured with an account. The "new Outlook" (the web-based rewrite) does not expose the COM object model and will not work — switch the toggle back to classic Outlook.

• Python 3.10+

Related MCP server: outlook-classic-mcp

Installation

git clone <this-repo>
cd outlook_mcp
pip install -e .

This installs mcp and pywin32 and registers the outlook-mcp command.

Configure Claude Desktop / Claude Code

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "outlook": {
      "command": "outlook-mcp"
    }
  }
}

Claude Code:

claude mcp add outlook -- outlook-mcp

If Outlook is not running, the first tool call starts it automatically.

Tools

Mail — read & search

Mail — write, drafts & management

Calendar & scheduling

Meeting invitations, contacts & accounts

Emails and events are addressed by their Outlook EntryID, which the list/ search tools return — pass it to get_email, reply_to_email, update_calendar_event, etc. Folders accept well-known names (Inbox, Sent Items, Drafts, ...) or slash paths like Inbox/Receipts or you@company.com/Inbox to target a specific account.

Example prompts

• "Show my unread emails"

• "Search my inbox for emails from Alice about the Q3 budget"

• "Reply to that email saying I'll review it by Friday"

• "Save the attachments from that email to C:\Users\me\Downloads"

• "What's on my calendar this week?"

• "Check if alice@corp.com and bob@corp.com are free Thursday afternoon"

• "Find a 30-minute slot next Monday when the whole team is available"

• "Set up a 30-minute meeting with bob@example.com tomorrow at 2pm"

• "Mark me out of office next Friday through the following Wednesday"

Time zones (recommended for meetings)

The meeting-creation tools (create_calendar_event, create_teams_meeting, create_recurring_meeting) accept an optional timezone_name. Give it an IANA name (Asia/Kolkata), a Windows ID (India Standard Time), or a common abbreviation (IST). The start time you pass is treated as wall-clock time in that zone, and the result reports both the local and UTC times.

This matters most for recurring meetings: without an explicit zone, a series pinned to "12:00" can shift by an hour when it crosses a daylight-saving boundary, because Outlook interprets the time in whatever zone the profile happens to be in. Passing timezone_name sets the appointment's StartTimeZone/EndTimeZone in COM so occurrences stay put. (Note: on Windows, Python needs the tzdata package for this — it's declared as a dependency.)

Recipient validation

send_email (and the meeting tools) add each recipient individually and call ResolveAll() before sending. If any name is ambiguous or unknown, the send is rejected with the offending entries listed — pass allow_unresolved=True to override. Results list every recipient's canonical SMTP address (Exchange EX addresses are resolved to real SMTP), so you can confirm exactly who will receive the message before trusting it.

Development & tests

pip install -e ".[dev]"
pytest

The pure-logic layer (date/timezone parsing, DST conversion, recurrence, recipient resolution) is covered by mock-based tests that run on any platform — no Windows or Outlook required. COM interaction itself can only be exercised on Windows. CI runs the suite on Python 3.10–3.12.

Checking other people's availability

check_availability and find_meeting_times read free/busy data — the same busy/free blocks Outlook shows in the Scheduling Assistant. In most Exchange/Microsoft 365 organizations every user can see everyone else's free/busy by default (busy times only, not the meeting subjects), so no special mailbox permissions are needed. If a person has restricted their free/busy sharing, their slots come back as unavailable and the tools say so.

Teams meetings and invitations

• Responding to invites works fully. list_meeting_invitations shows pending requests in your Inbox; respond_to_invitation accepts, tentatively accepts, or declines them (with an optional note, and an option to respond without notifying the organizer).

• Reading others' meetings (list_shared_calendar) works when that person has shared their calendar with you at Reviewer permission or higher. It shows real subjects/times, unlike check_availability, which shows only free/busy.

• Creating a Teams meeting is partial. COM cannot inject a Teams join link — the link is produced by the Teams Meeting Add-in/service, not the Outlook Object Model. create_teams_meeting sends the invite and relies on the mailbox setting File > Options > Calendar > "Add online meeting to all meetings"; with that ON, sent meetings automatically become Teams meetings. With it OFF, an ordinary meeting invite is sent and you'd add the Teams link manually.

• "Propose new time" is not available via COM. The Object Model has no propose-new-time method. To suggest another slot, decline with a message (or use find_meeting_times to pick a slot and send a fresh invite).

• Recurring meetings are supported. create_recurring_meeting sends a full series — daily, weekly (with specific weekdays like Mon,Wed,Fri), monthly, or yearly, with an interval (e.g. every 2 weeks) and an end defined by a number of occurrences (count) or an end date (until). Attendees receive the series and accept it as a series. Recurring invites you receive are accepted/declined as a whole series by respond_to_invitation.

Out of office: what works and what doesn't

• schedule_out_of_office works — it creates a calendar block with "Out of Office" availability status, so you show as away in other people's free/busy and Scheduling Assistant.

• Automatic replies (the auto-responder email) cannot be set via COM. The Outlook Object Model simply does not expose Out-of-Office reply settings. set_automatic_replies therefore only returns guidance. To turn on the auto-responder, either flip it on manually (File > Automatic Replies) or use Exchange Web Services (SetUserOofSettings) / Microsoft Graph (mailboxSettings.automaticRepliesSetting) — both of which are outside COM.

Notes & troubleshooting

• Security prompts: depending on your organization's policy, Outlook may show an "Allow access?" dialog when a program reads addresses or sends mail programmatically. Your admin controls this via Group Policy ("Programmatic Access" settings in Trust Center).

• "New Outlook" toggle: if tool calls fail with "class not registered" or Outlook opens but nothing happens, you are likely on new Outlook. Switch back to classic Outlook.

• Bitness/permissions: run the MCP server as the same user (and not elevated differently) as Outlook, or COM will refuse to connect to the running instance.