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

``bash
npm install outlook-mcp-device-flow
`

Or run directly with npx:

`bash
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

$3

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

$3

Add to your claude_desktop_config.json:

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

$3

Add to your .mcp.json:

`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

$3


| 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 |

$3

| 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 |

$3

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

$3

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

$3

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

$3

| 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 john@example.com about the meeting"
- "Download the PDF attachment from that email"
- "Flag the important emails about invoices"
- "Mark all emails from newsletter@example.com 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

`bash


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 (@ansuhail.ak@gmail.com)