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