Outlook for Work/School 365

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

Security Scan

The skill's code and instructions align with its stated purpose: it uses Azure/OAuth and Microsoft Graph to access and manage Outlook mail and calendar; the requested actions and stored secrets are proportionate to that goal.

Purpose & Capability

Name/description match the code: scripts call Microsoft Graph, perform calendar and mail operations, and the setup creates an Azure app registration and requests Mail.ReadWrite, Mail.Send, Calendars.ReadWrite and offline_access scopes — all expected for full mailbox/calendar management.

Instruction Scope

Runtime instructions direct the user to run an automated setup that logs into Azure, creates an app registration, creates a client secret, guides user authorization, and saves tokens and credentials under ~/.outlook-mcp. This is consistent with the skill's purpose but does store sensitive credentials and tokens on disk; the scripts do not appear to read unrelated files or exfiltrate data to third-party endpoints.

Install Mechanism

No external install/download is performed by the skill bundle; it is instruction+script based and relies on local tools (az, jq, curl). There are no obscure or remote installers, and no extracted archives or external binaries fetched by the skill.

Credentials

The skill requests no platform env vars but creates and stores a client_id/client_secret/tenant and access/refresh tokens in ~/.outlook-mcp — this is necessary for a confidential OAuth client but is sensitive. The OAuth scopes requested are appropriate for the stated mail/calendar functionality.

Persistence & Privilege

always:false and the skill does not auto-enable itself. It will create an Azure App Registration and a client secret in the user's tenant (if the authenticated account has permissions) and write config/tokens to the user's home directory — side effects that affect the user's Azure tenant and local filesystem but are expected for this functionality.

Assessment

This skill appears to do what it says, but be aware of these practical security points before installing: 1) The automated setup will create an Azure App Registration and a client secret in the authenticated Azure account/tenant — that requires appropriate privileges and may require admin consent for some tenants. 2) The client_secret and OAuth tokens are stored on disk at ~/.outlook-mcp/config.json and credentials.json; anyone with access to those files could use them to access your mailbox until you revoke them. 3) If you prefer tighter control, perform the manual setup (references/setup.md) and create the app yourself in the Azure Portal, then paste only the minimal config into ~/.outlook-mcp. 4) After use, revoke the app secret or delete the App Registration and remove ~/.outlook-mcp to invalidate access. 5) Inspect the included scripts (they are plain shell) before running and ensure az, jq, and curl are trusted on your system.

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 (including tenant context) 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 <email> [count]    # List emails from sender
./scripts/outlook-mail.sh read <id>               # Read email content
./scripts/outlook-mail.sh attachments <id>        # List email attachments

Managing Emails

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

Sending Emails

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

Drafts

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

Attachment Download

./scripts/outlook-mail.sh download <id> <name> [path] # Download attachment

Focused Inbox & Threads

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

Categories

./scripts/outlook-mail.sh categories               # List categories
./scripts/outlook-mail.sh categorize <id> <name>   # Add category
./scripts/outlook-mail.sh uncategorize <id>        # Remove categories

Folder Management

./scripts/outlook-mail.sh create-folder <name> [parent] # Create folder
./scripts/outlook-mail.sh delete-folder <name>          # Delete folder

Bulk Operations

./scripts/outlook-mail.sh bulk-read <id1> <id2>...   # Mark multiple as read
./scripts/outlook-mail.sh bulk-delete <id1> <id2>... # Delete multiple messages

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 <id>           # Event details
./scripts/outlook-calendar.sh calendars           # List all calendars
./scripts/outlook-calendar.sh free <start> <end>  # Check availability

Creating Events

./scripts/outlook-calendar.sh create <subj> <start> <end> [location]  # Create event
./scripts/outlook-calendar.sh quick <subject> [time]                  # Quick 1-hour event

Managing Events

./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)

Example Output

$ ./scripts/outlook-mail.sh inbox 3

{
  "n": 1,
  "subject": "Your weekly digest",
  "from": "[e-mail]",
  "date": "2026-01-25T15:44",
  "read": false,
  "id": "icYY6QAIUE26PgAAAA=="
}
{
  "n": 2,
  "subject": "Meeting reminder",
  "from": "[e-mail]",
  "date": "2026-01-25T14:06",
  "read": true,
  "id": "icYY6QAIUE26PQAAAA=="
}

$ ./scripts/outlook-mail.sh read "icYY6QAIUE26PgAAAA=="

{
  "subject": "Your weekly digest",
  "from": { "name": "Digest", "address": "[e-mail]" },
  "to": ["[e-mail]"],
  "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 - Tenant ID, client ID, and client 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

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

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