--- name: outlook description: Read, search, and manage Outlook emails and calendar via Microsoft Graph API. Use when the user asks about emails, inbox, Outlook, Microsoft mail, calendar events, or scheduling. version: 1.3.0 author: jotamed --- # Outlook Skill Access Outlook/Hotmail email and calendar via Microsoft Graph API using OAuth2. ## Quick Setup (Automated) ```bash # Requires: Azure CLI, jq ./scripts/outlook-setup.sh ``` The setup script will: 1. Log you into Azure (device code flow) 2. Create an App Registration automatically 3. Configure API permissions (Mail.ReadWrite, Mail.Send, Calendars.ReadWrite) 4. Guide you through authorization 5. Save credentials to `~/.outlook-mcp/` ## Manual Setup See `references/setup.md` for step-by-step manual configuration via Azure Portal. ## Usage ### Token Management ```bash ./scripts/outlook-token.sh refresh # Refresh expired token ./scripts/outlook-token.sh test # Test connection ./scripts/outlook-token.sh get # Print access token ``` ### Reading Emails ```bash ./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 [count] # List emails from sender ./scripts/outlook-mail.sh read # Read email content ./scripts/outlook-mail.sh attachments # List email attachments ``` ### Managing Emails ```bash ./scripts/outlook-mail.sh mark-read # Mark as read ./scripts/outlook-mail.sh mark-unread # Mark as unread ./scripts/outlook-mail.sh flag # Flag as important ./scripts/outlook-mail.sh unflag # Remove flag ./scripts/outlook-mail.sh delete # Move to trash ./scripts/outlook-mail.sh archive # Move to archive ./scripts/outlook-mail.sh move # Move to folder ``` ### Sending Emails ```bash ./scripts/outlook-mail.sh send # Send new email ./scripts/outlook-mail.sh reply "body" # Reply to email ``` ### Folders & Stats ```bash ./scripts/outlook-mail.sh folders # List mail folders ./scripts/outlook-mail.sh stats # Inbox statistics ``` ## Calendar ### Viewing Events ```bash ./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 # Event details ./scripts/outlook-calendar.sh calendars # List all calendars ./scripts/outlook-calendar.sh free # Check availability ``` ### Creating Events ```bash ./scripts/outlook-calendar.sh create [location] # Create event ./scripts/outlook-calendar.sh quick [time] # Quick 1-hour event ``` ### Managing Events ```bash ./scripts/outlook-calendar.sh update # Update (subject/location/start/end) ./scripts/outlook-calendar.sh delete # Delete event ``` Date format: `YYYY-MM-DDTHH:MM` (e.g., `2026-01-26T10:00`) ### Example Output ```bash $ ./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..." } ``` ## Token Refresh Access tokens expire after ~1 hour. Refresh with: ```bash ./scripts/outlook-token.sh refresh ``` ## Files - `~/.outlook-mcp/config.json` - Client ID and secret - `~/.outlook-mcp/credentials.json` - OAuth tokens (access + refresh) ## Permissions - `Mail.ReadWrite` - Read and modify emails - `Mail.Send` - Send emails - `Calendars.ReadWrite` - Read and modify calendar events - `offline_access` - Refresh tokens (stay logged in) - `User.Read` - Basic profile info ## Notes - **Email IDs**: The `id` field shows the last 20 characters of the full message ID. Use this ID with commands like `read`, `mark-read`, `delete`, etc. - **Numbered results**: Emails are numbered (n: 1, 2, 3...) for easy reference in conversation. - **Text extraction**: HTML email bodies are automatically converted to plain text. - **Token expiry**: Access tokens expire after ~1 hour. Run `outlook-token.sh refresh` when you see auth errors. - **Recent emails**: Commands like `read`, `mark-read`, etc. search the 100 most recent emails for the ID. ## Troubleshooting **"Token expired"** → Run `outlook-token.sh refresh` **"Invalid grant"** → Token invalid, re-run setup: `outlook-setup.sh` **"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. ## Supported Accounts - Personal Microsoft accounts (outlook.com, hotmail.com, live.com) - Work/School accounts (Microsoft 365) - may require admin consent ## Changelog ### v1.3.0 - Added: **Calendar support** (`outlook-calendar.sh`) - View events (today, week, upcoming) - Create/quick-create events - Update event details (subject, location, time) - Delete events - Check availability (free/busy) - List calendars - Added: `Calendars.ReadWrite` permission ### v1.2.0 - Added: `mark-unread` - Mark emails as unread - Added: `flag/unflag` - Flag/unflag emails as important - Added: `delete` - Move emails to trash - Added: `archive` - Archive emails - Added: `move` - Move emails to any folder - Added: `from` - Filter emails by sender - Added: `attachments` - List email attachments - Added: `reply` - Reply to emails - Improved: `send` - Better error handling and status output - Improved: `move` - Case-insensitive folder names, shows available folders on error ### v1.1.0 - Fixed: Email IDs now use unique suffixes (last 20 chars) - Added: Numbered results (n: 1, 2, 3...) - Improved: HTML bodies converted to plain text - Added: `to` field in read output ### v1.0.0 - Initial release

Outlook

Security Scan

Details

Outlook

Security Scan

Details