outlook-mcp

MCP server for Microsoft Outlook personal accounts via Microsoft Graph API.

Personal Microsoft accounts only — @outlook.com, @hotmail.com, @live.com. Work/school accounts (Entra ID) are not supported in v1.

Disclaimer: Independent open-source project. Not affiliated with, endorsed by, or supported by Microsoft Corporation. "Outlook" and "Microsoft Graph" are trademarks of Microsoft.

Who this is for

You'll like this if you're:

• An agent builder wiring Outlook into your own infra (OpenClaw, Claude Code, Cursor, custom MCP host) and want a typed tool surface — not stdout you have to parse
• Building on personal Microsoft accounts (Outlook.com / Hotmail / Live) and want full control: BYO Azure app, no enterprise consent flow, no shared client ID
• Looking for real coverage — mail, calendar, contacts, to-do, drafts, folders, batch ops, threading — instead of a mail-only or calendar-only wrapper
• Security-conscious: tokens in the OS keyring (Keychain on macOS), granular allow_categories, optional read_only mode, zero telemetry

This isn't for you if you need work/school M365 accounts (use Microsoft's official tooling — Entra ID auth and admin-consent flows are out of scope here), or if a basic mail-only client would suffice (this has 62 tools — way more than you need for "read my inbox").

How it differs from other Outlook tools you'll find

This is the only first-class MCP server in the personal-Outlook space — most alternatives are bash scripts or skill-shaped CLI wrappers the agent shells out to. That distinction matters: the agent gets typed tool schemas with structured args/returns, not stdout it has to parse. Other things you won't find elsewhere: /$batch-optimized triage (10-20× faster on bulk ops), recursive folder ops with name resolution, granular per-category permissions, multi-account support, and full attachment write paths including >3MB upload sessions for drafts.

What This Enables

Give your AI agent full Outlook access. Example prompts that just work:

• "Summarize my unread email from the past 24 hours and flag anything time-sensitive."
• "What's in my Focused Inbox right now? Anything in Other that looks like it belongs up top?"
• "Any shipping updates in my inbox? Track what I'm waiting on and when it's supposed to arrive."
• "Scan my email for upcoming subscription renewals — what's about to auto-charge in the next two weeks?"
• "I've got a trip to Seattle next week — check my calendar for the itinerary and create a To Do task with a packing checklist."
• "Draft a reply to the last message from my sister saying I'll call her this weekend."
• "Move all newsletter and promotional email from this week to a 'Read Later' folder — batch 20 at a time."

The server exposes 62 discrete tools so the agent can compose its own workflow — read, triage, write, schedule, track tasks — without hardcoded macros.

Works With

• OpenClaw — native MCP support, available via ClawHub
• Claude Code — add to ~/.claude/settings.json under mcpServers
• Cursor — MCP-compatible
• Any MCP client — it's a standard stdio MCP server

Listed on the official MCP Registry as io.github.mpalermiti/outlook-mcp.

Features

62 tools across 13 categories:

• Auth (1) -- auth status check (login is via CLI)
• Mail Read (7) -- list inbox (with Focused Inbox and uncategorized filters), read message, bulk read by ID via $batch, search (KQL), list folders, delta-sync inbox changes, composed "since last call" digest across mail/events/contacts
• Mail Write (3) -- send, reply/reply-all, forward
• Mail Triage (9) -- move, delete (soft by default), flag, categorize, mark read/unread, reclassify (Focused Inbox), list/set/delete per-sender Focused Inbox overrides
• Calendar Read (3) -- list events (with recurring expansion), get event details, delta-sync event changes
• Calendar Write (4) -- create, update, delete, RSVP (accept/decline/tentative)
• Contacts (7) -- list, search, get, create, update, delete, delta-sync changes
• To Do (6) -- list task lists, list/create/update/complete/delete tasks
• Drafts (5) -- list, create, update, send, delete
• Attachments (5) -- list, download, send-with-attachments, attach-to-draft, remove-draft-attachment
• Folder Management (3) -- create, rename, delete mail folders
• Threading and Batch (3) -- list thread, copy message, batch triage
• User and Admin (6) -- whoami, list calendars, list categories, mail tips, accounts

