Outlook MCP Server

A Model Context Protocol (MCP) server that gives AI assistants (Claude, Cursor, etc.) full access to your Microsoft Outlook — emails, calendar, and contacts — via the Microsoft Graph API.

Features

Related MCP server: Microsoft MCP

Prerequisites

• Node.js 18+ (tested with v22)

• A Microsoft 365 or Outlook account

• An Azure AD (Entra ID) app registration (free, takes ~5 minutes)

Step 1: Register an Azure AD Application

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

2. Fill in:

   • Name: Outlook MCP (or any name)

   • Supported account types: Choose based on your setup:

     • Personal Microsoft accounts only → for @outlook.com / @hotmail.com

     • Accounts in any organizational directory and personal accounts → for work + personal

   • Redirect URI: Leave blank (we use device code flow)

3. Click Register. Copy the Application (client) ID — this is your OUTLOOK_CLIENT_ID.

4. Copy the Directory (tenant) ID if you're using a work/school account — this is your OUTLOOK_TENANT_ID. For personal accounts use consumers.

5. Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions. Add:

   • Mail.ReadWrite

   • Mail.Send

   • Calendars.ReadWrite

   • Contacts.ReadWrite

   • MailboxSettings.ReadWrite

   • User.Read

   • offline_access

6. Click Grant admin consent (if you're an admin) or ask your admin to do so.

7. Go to Authentication → Enable Allow public client flows → Yes → Save.

Step 2: Build the Server

cd outlook-mcp
npm install
npm run build

Step 3: Configure in Cursor (or Claude Desktop)

Cursor

Add to your Cursor MCP config (~/.cursor/mcp.json or via Settings → MCP):

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/absolute/path/to/outlook-mcp/dist/index.js"],
      "env": {
        "OUTLOOK_CLIENT_ID": "YOUR_CLIENT_ID_HERE",
        "OUTLOOK_TENANT_ID": "common"
      }
    }
  }
}

Use "common" for multi-tenant, "consumers" for personal accounts (@outlook.com / @hotmail.com), or your specific tenant ID for work/school accounts.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/absolute/path/to/outlook-mcp/dist/index.js"],
      "env": {
        "OUTLOOK_CLIENT_ID": "YOUR_CLIENT_ID_HERE",
        "OUTLOOK_TENANT_ID": "common"
      }
    }
  }
}

Step 4: First-Time Authentication

The first time a tool is called, the server uses Device Code Flow:

1. A message will appear in the MCP client (or stderr) like:

   To sign in, use a web browser to open the page https://microsoft.com/devicelogin
   and enter the code ABCD1234 to authenticate.

2. Open that URL in your browser, enter the code, and sign in with your Microsoft account.

3. The token is cached at ~/.outlook-mcp-token-cache.json (permissions 600) and refreshed automatically.

4. You won't need to authenticate again until the refresh token expires (~90 days of inactivity).

Available Tools

Auth

Email

Calendar

Contacts

Development

# Run directly with tsx (no build step)
OUTLOOK_CLIENT_ID=xxx npm run dev

# Rebuild after changes
npm run build

Troubleshooting

"OUTLOOK_CLIENT_ID environment variable is required" → Make sure you've set the env var in your MCP config.

"AADSTS50011: The redirect URI ... was not found" → Enable Allow public client flows in Azure Portal → App Registration → Authentication.

"Insufficient privileges" → Add the missing Graph API permissions and re-grant admin consent. Then run outlook_sign_out and re-authenticate.

Token keeps expiring → Make sure offline_access is in your API permissions.