outlook-mcp

<p align="center"><img src="https://raw.githubusercontent.com/Pepebits/outlook-mcp/main/docs/banner.png" alt="outlook-mcp" width="720"></p>

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets Claude, Codex and any other MCP client read, search, send and organize your **Outlook / Microsoft 365 / Outlook.com** mail through the Microsoft Graph API.

---

## 🔭 Overview

`outlook-mcp` runs locally over stdio. It signs in with the **OAuth device code flow** (no client secret, no redirect URI), stores the refresh token in your OS keychain (or a local file only you can read), and talks to Microsoft Graph with plain `fetch`.

## ✨ Features

- 📂 Browse folders, list and search messages (KQL), read bodies as sanitized plain text
- 📎 List and download attachments safely into a configured directory
- ✉️ Send mail, create drafts, reply, reply-all and forward (local attachments up to 150 MB; files of 3 MB or more are uploaded in chunks)
- 🗂️ Move, mark read/unread, flag and delete messages, one at a time or in bulk (`ids`)
- 📰 Find newsletters, unsubscribe from them and block unwanted senders with inbox rules
- 🔒 Read-only mode that removes every mutating tool
- 🔁 Automatic retry with `Retry-After` / exponential backoff for throttling (429/503/504)
- 🧾 Logs only to stderr; never logs tokens or message bodies

## 📋 Requirements