Design principles:

• BYOID -- Bring Your Own ID. You register your own Azure AD app. No shared client ID.
• Zero telemetry -- no analytics, no local caching, no third-party calls.
• Token storage -- OS keyring via azure-identity (macOS Keychain, Windows Credential Store, Linux Secret Service).
• Input validation -- all inputs validated (email, Graph IDs, OData, KQL, datetimes) before any API call.
• Read-only mode -- set read_only: true in config to block all write operations.
• Soft delete -- delete moves to Deleted Items by default. Hard delete requires explicit permanent: true.
• Timezone-aware -- calendar operations respect your configured IANA timezone.

Agent-friendly shape (1.8.0)

Two pure-code upgrades that make the same 57 tools cheaper and more recoverable for AI agents:

• Concise mode — pass concise=True to the five high-volume read tools (outlook_list_inbox, outlook_read_message, outlook_search_mail, outlook_list_events, outlook_list_thread) to drop bulky fields: full message bodies, per-event attendee lists, quoted prior-message text in threads, body previews/categories on inbox listings. Typical payload reduction ~10×. Default concise=False preserves the existing response shape — strict backward compat.

• Structured Graph errors — every tool wraps msgraph SDK exceptions into {code, message, action} responses with operator-friendly recovery hints: re-auth on 401, a link to the repo's ROADMAP dead-ends list on 403/ErrorAccessDenied, re-list on 404/ErrorItemNotFound, back-off on 429, retry on 503. OutlookMCPError subclasses and validation errors pass through unchanged.

Azure AD App Registration

You need to register a free Azure AD app to get a client ID.

Prerequisites (Personal Microsoft Accounts)

Microsoft has deprecated app registration for personal accounts without an Azure AD tenant. You need to create a free Azure account first:

1. Go to azure.microsoft.com/free and sign up with your personal @outlook.com account. Requires a credit card for identity verification but won't charge you. This creates a proper Azure AD tenant.

Register the App

1. Go to App Registrations and sign in with your @outlook.com account.

2. Click "+ New registration" and fill in:

   • Name: anything except Microsoft-branded terms (e.g. mp-outlook-mcp — names like "Outlook MCP" will be rejected)
   • Supported account types: select "Personal Microsoft accounts only"
   • Redirect URI: leave blank

3. Click Register. Copy the Application (client) ID from the overview page.

4. Go to Authentication (Preview) → Settings tab → toggle "Allow public client flows" to Yes → Save.

5. Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions → add:

   • Mail.ReadWrite, Mail.Send
   • Calendars.ReadWrite
   • Contacts.ReadWrite, Tasks.ReadWrite
   • User.Read, offline_access

No client secret is needed. The device code flow uses public client auth.

Quick Start

Install

Option A — from PyPI (recommended):

uv tool install outlook-graph-mcp
# or: pipx install outlook-graph-mcp
# or: pip install outlook-graph-mcp

Option B — from source:

git clone https://github.com/mpalermiti/outlook-mcp.git
cd outlook-mcp
uv sync

Configure

Create ~/.outlook-mcp/config.json:

{
  "client_id": "YOUR_APPLICATION_CLIENT_ID",
  "tenant_id": "consumers",
  "timezone": "America/Los_Angeles",
  "read_only": true
}

The only required field is client_id. Everything else has sensible defaults. Start with read_only: true — flip to false when you're comfortable.

Register with your MCP client

If installed from PyPI:

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

If installed from source:

{
  "mcpServers": {
    "outlook": {
      "command": "uv",
      "args": ["--directory", "/path/to/outlook-mcp", "run", "outlook-mcp"]
    }
  }
}

For OpenClaw, use the openclaw mcp CLI — it writes to mcp.servers in ~/.openclaw/openclaw.json for you:

# If installed from PyPI:
openclaw mcp set outlook '{"command":"outlook-mcp"}'

# If installed from source:
openclaw mcp set outlook '{"command":"uv","args":["--directory","/path/to/outlook-mcp","run","outlook-mcp"]}'

# Verify:
openclaw mcp list
openclaw mcp show outlook --json