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.

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 urgent."
• "Draft a reply to Sarah's message from yesterday saying I'll review the deck Friday."
• "What's on my calendar Thursday? Reschedule my 2pm with Mark to 3pm."
• "Find all emails from the legal team about the compliance review and list action items."
• "Create a To Do task for each unread message from my manager, due end of week."
• "Move all emails from newsletter@ to my 'Newsletters' folder. Batch 20 at a time."*

The server exposes 51 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

51 tools across 13 categories:

• Auth (1) -- auth status check (login is via CLI)
• Mail Read (4) -- list inbox, read message, search (KQL), list folders
• Mail Write (3) -- send, reply/reply-all, forward
• Mail Triage (5) -- move, delete (soft by default), flag, categorize, mark read/unread
• Calendar Read (2) -- list events (with recurring expansion), get event details
• Calendar Write (4) -- create, update, delete, RSVP (accept/decline/tentative)
• Contacts (6) -- list, search, get, create, update, delete
• To Do (6) -- list task lists, list/create/update/complete/delete tasks
• Drafts (5) -- list, create, update, send, delete
• Attachments (3) -- list, download, send-with-attachments
• 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.

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, register under mcp.servers in ~/.openclaw/openclaw.json and restart the gateway.

Authenticate

Run this once on the machine where the MCP server will run:

uv run outlook-mcp auth

You'll get a URL and a code. Open the URL in any browser, enter the code, and sign in with your Microsoft account. Tokens are cached in the OS keyring — the MCP server picks them up automatically.

Other CLI commands:

uv run outlook-mcp status   # Check auth status
uv run outlook-mcp logout   # Clear credentials
uv run outlook-mcp serve    # Start MCP server (default, used by OpenClaw/Claude)

Tool Reference

Auth

Note: Authentication is handled via the CLI (outlook-mcp auth), not through MCP tools. See Authenticate above.

Mail Read

Mail Write

Mail Triage

Calendar Read

Calendar Write

Contacts

To Do

Drafts

Attachments

Folder Management

Threading and Batch

User and Admin

Configuration

Config lives at ~/.outlook-mcp/config.json (created with 0600 permissions).

Privacy and Security

• Zero telemetry. No analytics, no tracking, no usage data collected.
• Zero local caching. Every call goes directly to Microsoft Graph. No local email/calendar storage.
• Zero third-party calls. The server only talks to graph.microsoft.com and login.microsoftonline.com.
• Token storage. OAuth tokens are stored in your OS keyring via azure-identity (TokenCachePersistenceOptions). On macOS this is Keychain. No tokens are written to disk in plaintext.
• No logging of sensitive data. Message bodies, recipient addresses, and tokens are never logged.
• Config permissions. Config directory is 0700, config file is 0600. Symlinked configs are rejected.
• Input validation. All user inputs (email addresses, Graph IDs, OData filters, KQL queries, datetimes) are validated and sanitized before reaching the Graph API.

Development

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Run server locally (stdio)
uv run outlook-mcp

Requirements: Python 3.10+

Roadmap

• Focused Inbox -- list Focused/Other tab, override classification
• Out-of-Office -- get/set automatic replies
• Inbox Rules -- list, create, delete rules
• Advanced mail -- raw MIME export, internet message headers
• Calendar -- cancel event (with attendee notification)
• Checklists -- checklist items on To Do tasks
• Enterprise (Entra ID) -- work/school account support

License

MIT. See LICENSE.