- Node.js **24 (LTS) or newer**
- A Microsoft account (personal works out of the box; work or school needs [your own Azure app](#️-use-your-own-azure-app-optional))

## 🚀 Quick start

No terminal sign-in and no Azure setup needed. You only need Node.js 24+.

### Claude Code

```bash
claude mcp add outlook --scope user -- npx -y @pepebits/outlook-mcp
```

### Claude Desktop

Add to `claude_desktop_config.json` and restart Claude Desktop:

```json
{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@pepebits/outlook-mcp"]
    }
  }
}
```

### Codex (OpenAI)

```bash
codex mcp add outlook -- npx -y @pepebits/outlook-mcp
```

Or add it to `~/.codex/config.toml` (shared by the Codex CLI and IDE extension):

```toml
[mcp_servers.outlook]
command = "npx"
args = ["-y", "@pepebits/outlook-mcp"]
# env = { OUTLOOK_READ_ONLY = "true" }
```

Run `/mcp` inside Codex to check that it is connected.

### Other MCP clients

Any client that can launch a stdio MCP server works: run `npx -y @pepebits/outlook-mcp` as the server command.

### Sign in

Ask your assistant to *"log in to Outlook"*. The `login` tool returns a URL and a one-time code: open the URL, enter the code and accept. Prefer a terminal? Run `npx -y @pepebits/outlook-mcp auth` instead.

By default the server uses the shared **outlook-mcp** Azure app, which supports **personal Microsoft accounts** (outlook.com, hotmail, live). The consent screen may show an *unverified publisher* warning. No data passes through any server of ours: the server talks to Microsoft Graph directly from your machine and your tokens stay in the local token cache. For work or school accounts, or to use your own app, see [Use your own Azure app](#️-use-your-own-azure-app-optional).

## ⚙️ Configuration (`.env`)

The `.env` file is optional. Variables are read from `.env` in the current directory and in the package directory, and real environment variables override it. You can also pass them through your MCP client's env block, e.g. `claude mcp add outlook --scope user -e OUTLOOK_TENANT=organizations -e OUTLOOK_CLIENT_ID=your-client-id -- npx -y @pepebits/outlook-mcp`.

| Variable | Default | Description |
| --- | --- | --- |
| `OUTLOOK_CLIENT_ID` | shared outlook-mcp app | Application (client) ID of your own Azure app registration (optional). |
| `OUTLOOK_TENANT` | `consumers` | Authority tenant: `consumers` (personal), `organizations` (work/school), `common` (both) or a tenant GUID. |
| `OUTLOOK_SCOPES` | `User.Read Mail.ReadWrite Mail.Send MailboxSettings.ReadWrite offline_access` | Space-separated delegated Graph scopes requested at sign-in. |
| `OUTLOOK_TOKEN_STORE` | `auto` | Where the token cache lives: `auto` (OS keychain when available, else file), `keychain` (fails if no keychain) or `file`. See [Token storage](#️-token-storage). |
| `OUTLOOK_TOKEN_CACHE` | `~/.config/outlook-mcp/token-cache.json` | Token cache file (mode `0600`) for the `file` store; also identifies the keychain entry. |
| `OUTLOOK_READ_ONLY` | `false` | When `true`, send/move/delete/flag/mark tools are not registered at all. |
| `OUTLOOK_DOWNLOAD_DIR` | `~/Downloads` | The only directory attachments may be written to. |
| `OUTLOOK_DEFAULT_TOP` | `20` | Default page size for list/search tools (1-100). |
| `OUTLOOK_MAX_BODY_CHARS` | `20000` | Maximum body characters returned by `get_message`. |
| `OUTLOOK_GRAPH_BASE_URL` | `https://graph.microsoft.com/v1.0` | Graph endpoint (change for national clouds). |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn` or `error` (written to stderr). |

## 🔐 Authentication

```bash
npx -y @pepebits/outlook-mcp auth      # device code sign-in; prints a URL and a code
npx -y @pepebits/outlook-mcp whoami    # silent token + GET /me
npx -y @pepebits/outlook-mcp logout    # removes accounts and deletes the token cache (keychain entry and file)
```

You can also sign in without a terminal. Just ask your assistant to *"log in to Outlook"*:

- 🔑 `login` returns a URL and a one-time code. Open the URL, enter the code and accept; sign-in finishes in the background.
- ✅ `auth_status` tells you whether you are signed in, still waiting, or signed out.
- 🚪 `logout` removes the cached account and the token cache (keychain entry and file).

Use `login` with `force: true` to sign in again, for example after adding a permission in Azure. If the session is missing or expired, tools return *"Not signed in or session expired. Call the login tool ..."*.

## 🗝️ Token storage

The refresh token is the most sensitive thing this server holds, so by default (`OUTLOOK_TOKEN_STORE=auto`) it goes into the operating system keychain instead of a plain file. No native npm dependencies are used; the server calls the OS tools directly:

| Platform | Backend | Notes |
| --- | --- | --- |
| macOS | Keychain via the `security` CLI | Service `outlook-mcp`, account = the cache path. |
| Linux | Secret Service via `secret-tool` (libsecret) | Used only if `secret-tool` is installed and a keyring is running; otherwise the file store is used. |
| Windows and others | File | `~/.config/outlook-mcp/token-cache.json`, mode `0600`. |

- **Migration:** if a cache file exists and the keychain is still empty, it is imported into the keychain and the file is deleted.
- **Fallback:** in `auto` mode, if the keychain cannot be used at runtime the server falls back to the file and logs a warning. `OUTLOOK_TOKEN_STORE=keychain` never falls back and fails instead; `file` never touches the keychain.
- **Secrets stay out of process listings:** on Linux `secret-tool` reads the secret from stdin. `security add-generic-password` only accepts the password as a command-line argument (visible in `ps` to other local processes), so on macOS the commands are fed to `security -i` over stdin instead. That interface truncates lines at about 4 KB, so the cache is stored base64 encoded across a few small keychain items (`<account>#0`, `#1`, ...).
- `logout` (tool and CLI) removes the keychain entry as well as the file.
- On macOS the first access from a different binary may show a Keychain prompt; click *Always Allow*.

## 🛠️ Use your own Azure app (optional)

By default `outlook-mcp` uses the shared **outlook-mcp** Azure app, which works with personal Microsoft accounts only. Register your own app if you need **work or school** accounts or simply prefer to use your own. Then set `OUTLOOK_CLIENT_ID` (and `OUTLOOK_TENANT`, see below).

### Step by step

1. Open [portal.azure.com](https://portal.azure.com) and go to **Microsoft Entra ID** -> **App registrations** -> **New registration**.
2. Give it a name (for example `outlook-mcp`).
3. Under **Supported account types** choose:
   - **Personal Microsoft accounts only** (Outlook.com, Hotmail, Live), or
   - **Accounts in any organizational directory and personal Microsoft accounts** (both).
   - For work/school only, pick an organizational option.
4. Leave **Redirect URI** empty and click **Register**.
5. In the left menu go to **Manage** -> **Authentication** -> **Settings** tab, set **Allow public client flows** to **Yes** and save.
6. Go to **Manage** -> **API permissions**. `User.Read` is already granted by default. Click **Add a permission** -> **Microsoft Graph** -> **Delegated permissions** and add:
   - 📬 Expand the **Mail** group and tick `Mail.ReadWrite` and `Mail.Send`.
   - ⚙️ Expand the **MailboxSettings** group and tick `MailboxSettings.ReadWrite` (needed for inbox rules and `block_sender`).
   - 🔑 Expand the **OpenId permissions** group and tick `offline_access`.

   Then click **Add permissions**. No admin consent is needed for personal accounts.

| Scope | Used for |
| --- | --- |
| `User.Read` | Sign-in and `whoami` |
| `Mail.ReadWrite` | Reading, searching, moving, flagging and deleting messages |
| `Mail.Send` | `send_mail`, replies, forwards and mailto unsubscribe |
| `MailboxSettings.ReadWrite` | Inbox rules: `list_rules`, `create_rule`, `delete_rule`, `block_sender` |
| `offline_access` | Refresh token, so you only sign in once |

> 💡 If you upgrade from 0.1.0, add `MailboxSettings.ReadWrite` in Azure and run `login` with `force: true` (or `npx -y @pepebits/outlook-mcp auth`) again.

> 💡 The Azure portal may be shown in your language, so labels can differ slightly (e.g. *Administrar* -> *Autenticación* -> *Configuración*, *Permisos de OpenId*).
7. From the **Overview** page copy the **Application (client) ID**. This is your `OUTLOOK_CLIENT_ID`.

> 🏢 **Work or school accounts:** set `OUTLOOK_CLIENT_ID` to your app and `OUTLOOK_TENANT=organizations` (or your tenant GUID). Your organization may require