# 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`.