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.

Go to https://portal.azure.com → Microsoft Entra ID → App registrations → New registration.
Name: outlook-mcp-server (or anything).
Supported account types: choose "Personal Microsoft accounts only".
Redirect URI: leave blank for now.
After creation, copy the Application (client) ID — this is your OUTLOOK_MCP_CLIENT_ID.
Open Authentication → enable "Allow public client flows" = Yes → Save.
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.