outlook-mcp-server

# outlook-mcp-server A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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 ```bash git clone https://github.com/dhtim135/outlook-mcp-server cd outlook-mcp-server uv sync ``` ### 3. Authenticate (one-time) ```bash 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 ```bash 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: ```json { "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`.