| 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)
./scripts/outlook-setup.sh
The setup script will:
- Log you into Azure (device code flow)
- Create an App Registration automatically
- Configure API permissions (Mail.ReadWrite, Mail.Send, Calendars.ReadWrite)
- Guide you through authorization
- 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
./scripts/outlook-token.sh test
./scripts/outlook-token.sh get
Reading Emails
./scripts/outlook-mail.sh inbox [count]
./scripts/outlook-mail.sh unread [count]
./scripts/outlook-mail.sh search "query" [count]
./scripts/outlook-mail.sh from <email> [count]
./scripts/outlook-mail.sh read <id>
./scripts/outlook-mail.sh attachments <id>
Managing Emails
./scripts/outlook-mail.sh mark-read <id>
./scripts/outlook-mail.sh mark-unread <id>
./scripts/outlook-mail.sh flag <id>
./scripts/outlook-mail.sh unflag <id>
./scripts/outlook-mail.sh delete <id>
./scripts/outlook-mail.sh archive <id>
./scripts/outlook-mail.sh move <id> <folder>
Sending Emails
./scripts/outlook-mail.sh send <to> <subj> <body>
./scripts/outlook-mail.sh reply <id> "body"
Folders & Stats
./scripts/outlook-mail.sh folders
./scripts/outlook-mail.sh stats
Calendar
Viewing Events
./scripts/outlook-calendar.sh events [count]
./scripts/outlook-calendar.sh today
./scripts/outlook-calendar.sh week
./scripts/outlook-calendar.sh read <id>
./scripts/outlook-calendar.sh calendars
./scripts/outlook-calendar.sh free <start> <end>
Creating Events
./scripts/outlook-calendar.sh create <subj> <start> <end> [location]
./scripts/outlook-calendar.sh quick <subject> [time]
Managing Events
./scripts/outlook-calendar.sh update <id> <field> <value>
./scripts/outlook-calendar.sh delete <id>
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 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
