outlook-mcp-server

A lightweight Model Context Protocol (MCP) server for personal Microsoft Outlook / Hotmail accounts. It connects Claude (or any MCP-compatible AI) to your inbox via the Microsoft Graph API, using OAuth 2.0 device-code flow — no service account or admin consent required.

Tools

These tools compose naturally for email-automation workflows — for example: search by sender → read body → download attachments → mark read → move to archive.

Setup

1. Azure App Registration (one-time)

Personal Microsoft accounts still require an Azure App Registration to call Graph.

1. Go to https://portal.azure.com → Microsoft Entra ID → App registrations → New registration.

2. Name: outlook-mcp-server (or anything).

3. Supported account types: choose "Personal Microsoft accounts only".

4. Redirect URI: leave blank for now.

5. After creation, copy the Application (client) ID — this is your OUTLOOK_MCP_CLIENT_ID.

6. Open Authentication → enable "Allow public client flows" = Yes → Save.

7. Open API permissions → Add a permission → Microsoft Graph → Delegated permissions → check Mail.ReadWrite → Add. (No admin consent needed for personal accounts.)

2. Install

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

3. Authenticate (one-time)

export OUTLOOK_MCP_CLIENT_ID="<your-client-id>"
uv run python login.py

Follow the device code prompt — visit the URL in any browser, enter the code, sign in with your Hotmail/Outlook.com account, and approve the Mail.ReadWrite permission.

The token is cached at ~/.config/outlook-mcp/token-cache.json (mode 0600). Refresh tokens are rotated automatically as long as the server is used at least every ~90 days.

4. Register with Claude Code

claude mcp add outlook \
  --env OUTLOOK_MCP_CLIENT_ID="<your-client-id>" \
  -- uv --directory /path/to/outlook-mcp-server run python server.py

Or add manually to your MCP config:

{
  "mcpServers": {
    "outlook": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/outlook-mcp-server",
        "run", "python", "server.py"
      ],
      "env": {
        "OUTLOOK_MCP_CLIENT_ID": "<your-client-id>"
      }
    }
  }
}

KQL search examples

from:amazon.com
subject:invoice
from:receipts@uber.com received>=2026-01-01
hasattachment:yes from:doordash.com

Multiple terms are AND-ed. Quote phrases with spaces.

Re-authentication

If you see Token refresh failed, just re-run uv run python login.py.