Outlook
by @jotamed
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.
clawhub install outlookπ About This Skill
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)
# 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
./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
./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
./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
./scripts/outlook-mail.sh send # Send new email
./scripts/outlook-mail.sh reply "body" # Reply to email
Folders & Stats
./scripts/outlook-mail.sh folders # List mail folders
./scripts/outlook-mail.sh stats # Inbox statistics
Calendar
Viewing Events
./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
./scripts/outlook-calendar.sh create [location] # Create event
./scripts/outlook-calendar.sh quick [time] # Quick 1-hour event
Managing Events
./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
$ ./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:
./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 emailsMail.Send - Send emailsCalendars.ReadWrite - Read and modify calendar eventsoffline_access - Refresh tokens (stay logged in)User.Read - Basic profile infoNotes
id 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.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
Changelog
v1.3.0
outlook-calendar.sh)Calendars.ReadWrite permissionv1.2.0
mark-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 errorv1.1.0
to field in read outputv1.0.0
π‘ Examples
Token Management
./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
./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
./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
./scripts/outlook-mail.sh send # Send new email
./scripts/outlook-mail.sh reply "body" # Reply to email
Folders & Stats
./scripts/outlook-mail.sh folders # List mail folders
./scripts/outlook-mail.sh stats # Inbox statistics
π Tips & Best Practices
id 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.