How do I install the Outlook skill?

Run npx skillmds@latest add cristiandan/outlook in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Outlook skill do?

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. It is listed under Integrations & APIs on SkillMD.

Is Outlook safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Outlook?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Outlook free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Outlook?

cristiandan (@cristiandan) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Outlook by cristiandan — Agent Skill

Name: Outlook
Rating: 4.5 (4 reviews)
Author: cristiandan

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:

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.

Multiple Accounts

You can connect multiple Outlook accounts (personal, work, etc.):

Setup additional accounts

./scripts/outlook-setup.sh --account work
./scripts/outlook-setup.sh --account personal

Use specific account

./scripts/outlook-mail.sh --account work inbox
./scripts/outlook-calendar.sh --account personal today
./scripts/outlook-token.sh --account work refresh

Or use environment variable

export OUTLOOK_ACCOUNT=work
./scripts/outlook-mail.sh inbox

List configured accounts

./scripts/outlook-token.sh list

Credentials are stored separately:

~/.outlook-mcp/
  default/
    config.json
    credentials.json
  work/
    config.json  
    credentials.json

Existing single-account setups are auto-migrated to default.

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

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

Feature: Multi-account support
- Use --account NAME flag or OUTLOOK_ACCOUNT env var
- Setup additional accounts with outlook-setup.sh --account work
- List accounts with outlook-token.sh list
- Auto-migrates existing single-account setups to default

v1.3.2

Fixed: Timezone no longer hardcoded to Europe/Madrid
- Auto-detects system timezone (macOS + Linux)
- Can override with OUTLOOK_TZ environment variable
- Falls back to UTC if detection fails

v1.3.1

Security: Fixed path traversal vulnerability in download command
- Attachment filenames are now sanitized using basename and stripped of .. sequences
- Prevents malicious attachments from writing to arbitrary filesystem paths
- Reported by VirusTotal Code Insights

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

File contents

Outlook Skill

Quick Setup (Automated)

Manual Setup

Multiple Accounts

Setup additional accounts

Use specific account

Or use environment variable

List configured accounts

Usage

Token Management

Reading Emails

Managing Emails

Sending Emails

Folders & Stats

Calendar

Viewing Events

Creating Events

Managing Events

Example Output

Token Refresh

Files

Permissions

Notes

Troubleshooting

Supported Accounts

Changelog

v1.4.0

v1.3.2

v1.3.1

v1.3.0

v1.2.0

v1.1.0

v1.0.0

Frequently asked questions

Outlook

File contents

Outlook Skill

Quick Setup (Automated)

Manual Setup

Multiple Accounts

Setup additional accounts

Use specific account

Or use environment variable

List configured accounts

Usage

Token Management

Reading Emails

Managing Emails

Sending Emails

Folders & Stats

Calendar

Viewing Events

Creating Events

Managing Events

Example Output

Token Refresh

Files

Permissions

Notes

Troubleshooting

Supported Accounts

Changelog

v1.4.0

v1.3.2

v1.3.1

v1.3.0

v1.2.0

v1.1.0

v1.0.0

Related skills

Frequently asked questions

How do I install the Outlook skill?

What does the Outlook skill do?

Is Outlook safe to use?

Which AI agents work with Outlook?

Is Outlook free to use?

Who published Outlook?