<!-- mcp-name: io.github.salahawad/outlook-personal-mcp -->
# outlook-personal-mcp

An MCP server that gives Claude Code and Codex full control of a personal Outlook.com mailbox and calendar via the Microsoft Graph API. Written in Python, speaks the MCP stdio transport, and uses per-user device-code OAuth so your credentials never leave your machine. MIT licensed.

---

## Features

- **Mail** — list, search, read, send, reply, forward, move, copy, flag, mark read/unread, delete (soft or hard)
- **Drafts** — create, update, attach local files, send
- **Folders** — list, create, rename, delete
- **Calendar** — list calendars, list/search/get/create/update/delete events, respond to invites (accept/decline/tentative), check free/busy availability
- **Per-user OAuth** — you register your own free Azure app; the server authenticates with your Microsoft account and caches the token locally
- **Local stdio** — runs as a child process of the MCP host; your mailbox data never transits a third party

---

## Prerequisites

- Python 3.10 or later
- [`uv`](https://docs.astral.sh/uv/) (fast Python package and tool runner) — **required at runtime**: the server is launched via `uvx`, and it is not bundled by your MCP host (including Claude Desktop). Install it with `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux) or `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows).
- A personal Microsoft account (Outlook.com, Hotmail, Live, etc.)
- A free Azure app registration (see below — takes about three minutes)

---

## Azure App Registration

1. Go to [https://portal.azure.com](https://portal.azure.com) → **Microsoft Entra ID** → **App registrations** → **New registration**.
2. Name it anything you like (e.g. `outlook-personal-mcp`). Under **Supported account types** choose **Personal Microsoft accounts only**. No redirect URI is needed. Click **Register**.
3. Open the app → **Authentication** → **Advanced settings** → **Allow public client flows** → set to **Yes** → **Save**. (This is required for the device-code login flow used by this server.)
4. Go to **API permissions** → **Add a permission** → **Microsoft Graph** → **Delegated permissions**, then add:
   - `Mail.ReadWrite`
   - `Mail.Send`
   - `Calendars.ReadWrite`

   (`User.Read` is included by default; `offline_access` is requested automatically at runtime — you do not need to add it.)
5. Copy the **Application (client) ID** from the **Overview** page. This is your `OUTLOOK_MCP_CLIENT_ID`.

### Alternatively: create the app with the Azure CLI

If you have the [`az` CLI](https://learn.microsoft.com/cli/azure/install-azure-cli), the whole registration is one command:

```bash
az login --use-device-code --allow-no-subscriptions   # sign in with your personal account

az ad app create \
  --display-name "outlook-personal-mcp" \
  --sign-in-audience PersonalMicrosoftAccount \
  --is-fallback-public-client true \
  --required-resource-accesses '[{"resourceAppId":"00000003-0000-0000-c000-000000000000","resourceAccess":[{"id":"024d486e-b451-40bb-833d-3e66d98c5c73","type":"Scope"},{"id":"e383f46e-2787-4529-855e-0e479a3ffac0","type":"Scope"},{"id":"1ec239c2-d7c9-4623-a91a-a9775856bb36","type":"Scope"}]}]' \
  --query appId -o tsv
```

The printed `appId` is your `OUTLOOK_MCP_CLIENT_ID`. (The GUIDs are the Microsoft Graph delegated scopes `Mail.ReadWrite`, `Mail.Send`, and `Calendars.ReadWrite`.) **Note:** a brand-new app registration takes a few minutes to propagate to Microsoft's consumer login endpoint — if your first login fails with `AADSTS700016` ("application … not found"), wait a few minutes and retry.

---

## Install & First-Time Login

Run the one-time interactive login. It prints a short URL and a code; open the URL in any browser, enter the code, approve the permissions, and you are done. The token is cached at `~/.config/outlook-personal-mcp/token_cache.bin` (mode 600) and refreshed automatically on subsequent runs — you will not be prompted again unless the refresh token expires or is revoked.

```bash
OUTLOOK_MCP_CLIENT_ID=<your-app-client-id> uvx mcp-outlook-personal login
```

> To run the latest unreleased code from source instead of the PyPI release, swap `mcp-outlook-personal` for `--from git+https://github.com/salahawad/outlook-personal-mcp mcp-outlook-personal`.

---

## Configure Claude Code

Add the server to your project's `.mcp.json` (or `~/.claude/.mcp.json` for all projects):

```json
{
  "mcpServers": {
    "outlook": {
      "command": "uvx",
      "args": ["mcp-outlook-personal"],
      "env": { "OUTLOOK_MCP_CLIENT_ID": "<your-app-client-id>" }
    }
  }
}
```

Alternatively, use the CLI: `claude mcp add`.

---

## Configure Codex

Add the server to `~/.codex/config.toml`:

```toml
[mcp_servers.outlook]
command = "uvx"
args = ["mcp-outlook-personal"]
env = { OUTLOOK_MCP_CLIENT_ID = "<your-app-client-id>" }
```

---

## Install as a Claude Desktop extension (.mcpb)

This server is also packaged as a [Claude Desktop extension](https://www.anthropic.com/engineering/desktop-extensions) (`.mcpb`). Build the bundle from a checkout:

```bash
npx @anthropic-ai/mcpb pack . dist/mcp-outlook-personal.mcpb
```

Then in Claude Desktop open **Settings → Extensions**, install the `dist/mcp-outlook-personal.mcpb` file, and enter your **Azure App Client ID** (plus any optional settings) when prompted.

> **Requirement:** the extension launches the server with `uvx mcp-outlook-personal`, so [`uv`](https://docs.astral.sh/uv/) must be installed and on your `PATH` — Claude Desktop does not bundle it (see [Prerequisites](#prerequisites)). Codex and other stdio hosts use the config above instead of the `.mcpb`.

---

## Configuration (Environment Variables)

| Variable | Required | Default | Description |
|---|---|---|---|
| `OUTLOOK_MCP_CLIENT_ID` | **Yes** | — | Azure app's Application (client) ID |
| `OUTLOOK_MCP_AUTHORITY` | No | `https://login.microsoftonline.com/consumers` | MSAL authority URL (change only if you move to a work/school tenant) |
| `OUTLOOK_MCP_TOKEN_CACHE` | No | `~/.config/outlook-personal-mcp/token_cache.bin` | Path to the MSAL token cache file |
| `OUTLOOK_MCP_FILE_ROOT` | No | `~/.local/share/outlook-personal-mcp/files` | Only files under this directory can be read by `add_attachment` or written by `download_attachment` |
| `OUTLOOK_MCP_MAX_FILE_BYTES` | No | `3145728` | Maximum bytes allowed for local attachment reads and attachment downloads |
| `OUTLOOK_MCP_ALLOW_PERMANENT_DELETE` | No | `false` | Set to `true` to enable the `permanent_delete` tool (irreversible — see below) |
| `OUTLOOK_MCP_DEBUG` | No | `false` | Set to `true` to log each Graph request's method, URL, and HTTP status code to stderr. Never logs tokens or message content. |

---

## Tools

### Account

| Tool | Description |
|---|---|
| `whoami` | Return the signed-in user's Microsoft account profile |

### Mail

| Tool | Description |
|---|---|
| `list_messages` | List messages (newest first); optionally filter by folder or unread-only |
| `search_messages` | Full-text search across the entire mailbox (Graph `$search`) |
| `get_message` | Get a single message; optionally include the full body |
| `list_attachments` | List a message's attachments (id, name, size, content type) |
| `download_attachment` | Download an attachment to a path under `OUTLOOK_MCP_FILE_ROOT` (refuses to overwrite an existing file) |
| `send_mail` | Send an email |
| `reply` | Reply to a message (`reply_all` to reply to everyone) |
| `forward` | Forward a message to recipients with an optional comment |
| `move_message` | Move a message to another folder |
| `copy_message` | Copy a message to another folder |
| `mark_read` | Mark a message read or unread |
| `flag_message` | Flag or unflag a message |
| `delete_message` | Delete a message (moves it to Deleted Items; reversible) |
| `permanent_delete` | **Permanently** delete a message (irreversible). Only available when `OUTLOOK_MCP_ALLOW_PERMANENT_DELETE=true` |

### Folders

| Tool | Description |
|---|---|
| `list_folders` | List mail folders with unread and total message counts |
| `create_folder` | Create a mail folder, optionally nested under a parent |
| `rename_folder` | Rename a mail folder |
| `delete_folder` | Delete a mail folder (moves it to Deleted Items) |

### Drafts

| Tool | Description |
|---|---|
| `create_draft` | Create a draft message (not sent) |
| `update_draft` | Update a draft's subject and/or body |
| `add_attachment` | Attach a local file (a regular, non-symlink file under `OUTLOOK_MCP_FILE_ROOT`) to a draft |
| `send_draft` | Send an existing draft |

### Calendar

| Tool | Description |
|---|---|
| `list_calendars` | List the user's calendars |
| `list_events` | List events; if `start`/`end` (ISO 8601) are given, returns that time window |
| `search_events` | Search events by free text |
| `get_event` | Get one event including body, attendees, and online meeting link |
| `create_event` | Create a calendar event with optional attendees and online meeting |
| `update_event` | Update fields on an existing event (only provided fields change) |
| `delete_event` | Delete/cancel a calendar event |
| `respond_event` | Respond to a meeting invite: `accept`, `decline`, or `tentative` |
| `find_availability` | Get free/busy availability for a list of people over a time window |

---

## Permanent Delete

The `permanent_delete` tool bypasses the Deleted Items folder and removes a message irreversibly. It is **disabled by default** — when `OUTLOOK_MCP_ALLOW_PERMANENT_DELETE` is not set (or is `false`), the tool is not registered with the MCP server at all and will not appear in the tool list.

To enable it, set `OUTLOOK_MCP_ALLOW_PERMANENT_DELETE=true` in the server's environment block in your `.mcp.json` / `config.toml`. Only do this if you understand the consequences: there is no undo and no Recoverable Items path for personal accounts.

---

## Security

- **Token cache is a credential.** The file at `~/.config/outlook-personal-mcp/token_cache.bin` contains a long-lived refresh token. It is written with mode `600`, but treat it like a password — never commit it, never share it, and store it on an encrypted volume.
- **Data stays local.** The server runs as a child process of Claude Code / Codex over stdio. Your mailbox content is passed directly between the MCP host and the Microsoft Graph API; no third-party relay is involved.
- **Revocation.** To revoke access, delete the token cache file and/or navigate to [https://account.microsoft.com/permissions](https://account.microsoft.com/permissions) to remove the Azure app's consent. You can also delete the Azure app registration entirely from the portal.
- **File paths.** `download_attachment` writes only under `OUTLOOK_MCP_FILE_ROOT` and refuses to overwrite existing files. `add_attachment` reads only regular, non-symlink files under `OUTLOOK_MCP_FILE_ROOT`. Relative paths are resolved under that root; absolute paths outside it (and any path traversing a symlink) are rejected. Both tools enforce `OUTLOOK_MCP_MAX_FILE_BYTES`. Review these paths before confirming any tool call that touches the filesystem.

---

## Development

```bash
git clone https://github.com/salahawad/outlook-personal-mcp
cd outlook-personal-mcp
uv venv && uv pip install -e ".[dev]"
uv run pytest
uv run ruff check .
```

---

## Privacy Policy

This server runs entirely on your machine and sends data only between your machine and Microsoft's Graph API — no third-party relay, no telemetry, and the maintainer receives nothing. OAuth tokens are cached locally at `~/.config/outlook-personal-mcp/token_cache.bin` (mode 600). See [PRIVACY.md](PRIVACY.md) for the full privacy policy.

---

## License

MIT — see [LICENSE](LICENSE).