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

Tool	Parameters	Description
search_emails	query, max_results	Search your inbox using KQL (Keyword Query Language). Supports filtering by sender, subject, date, attachment presence, and more.
read_email	message_id	Fetch the full body (plain text + HTML) and headers of a specific email.
list_attachments	message_id	List all attachments on an email, including their IDs, names, sizes, and content types.
download_attachment	message_id, attachment_id, save_path	Download an attachment and save it to a local file path.
mark_as_read	message_id, read	Mark an email as read or unread.
move_email	message_id, folder	Move an email to a folder by well-known name (e.g. inbox, deleteditems, archive) or folder ID.

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.