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 (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 → 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, the whole registration is one command:

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.

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):

{
  "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:

[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 (.mcpb). Build the bundle from a checkout:

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 must be installed and on your PATH — Claude Desktop does not bundle it (see Prerequisites). Codex and other stdio hosts use the config above instead of the .mcpb.

Configuration (Environment Variables)

Tools

Account

Mail

Folders

Drafts

Calendar

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 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

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 for the full privacy policy.

License

MIT — see LICENSE.