Microsoft Outlook MCP

An MCP server that connects Claude (or any MCP client) to Microsoft Outlook — Mail, Calendar, and Contacts — through the Microsoft Graph API using OAuth 2.0 device code flow.

• Cloud-based via Microsoft Graph — works anywhere, for Microsoft 365 and personal Microsoft accounts.
• No client secret required. Device code flow uses a public client app.
• Tokens are cached on disk and refreshed silently, so you sign in once.

Tools

Area	Tools
Account	whoami, auth_status
Mail	list_messages, get_message, send_mail, reply_to_message, update_message, move_message, delete_message
Calendar	list_events, get_event, create_event, update_event, delete_event, respond_to_event
Contacts	list_contacts, get_contact, create_contact, update_contact, delete_contact
Folders	list_mail_folders, create_mail_folder, rename_mail_folder, delete_mail_folder
Inbox rules	list_message_rules, get_message_rule, create_message_rule, update_message_rule, delete_message_rule

1. Register an app in Azure AD (Entra ID)

1. Go to the Azure Portal → Microsoft Entra ID → App registrations → New registration.

2. Name it e.g. Outlook MCP.

3. Supported account types: choose based on the accounts you'll use:

   • Accounts in any organizational directory and personal Microsoft accounts → tenant common
   • This organizational directory only → your specific tenant GUID

4. Leave Redirect URI blank (device code flow doesn't need one). Register.

5. On the app's Overview page, copy the Application (client) ID and Directory (tenant) ID.

6. Authentication → Advanced settings → set Allow public client flows to Yes. (Required for device code flow.)

7. API permissions → Add a permission → Microsoft Graph → Delegated permissions, and add:

   • User.Read
   • Mail.ReadWrite
   • Mail.Send
   • Calendars.ReadWrite
   • Contacts.ReadWrite
   • MailboxSettings.ReadWrite (required for inbox rules)
   • offline_access (added automatically for refresh tokens)

   Click Grant admin consent if you're in an org tenant that requires it.

2. Configure

cd C:\Users\zlalime\Documents\Github\Microsoft-Outlook-MCP
copy .env.example .env

Edit .env and set at least OUTLOOK_CLIENT_ID and OUTLOOK_TENANT_ID.

3. Build & sign in

npm install
npm run build
npm run login

npm run login prints a URL and a code. Open https://microsoft.com/devicelogin, enter the code, and approve. The session is cached in .token-cache.json (git-ignored). Useful variants:

npm run login -- --status   # check whether a session is cached
npm run login -- --logout   # clear the cached session

4. Connect a client

Claude Code

claude mcp add outlook --scope user -- node "C:\Users\zlalime\Documents\Github\Microsoft-Outlook-MCP\dist\index.js"

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["C:\\Users\\zlalime\\Documents\\Github\\Microsoft-Outlook-MCP\\dist\\index.js"]
    }
  }
}

The server reads .env from its own folder, so no env block is needed. If you prefer, you can instead pass the values inline:

"env": {
  "OUTLOOK_CLIENT_ID": "…",
  "OUTLOOK_TENANT_ID": "common"
}

Restart the client. Ask Claude to run auth_status or whoami to confirm.

How auth works

• The MCP server runs non-interactively over stdio, so it never prompts. At request time it acquires tokens silently from the on-disk cache (acquireTokenSilent), refreshing with the stored refresh token as needed.
• Interactive device-code sign-in happens only in the separate npm run login step. Run it again any time a tool reports the session expired.
• The token cache is stored in OS-native encrypted storage via @azure/msal-node-extensions: DPAPI on Windows, Keychain on macOS, libsecret on Linux. The backend is verified at startup; if the native layer can't be loaded, the server logs a warning and falls back to a restricted-permission plaintext file so sign-in still works.
• All diagnostics go to stderr; stdout carries only the MCP JSON-RPC stream.

Environment variables

Variable	Default	Purpose
OUTLOOK_CLIENT_ID	(required)	Azure AD application (client) ID
OUTLOOK_TENANT_ID	common	Tenant GUID or common/organizations/consumers
OUTLOOK_SCOPES	Mail/Calendar/Contacts set	Space-separated delegated Graph scopes
OUTLOOK_TOKEN_CACHE_PATH	.token-cache.json	Where the token cache is stored

Security notes

• The token cache holds live refresh/access tokens. By default it is encrypted at rest using your OS credential store (Windows DPAPI / macOS Keychain / Linux libsecret), tied to your user account. Only if that native backend is unavailable does it fall back to a git-ignored plaintext file written with 0600 permissions — watch the startup log to see which is in use. Either way, run npm run login -- --logout to revoke local access.
• Client ID and tenant ID are not secrets — this is a public client app, so no client secret is stored anywhere.
• Scopes are delegated: the server can only do what your signed-in account can.
• If you upgraded from an earlier version that used a plaintext .token-cache.json, delete that file and re-run npm run login so the cache is rewritten in the encrypted format.

Troubleshooting

Encrypted storage isn't being used (native module)

The encrypted cache is provided by @azure/msal-node-extensions, which relies on a native (N-API) addon. npm install normally downloads a prebuilt binary for your platform. If none is available for your OS/CPU/Node version, the build falls back to compiling from source, which needs a toolchain.

You'll know the native layer failed to load if the startup log shows:

[auth] secure token storage unavailable (...); falling back to a plaintext file...

instead of:

[auth] token cache: OS-native encrypted storage (msal-node-extensions)

The server still works in this state — it just stores tokens in a restricted-permission plaintext file. To get encryption working:

• Windows — install the Visual Studio Build Tools ("Desktop development with C++"), then npm rebuild.
• macOS — install the Xcode command line tools: xcode-select --install, then npm rebuild.
• Linux — install build-essential, python3, and libsecret headers (Debian/Ubuntu: sudo apt-get install build-essential python3 libsecret-1-dev); ensure a Secret Service provider (e.g. GNOME Keyring) is running, then npm rebuild.

After rebuilding, run npm run login -- --status and confirm the log reports OS-native encrypted storage.

AADSTS7000218 or "public client flow" errors during login

Your app registration is missing the public-client setting. In Azure → Authentication → Advanced settings, set Allow public client flows to Yes.

Tools return HTTP 401 / 403 after adding scopes

The cached token predates the new permission. Re-run npm run login (and grant admin consent in Azure if your tenant requires it) so a fresh token carries the added scope.

whoami / tools say "Not signed in"

Run npm run login in a terminal from the project folder. The MCP server never prompts for sign-in itself — it only reads the cached session.

Project layout

src/
  index.ts          MCP server entry: registers tools, connects stdio transport
  login.ts          Standalone device-code sign-in (npm run login)
  config.ts         .env loader + config
  auth.ts           MSAL public client, device code + silent refresh, encrypted cache
  graph.ts          Minimal fetch-based Graph client (auth, paging, errors)
  tools/
    mail.ts         Mail tools
    calendar.ts     Calendar tools
    contacts.ts     Contacts tools
    rules.ts        Mail folder management + inbox rule tools
    util.ts         ok()/fail() result helpers

License

MIT