Read, search, and manage Outlook emails and calendar via Microsoft Graph API. Use when the user asks about emails, inbox, Outlook, Microsoft mail, calendar e...
Access Outlook/Hotmail email and calendar via Microsoft Graph API using OAuth2.
# Requires: Azure CLI, jq
./scripts/outlook-setup.sh
The setup script will:
~/.outlook-mcp/See references/setup.md for step-by-step manual configuration via Azure Portal.
./scripts/outlook-token.sh refresh # Refresh expired token
./scripts/outlook-token.sh test # Test connection
./scripts/outlook-token.sh get # Print access token
./scripts/outlook-mail.sh inbox [count] # List latest emails (default: 10)
./scripts/outlook-mail.sh unread [count] # List unread emails
./scripts/outlook-mail.sh search "query" [count] # Search emails
./scripts/outlook-mail.sh from <email> [count] # List emails from sender
./scripts/outlook-mail.sh read <id> # Read email content
./scripts/outlook-mail.sh attachments <id> # List email attachments
./scripts/outlook-mail.sh mark-read <id> # Mark as read
./scripts/outlook-mail.sh mark-unread <id> # Mark as unread
./scripts/outlook-mail.sh flag <id> # Flag as important
./scripts/outlook-mail.sh unflag <id> # Remove flag
./scripts/outlook-mail.sh delete <id> # Move to trash
./scripts/outlook-mail.sh archive <id> # Move to archive
./scripts/outlook-mail.sh move <id> <folder> # Move to folder
./scripts/outlook-mail.sh send <to> <subj> <body> # Send new email
./scripts/outlook-mail.sh reply <id> "body" # Reply to email
./scripts/outlook-mail.sh forward <id> <to> [msg] # Forward email
./scripts/outlook-mail.sh draft <to> <subj> <body> # Create draft
./scripts/outlook-mail.sh drafts [count] # List drafts
./scripts/outlook-mail.sh send-draft <id> # Send a draft
./scripts/outlook-mail.sh download <id> <name> [path] # Download attachment
./scripts/outlook-mail.sh focused [count] # Focused/important inbox
./scripts/outlook-mail.sh other [count] # Other/low-priority inbox
./scripts/outlook-mail.sh thread <id> # Conversation thread by message
./scripts/outlook-mail.sh categories # List categories
./scripts/outlook-mail.sh categorize <id> <name> # Add category
./scripts/outlook-mail.sh uncategorize <id> # Remove categories
./scripts/outlook-mail.sh create-folder <name> [parent] # Create folder
./scripts/outlook-mail.sh delete-folder <name> # Delete folder
./scripts/outlook-mail.sh bulk-read <id1> <id2>... # Mark multiple as read
./scripts/outlook-mail.sh bulk-delete <id1> <id2>... # Delete multiple messages
./scripts/outlook-mail.sh folders # List mail folders
./scripts/outlook-mail.sh stats # Inbox statistics
./scripts/outlook-calendar.sh events [count] # List upcoming events
./scripts/outlook-calendar.sh today # Today's events
./scripts/outlook-calendar.sh week # This week's events
./scripts/outlook-calendar.sh read <id> # Event details
./scripts/outlook-calendar.sh calendars # List all calendars
./scripts/outlook-calendar.sh free <start> <end> # Check availability
./scripts/outlook-calendar.sh create <subj> <start> <end> [location] # Create event
./scripts/outlook-calendar.sh quick <subject> [time] # Quick 1-hour event
./scripts/outlook-calendar.sh update <id> <field> <value> # Update (subject/location/start/end)
./scripts/outlook-calendar.sh delete <id> # Delete event
Date format: YYYY-MM-DDTHH:MM (e.g., 2026-01-26T10:00)
$ ./scripts/outlook-mail.sh inbox 3
{
"n": 1,
"subject": "Your weekly digest",
"from": "digest@example.com",
"date": "2026-01-25T15:44",
"read": false,
"id": "icYY6QAIUE26PgAAAA=="
}
{
"n": 2,
"subject": "Meeting reminder",
"from": "calendar@outlook.com",
"date": "2026-01-25T14:06",
"read": true,
"id": "icYY6QAIUE26PQAAAA=="
}
$ ./scripts/outlook-mail.sh read "icYY6QAIUE26PgAAAA=="
{
"subject": "Your weekly digest",
"from": { "name": "Digest", "address": "digest@example.com" },
"to": ["you@hotmail.com"],
"date": "2026-01-25T15:44:00Z",
"body": "Here's what happened this week..."
}
$ ./scripts/outlook-mail.sh stats
{
"folder": "Inbox",
"total": 14098,
"unread": 2955
}
$ ./scripts/outlook-calendar.sh today
{
"n": 1,
"subject": "Team standup",
"start": "2026-01-25T10:00",
"end": "2026-01-25T10:30",
"location": "Teams",
"id": "AAMkAGQ5NzE4YjQ3..."
}
$ ./scripts/outlook-calendar.sh create "Lunch with client" "2026-01-26T13:00" "2026-01-26T14:00" "Restaurant"
{
"status": "event created",
"subject": "Lunch with client",
"start": "2026-01-26T13:00",
"end": "2026-01-26T14:00",
"id": "AAMkAGQ5NzE4YjQ3..."
}
Access tokens expire after ~1 hour. Refresh with:
./scripts/outlook-token.sh refresh
~/.outlook-mcp/config.json - Tenant ID, client ID, and client secret~/.outlook-mcp/credentials.json - OAuth tokens (access + refresh)Mail.ReadWrite - Read and modify emailsMail.Send - Send emailsCalendars.ReadWrite - Read and modify calendar eventsoffline_access - Refresh tokens (stay logged in)User.Read - Basic profile infoid field shows the last 20 characters of the full message ID. Use this ID with commands like read, mark-read, delete, etc.outlook-token.sh refresh when you see auth errors.read, mark-read, etc. search the 100 most recent emails for the ID."Token expired" → Run outlook-token.sh refresh
"Invalid grant" → Token invalid, re-run setup: outlook-setup.sh
"AADSTS50194" → App is single-tenant but endpoint used /common; use tenant-specific endpoint or re-run outlook-setup.sh
"AADSTS700025" → App is configured as public client; disable public client flow in App Registration Authentication settings
"Insufficient privileges" → Check app permissions in Azure Portal → API Permissions
"Message not found" → The email may be older than 100 messages. Use search to find it first.
"Folder not found" → Use exact folder name. Run folders to see available folders.
outlook-calendar.sh)
Calendars.ReadWrite permissionmark-unread - Mark emails as unreadflag/unflag - Flag/unflag emails as importantdelete - Move emails to trasharchive - Archive emailsmove - Move emails to any folderfrom - Filter emails by senderattachments - List email attachmentsreply - Reply to emailssend - Better error handling and status outputmove - Case-insensitive folder names, shows available folders on errorto field in read outputZIP package — ready to use