outlook-mcp-device-flow

An Outlook/Microsoft 365 MCP (Model Context Protocol) server that provides email management capabilities through the Microsoft Graph API. Uses Device Flow authentication for easy setup. Works with Claude Desktop, Claude Code, and any MCP-compatible client.

Features

• Focused/Other Inbox: Fetch emails by Outlook's smart classification (Focused vs Other)
• Full Email Management: Read, send, reply, flag, delete, and move emails
• Attachment Handling: List, download, and save attachments to disk
• Categories: Add/remove categories to mark emails (e.g., "AI-Processed")
• Batch Operations: Get multiple emails in a single request
• Thread Support: Fetch entire email conversations by thread ID
• Date Filtering: Filter emails by date range

Installation

npm install outlook-mcp-device-flow

Or run directly with npx:

npx outlook-mcp-device-flow

Prerequisites

1. A Microsoft 365 or Outlook.com account
2. Azure App Registration (free):
   • Go to Azure Portal
   • Navigate to Azure Active Directory → App registrations → New registration
   • Name: "Outlook MCP" (or any name)
   • Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"
   • Redirect URI: Leave blank (we use Device Flow)
   • Click Register
   • Copy the Application (client) ID
   • Go to Authentication → Enable "Allow public client flows" → Save
   • Go to API Permissions → Add a permission → Microsoft Graph → Delegated permissions
   • Add: Mail.Read, Mail.ReadWrite, Mail.Send, User.Read
   • Click Grant admin consent (if you have admin access) or users will consent on first use

Configuration

Environment Variables

export OUTLOOK_CLIENT_ID="your-azure-app-client-id"
export OUTLOOK_TENANT_ID="common"  # Use "common" for personal + work accounts

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["outlook-mcp-device-flow"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-azure-app-client-id",
        "OUTLOOK_TENANT_ID": "common"
      }
    }
  }
}

Claude Code Configuration

Add to your .mcp.json:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["outlook-mcp-device-flow"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-azure-app-client-id",
        "OUTLOOK_TENANT_ID": "common"
      }
    }
  }
}

First-Time Authentication

On first use, the server will prompt you to:

1. Open a URL in your browser
2. Enter a code displayed in the terminal
3. Sign in with your Microsoft account
4. Grant the requested permissions

Tokens are cached locally, so you only need to do this once (until they expire).

Available Tools

Email Retrieval Tools

| Tool | Description | |------|-------------| | get_focused_emails | Important emails (like Gmail Primary) | | get_other_emails | Newsletters, notifications (like Gmail Promotions) | | get_inbox_emails | All inbox emails regardless of classification | | search_emails | Search emails using KQL syntax | | get_emails_with_attachments | Emails that have attachments | | get_email_content | Full email content by ID | | get_emails_by_folder | Emails from a specific folder | | list_folders | List all mail folders |

Action Tools

| Tool | Description | |------|-------------| | send_email | Send a new email | | reply_to_email | Reply to an existing email | | mark_as_read | Mark email as read | | mark_as_unread | Mark email as unread | | flag_email | Flag or unflag an email (like starring) | | delete_email | Move email to Deleted Items | | move_to_folder | Move email to a specific folder |

Attachment Tools

| Tool | Description | |------|-------------| | list_attachments | List attachments in an email | | download_attachment | Download attachment as Base64 | | save_attachment | Save attachment to disk |

Category Tools

| Tool | Description | |------|-------------| | set_email_category | Add/remove category from email | | create_master_category | Create a new category | | list_master_categories | List all available categories |

Batch & Thread Tools

| Tool | Description | |------|-------------| | get_emails_batch | Get multiple emails in one request (up to 20) | | get_email_thread | Get all emails in a conversation |

Utility Tools

| Tool | Description | |------|-------------| | get_current_user | Get authenticated user info |

Usage Examples

Once configured, you can ask Claude:

• "Show me my focused emails from today"
• "Search for emails from Amazon"
• "Read the email with ID abc123"
• "Send an email to [email protected] about the meeting"
• "Download the PDF attachment from that email"
• "Flag the important emails about invoices"
• "Mark all emails from [email protected] as read"

Why Device Flow Authentication?

• No Redirect URI needed: Works without a web server
• Headless compatible: Perfect for CLI and MCP servers
• Secure: No client secret required for public clients
• User-friendly: Simple browser-based sign-in

Development

# Clone the repository
git clone https://github.com/suhailak/outlook-mcp.git
cd outlook-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run production build
npm start

License

MIT

Author

Suhail (@[email protected])