outlook-mcp

MCP server for Claude that provides full Outlook email management via Microsoft Graph API. Read, send, organize, draft, and bulk-manage emails — all from Claude Code or Claude Desktop.

Quick Install

claude mcp add outlook -e OUTLOOK_CLIENT_ID=your_client_id -- npx -y @hamzashahbaz/outlook-mcp

Features

19 tools for complete email management:

Reading

| Tool | Description | |------|-------------| | outlook_list_messages | List emails in a folder with pagination and OData filters | | outlook_get_message | Get full email details by message ID | | outlook_search_messages | Search emails using KQL queries | | outlook_list_folders | List all mail folders with unread counts |

Sending

| Tool | Description | |------|-------------| | outlook_send_email | Send a new email to one or more recipients | | outlook_reply | Reply to an email (reply or reply-all) | | outlook_forward | Forward an email to new recipients |

Drafts

| Tool | Description | |------|-------------| | outlook_create_draft | Create a draft email (saved, not sent) | | outlook_update_draft | Update an existing draft | | outlook_send_draft | Send a previously created draft | | outlook_delete_draft | Delete a draft |

Organization

| Tool | Description | |------|-------------| | outlook_move_message | Move a message to a different folder | | outlook_delete_message | Delete a message (moves to Deleted Items) | | outlook_update_message | Mark as read/unread, flag/unflag | | outlook_mark_all_read | Mark all messages in a folder as read | | outlook_create_folder | Create a new mail folder | | outlook_empty_folder | Permanently delete all messages in a folder |

Bulk Operations

| Tool | Description | |------|-------------| | outlook_bulk_move_by_sender | Move all emails from a sender domain to a folder | | outlook_bulk_move_by_search | Move emails matching a KQL search query to a folder |

Prerequisites

• Node.js 18+
• Azure App Registration with device code flow enabled

Setup

Azure App Registration

1. Go to Azure Portal > App Registrations > New Registration
2. Name: Outlook MCP (or anything you like)
3. Supported account types: Personal Microsoft accounts only (or include organizational if needed)
4. Redirect URI: Leave blank (device code flow doesn't need one)
5. Under Authentication > Advanced settings:
   • Enable Allow public client flows (required for device code)
6. Under API Permissions, add Microsoft Graph delegated permissions:
   • Mail.ReadWrite
   • Mail.Send
   • User.Read
7. Copy the Application (client) ID — this is your OUTLOOK_CLIENT_ID

Authentication

On first run, the server initiates an OAuth 2.0 device code flow:

1. A URL and code are displayed in stderr output
2. Open the URL in your browser and enter the code
3. Sign in with your Microsoft account and grant permissions
4. Tokens are saved automatically for future use

Tokens auto-refresh using the refresh token. If a refresh fails (e.g., token revoked), delete the token file and restart — the device code flow will trigger again.

Configuration

Claude Code

Add via CLI (recommended):

claude mcp add outlook -e OUTLOOK_CLIENT_ID=your_client_id -- npx -y @hamzashahbaz/outlook-mcp

Or add manually to .mcp.json:

{
  "mcpServers": {
    "outlook": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hamzashahbaz/outlook-mcp"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your_client_id"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@hamzashahbaz/outlook-mcp"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your_client_id"
      }
    }
  }
}

Token Storage

Tokens are stored at ~/.outlook-mcp/.tokens.json with 600 permissions (owner read/write only). This location persists across npx invocations.

The file contains:

• Access token — short-lived, auto-refreshed
• Refresh token — long-lived, used to obtain new access tokens

To re-authenticate, delete the token file:

rm ~/.outlook-mcp/.tokens.json

Folder Names

Standard Outlook folder names: Inbox, SentItems, Drafts, DeletedItems, Archive, JunkEmail

Custom folders use the display name as created.

Troubleshooting

"OUTLOOK_CLIENT_ID environment variable is required"

Set OUTLOOK_CLIENT_ID in your MCP configuration's env block.

Authentication expired

Delete the token file and restart:

rm ~/.outlook-mcp/.tokens.json

The device code flow will trigger again on next use.

"Insufficient privileges"

Check your Azure App Registration > API Permissions. Ensure Mail.ReadWrite and Mail.Send are granted. For organizational accounts, admin consent may be required.

Rate limited

Microsoft Graph enforces rate limits. The server reports the Retry-After header value. Wait and retry.

Known Limitations

• Cannot delete mail folders — Microsoft Graph API does not support folder deletion for personal accounts
• Search pagination — KQL search results are limited to 25 per request (the server handles pagination internally)
• Bulk operations — Process up to 200-500 messages per call to avoid timeouts

How It Works

• API: Microsoft Graph API v1.0
• Auth: OAuth 2.0 device code flow
• Protocol: Model Context Protocol (MCP) over stdio
• Validation: Zod schemas for all tool inputs
• Built for: Claude Code and Claude Desktop

License

MIT