outlook-cli

Production-ready CLI and MCP server for Microsoft Outlook through Microsoft Graph.

GitHub: https://github.com/selvin-paul-raj/outlook-cli

What This Package Gives You

• Global CLI command: outlook-cli
• One-time OAuth token storage — reused across runs and updates
• Human-friendly commands with rich terminal output, theme presets, and machine-friendly --json/--ai mode
• 21 MCP tools available to Claude and other AI assistants via the shared tool registry
• Full email, calendar, folder, and rules management through Microsoft Graph API

Install

Global (recommended)

npm i -g outlook-cli

outlook-cli --help

Local development

npm install
npm run cli -- --help

Requirements: Node.js >= 18.0.0

Azure App Setup (Required)

Before using this package you need an Azure app registration:

1. Go to portal.azure.com → Azure Active Directory → App registrations → New registration
2. Set redirect URI to: http://localhost:3333/auth/callback
3. Under API Permissions, add Microsoft Graph delegated permissions:
   • Mail.Read, Mail.ReadWrite, Mail.Send
   • Calendars.Read, Calendars.ReadWrite
   • User.Read
   • offline_access
4. Under Certificates & Secrets → New client secret — copy the Value (not the Secret ID)
5. Copy your Application (client) ID from the Overview page

Quick Start

1. Set credentials

PowerShell (Windows):

$env:OUTLOOK_CLIENT_ID="your-client-id-here"
$env:OUTLOOK_CLIENT_SECRET="your-client-secret-value-here"

Bash/zsh (Linux/Mac):

export OUTLOOK_CLIENT_ID="your-client-id-here"
export OUTLOOK_CLIENT_SECRET="your-client-secret-value-here"

Or use a .env file (copy from .env.example):

cp .env.example .env
# Edit .env with your credentials

2. Start the auth server (required for first-time login)

npm run auth-server
# or
outlook-cli auth server --start

This starts an OAuth callback server on port 3333. Keep it running during authentication.

3. Authenticate once

outlook-cli auth login --open --start-server --wait

This opens your browser to the Microsoft login page. After you approve, tokens are saved to ~/.outlook-mcp-tokens.json and reused for all future runs.

4. Verify and explore

outlook-cli auth status        # confirm authenticated
outlook-cli tools list         # see all available tools
outlook-cli email list         # list recent inbox emails
outlook-cli calendar list      # list upcoming events

Environment Variables

Required

| Variable | Description | |---|---| | OUTLOOK_CLIENT_ID | Azure app Application (client) ID | | OUTLOOK_CLIENT_SECRET | Azure app client secret value (not the Secret ID) |

Optional

| Variable | Default | Description | |---|---|---| | OUTLOOK_REDIRECT_URI | http://localhost:3333/auth/callback | OAuth redirect URL | | OUTLOOK_SCOPES | offline_access Mail.Read Mail.ReadWrite Mail.Send User.Read Calendars.Read Calendars.ReadWrite | Microsoft Graph permission scopes | | OUTLOOK_TOKEN_STORE_PATH | ~/.outlook-mcp-tokens.json | Where tokens are saved on disk | | OUTLOOK_TOKEN_ENDPOINT | Microsoft consumer OAuth endpoint | Token exchange URL | | OUTLOOK_AUTH_SERVER_URL | http://localhost:3333 | Auth server base URL | | USE_TEST_MODE | false | Use mock data instead of real API calls |

Legacy aliases (backward-compatible): MS_CLIENT_ID, MS_CLIENT_SECRET, MS_REDIRECT_URI, MS_SCOPES, MS_TOKEN_STORE_PATH, MS_TOKEN_ENDPOINT, MS_AUTH_SERVER_URL

Command Groups

auth — Authentication

| Command | Description | Example | |---|---|---| | auth status | Show current authentication status | outlook-cli auth status | | auth login | Start authentication flow | outlook-cli auth login --open --start-server --wait | | auth url | Show the OAuth URL without opening browser | outlook-cli auth url | | auth server | Check/start local OAuth callback server | outlook-cli auth server --start | | auth logout | Clear stored tokens | outlook-cli auth logout |

Flags for auth login:

• --open — Automatically open the auth URL in your browser
• --start-server — Start the OAuth callback server automatically
• --wait — Wait for authentication to complete before returning
• --client-id — Provide Application (client) ID at runtime (optional)
• --client-secret — Provide client secret value at runtime (optional)
• --prompt-credentials — Prompt for missing credentials in interactive terminals

Examples:

# Full login with browser open and wait
outlook-cli auth login --open --start-server --wait

# Just get the URL to open manually
outlook-cli auth url

# Check if you're logged in
outlook-cli auth status

# Force re-authentication
outlook-cli auth login --open --force

# Runtime credentials (useful outside repo where .env is not loaded)
outlook-cli auth login --open --client-id <id> --client-secret <secret>

# Start or check auth callback server
outlook-cli auth server --start
outlook-cli auth server --status

email — Email Management

| Command | Description | Example | |---|---|---| | email list | List recent emails | outlook-cli email list --count 20 | | email search | Search emails by criteria | outlook-cli email search --from [email protected] | | email read | Read full email content | outlook-cli email read --id AAMkAGVm... | | email attachments | List attachments on one email | outlook-cli email attachments --id AAMkAGVm... | | email attachment | Get one attachment and optionally save it | outlook-cli email attachment --id AAMkAGVm... --attachment-id AA... --save-path ./downloads/ | | email send | Send a new email | outlook-cli email send --to [email protected] --subject "Hi" --body "Hello" | | email mark-read | Mark email as read or unread | outlook-cli email mark-read --id AAMkAGVm... |

email list — List Recent Emails

Lists emails from a folder, sorted newest first.

Parameters:

| Flag | Type | Default | Description | |---|---|---|---| | --folder | string | inbox | Folder to list from: inbox, sent, drafts, deleted, junk, archive, or any custom folder name | | --count | number | 10 | Number of emails to return (1–50) |

Examples:

# Default: 10 most recent inbox emails
outlook-cli email list

# Last 25 inbox emails
outlook-cli email list --count 25

# 10 most recent sent emails
outlook-cli email list --folder sent

# 15 emails from a custom folder
outlook-cli email list --folder "Project Alpha" --count 15

# Output as JSON for scripting
outlook-cli email list --count 5 --json

Output shows: Email ID, sender, subject, date, read/unread status, attachment indicator, body preview.

email search — Search Emails

Searches emails using text and/or filter criteria. Supports multiple criteria simultaneously.

Parameters:

| Flag | Type | Description | |---|---|---| | --query | string | Full-text search across subject, body, and sender | | --folder | string | Folder to search (default: inbox) | | --from | string | Filter by sender email or name | | --to | string | Filter by recipient email | | --subject | string | Filter by subject text | | --hasAttachments | boolean | Only show emails with attachments | | --unreadOnly | boolean | Only show unread emails | | --count | number | Max results (1–50, default: 10) |

Examples:

# Search by keyword
outlook-cli email search --query "quarterly report"

# Find unread emails from a specific sender
outlook-cli email search --from [email protected] --unreadOnly

# Find emails with attachments about invoices
outlook-cli email search --subject invoice --hasAttachments

# Search sent folder for emails to a client
outlook-cli email search --folder sent --to [email protected]

# Complex search
outlook-cli email search --from [email protected] --subject "budget" --unreadOnly --count 20

# JSON output
outlook-cli email search --query "meeting notes" --json

email read — Read Full Email

Reads the complete content of one email by its ID.

Parameters:

| Flag | Type | Required | Description | |---|---|---|---| | --id | string | yes | Email ID from email list or email search output |

Examples:

# Read a specific email
outlook-cli email read --id AAMkAGVmMDAwAT...

# Read and output as JSON
outlook-cli email read --id AAMkAGVmMDAwAT... --json

Output shows: From, To, CC, BCC, Subject, Date, Importance, Attachment status, full Body text (HTML auto-converted to plain text).

Tip: Get email IDs from email list or email search output first.

email attachments — List Email Attachments

Lists attachments for a specific email message.

Parameters:

| Flag | Type | Required | Default | Description | |---|---|---|---|---| | --id | string | yes | — | Message ID from email list or email search | | --count | number | no | 25 | Max attachments to list (1–50) |

Examples:

# List attachments for one message
outlook-cli email attachments --id AAMkAGVmMDAwAT...

# Limit to first 10 attachments
outlook-cli email attachments --id AAMkAGVmMDAwAT... --count 10

Output shows: Attachment ID, type (fileAttachment, itemAttachment, or referenceAttachment), content type, size, inline flag, and last modified date.

email attachment — Get/Download One Attachment

Gets metadata for one attachment and optionally saves it to disk.

Parameters:

| Flag | Type | Required | Default | Description | |---|---|---|---|---| | --id | string | yes | — | Message ID | | --attachmentId | string | yes | — | Attachment ID from email attachments | | --savePath | string | no | — | File path or directory path to save downloaded bytes | | --includeContent | boolean | no | false | Include text preview when attachment content is text-like | | --expandItem | boolean | no | false | Expand metadata for item attachments | | --overwrite | boolean | no | false | Overwrite existing file at destination path |

Examples:

# Get metadata only
outlook-cli email attachment --id AAMkAGVmMDAwAT... --attachment-id AAMkAGVmMDAwAT...=

# Save attachment to downloads directory
outlook-cli email attachment \
  --id AAMkAGVmMDAwAT... \
  --attachment-id AAMkAGVmMDAwAT...= \
  --save-path ./downloads/

# Save and include text preview when possible
outlook-cli email attachment \
  --id AAMkAGVmMDAwAT... \
  --attachment-id AAMkAGVmMDAwAT...= \
  --save-path ./downloads/ \
  --include-content

Notes:

• referenceAttachment is a cloud link and cannot be downloaded as raw bytes from this endpoint.
• Item attachments use MIME raw content when downloaded.

email send — Send Email

Composes and sends an email from the user's account.

Parameters:

| Flag | Type | Required | Default | Description | |---|---|---|---|---| | --to | string | yes | — | Recipient(s), comma-separated for multiple | | --subject | string | yes | — | Email subject | | --body | string | yes | — | Email body (plain text or HTML) | | --cc | string | no | — | CC recipient(s), comma-separated | | --bcc | string | no | — | BCC recipient(s), comma-separated | | --importance | string | no | normal | Priority: normal, high, or low | | --saveToSentItems | boolean | no | true | Save copy to Sent folder |

Examples:

# Simple email
outlook-cli email send \
  --to [email protected] \
  --subject "Meeting notes" \
  --body "Here are today's action items..."

# Email to multiple recipients with CC and high priority
outlook-cli email send \
  --to "[email protected],[email protected]" \
  --cc [email protected] \
  --subject "URGENT: System outage" \
  --body "We are investigating..." \
  --importance high

# Email without saving to sent folder
outlook-cli email send \
  --to [email protected] \
  --subject "Test" \
  --body "Hello" \
  --saveToSentItems false

Notes:

• HTML body is detected automatically when the body contains <html.
• Sending attachments is not supported yet — body text only.

email mark-read — Mark Email Read/Unread

Changes the read status of an email.

Parameters:

| Flag | Type | Required | Default | Description | |---|---|---|---|---| | --id | string | yes | — | Email ID | | --isRead | boolean | no | true | true = mark read, false = mark unread |

Examples:

# Mark as read (default)
outlook-cli email mark-read --id AAMkAGVmMDAwAT...

# Mark as unread
outlook-cli email mark-read --id AAMkAGVmMDAwAT... --isRead false

calendar — Calendar Management

| Command | Description | |---|---| | calendar list | List upcoming events | | calendar create | Create a new event | | calendar decline | Decline an event invitation | | calendar cancel | Cancel an event you organized | | calendar delete | Delete an event |

calendar list — List Upcoming Events

Lists upcoming calendar events starting from now, ordered by start time.

Parameters:

| Flag | Type | Default | Description | |---|---|---|---| | --count | number | 10 | Number of events to return (1–50) |

Examples:

# Next 10 events (default)
outlook-cli calendar list

# Next 30 events
outlook-cli calendar list --count 30

# JSON output
outlook-cli calendar list --count 5 --json

Output shows: Event ID, subject, location, start time, end time, organizer, attendees list.

Tip: Copy the Event ID from the output to use with decline, cancel, or delete commands.

calendar create — Create Calendar Event

Creates a new event on the calendar. Optionally invites attendees.

Parameters:

| Flag | Type | Required | Description | |---|---|---|---| | --subject | string | yes | Event title | | --start | string | yes | Start datetime: YYYY-MM-DDTHH:MM:SS | | --end | string | yes | End datetime: YYYY-MM-DDTHH:MM:SS | | --attendees | string | no | Comma-separated attendee email addresses | | --body | string | no | Event description/agenda |

Examples:

# Simple personal event
outlook-cli calendar create \
  --subject "Focus time" \
  --start "2026-04-10T09:00:00" \
  --end "2026-04-10T11:00:00"

# Team meeting with attendees and agenda
outlook-cli calendar create \
  --subject "Q2 Planning" \
  --start "2026-04-15T14:00:00" \
  --end "2026-04-15T15:30:00" \
  --attendees "[email protected],[email protected]" \
  --body "Agenda: review Q1, plan Q2 roadmap, assign owners"

# All-day event (use midnight to midnight)
outlook-cli calendar create \
  --subject "Company holiday" \
  --start "2026-04-25T00:00:00" \
  --end "2026-04-25T23:59:00"

Notes:

• Datetime must be in YYYY-MM-DDTHH:MM:SS format without timezone offset.
• The server uses Central European Standard Time by default.

calendar decline — Decline Event Invitation

Declines a received event invitation, optionally with a message to the organizer.

Parameters:

| Flag | Type | Required | Description | |---|---|---|---| | --eventId | string | yes | Event ID from calendar list | | --comment | string | no | Message to send to the organizer |

Examples:

# Decline without a message
outlook-cli calendar decline --eventId AAMkAGVmMDAwAT...

# Decline with a reason
outlook-cli calendar decline \
  --eventId AAMkAGVmMDAwAT... \
  --comment "Sorry, I have a conflict. Can we reschedule to next week?"

calendar cancel — Cancel Your Event

Cancels an event you organized and notifies all attendees.

Parameters:

| Flag | Type | Required | Description | |---|---|---|---| | --eventId | string | yes | Event ID from calendar list | | --comment | string | no | Cancellation reason sent to attendees |

Examples:

# Cancel without message
outlook-cli calendar cancel --eventId AAMkAGVmMDAwAT...

# Cancel with explanation
outlook-cli calendar cancel \
  --eventId AAMkAGVmMDAwAT... \
  --comment "This meeting is no longer needed. Details will follow by email."

Note: Use cancel (not delete) when you want attendees to receive a cancellation notification.

calendar delete — Delete Event

Permanently removes an event from the calendar without notifying attendees.

Parameters:

| Flag | Type | Required | Description | |---|---|---|---| | --eventId | string | yes | Event ID from calendar list |

Examples:

outlook-cli calendar delete --eventId AAMkAGVmMDAwAT...

Tip: Use cancel instead of delete for meetings with attendees so they receive proper notification.

folder — Mail Folder Management

| Command | Description | |---|---| | folder list | List all mail folders | | folder create | Create a new folder | | folder move | Move emails to another folder |

folder list — List Mail Folders

Lists all mail folders in the account. Optionally shows item counts and subfolder hierarchy.

Parameters:

| Flag | Type | Default | Description | |---|---|---|---| | --includeItemCounts | boolean | false | Show total and unread message counts | | --includeChildren | boolean | false | Show nested subfolders |

Examples:

# Simple folder list
outlook-cli folder list

# With message counts
outlook-cli folder list --includeItemCounts

# Full hierarchy with counts
outlook-cli folder list --includeItemCounts --includeChildren

# JSON output for scripting
outlook-cli folder list --includeItemCounts --json

Tip: Use this to discover custom folder names before using them in email list, email search, folder move, or rule create.

folder create — Create Mail Folder

Creates a new mail folder at the root level or inside an existing folder.

Parameters:

| Flag | Type | Required | Default | Description | |---|---|---|---|---| | --name | string | yes | — | Name for the new folder | | --parentFolder | string | no | root | Name of existing parent folder |

Examples:

# Create top-level folder
outlook-cli folder create --name "Project Alpha"

# Create subfolder inside an existing folder
outlook-cli folder create --name "2026 Invoices" --parentFolder "Finance"

# Create a subfolder under inbox
outlook-cli folder create --name "Action Required" --parentFolder inbox

folder move — Move Emails

Moves one or more emails from one folder to another.

Parameters:

| Flag | Type | Required | Default | Description | |---|---|---|---|---| | --emailIds | string | yes | — | Comma-separated email ID(s) | | --targetFolder | string | yes | — | Destination folder name | | --sourceFolder | string | no | inbox | Source folder (for context) |

Examples:

# Move one email to archive
outlook-cli folder move \
  --emailIds AAMkAGVmMDAwAT... \
  --targetFolder archive

# Move multiple emails to a custom folder
outlook-cli folder move \
  --emailIds "AAMkAGVm...,BBMkAHXn...,CCMkAIYo..." \
  --targetFolder "Project Alpha"

# Move from a non-inbox folder
outlook-cli folder move \
  --emailIds AAMkAGVmMDAwAT... \
  --sourceFolder "Junk" \
  --targetFolder inbox

Output: Reports success count, failure count, and error details for any failed moves (up to 3 error messages shown).

rule — Inbox Rules

| Command | Description | |---|---| | rule list | List all inbox rules | | rule create | Create a new inbox rule | | rule sequence | Change a rule's execution order |

rule list — List Inbox Rules

Lists all inbox rules sorted by sequence (execution order — lower runs first).

Parameters:

| Flag | Type | Default | Description | |---|---|---|---| | --includeDetails | boolean | false | Show full conditions and actions |

Examples:

# Just rule names and enabled status
outlook-cli rule list

# Full detail — conditions and actions for each rule
outlook-cli rule list --includeDetails

# JSON for scripting
outlook-cli rule list --includeDetails --json

Output (with details) shows:

• Conditions: fromAddresses, subjectContains, bodyContains, hasAttachment, importance
• Actions: moveToFolder, copyToFolder, markAsRead, markImportance, forwardTo, delete

rule create — Create Inbox Rule

Creates an inbox rule that automatically processes incoming emails. Needs a name, at least one condition, and at least one action.

Parameters:

| Flag | Type | Required | Description | |---|---|---|---| | --name | string | yes | Rule name | | --fromAddresses | string | condition | Comma-separated sender emails to match | | --containsSubject | string | condition | Text that must appear in subject | | --hasAttachments | boolean | condition | Match only emails with attachments | | --moveToFolder | string | action | Folder name to move matching emails to | | --markAsRead | boolean | action | Auto-mark matching emails as read | | --isEnabled | boolean | — | Whether rule is active (default: true) | | --sequence | number | — | Execution order (lower = first); auto-assigned if omitted |

At least one condition (--fromAddresses, --containsSubject, --hasAttachments) and at least one action (--moveToFolder, --markAsRead) are required.

Examples:

# Auto-move emails from boss to Important folder
outlook-cli rule create \
  --name "Boss emails" \
  --fromAddresses [email protected] \
  --moveToFolder Important

# Auto-file newsletters and mark as read
outlook-cli rule create \
  --name "Newsletter handler" \
  --fromAddresses "[email protected],[email protected]" \
  --moveToFolder Newsletters \
  --markAsRead \
  --sequence 10

# Rule based on subject text
outlook-cli rule create \
  --name "Invoice sorter" \
  --containsSubject invoice \
  --hasAttachments \
  --moveToFolder Finance

# Disabled rule (create but don't activate yet)
outlook-cli rule create \
  --name "Temp filter" \
  --fromAddresses [email protected] \
  --markAsRead \
  --isEnabled false

Notes:

• The moveToFolder target must already exist. Create it first with folder create.
• If --sequence is not provided, the rule is placed after all existing rules.

rule sequence — Change Rule Execution Order

Changes the sequence (execution order) of an existing rule. Lower sequence numbers run first.

Parameters:

| Flag | Type | Required | Description | |---|---|---|---| | --ruleName | string | yes | Exact name of the rule to reorder | | --sequence | number | yes | New sequence number |

Examples:

# Make boss email rule run first
outlook-cli rule sequence --ruleName "Boss emails" --sequence 1

# Push newsletter rule later in the order
outlook-cli rule sequence --ruleName "Newsletter handler" --sequence 500

tools — Tool Inspection

| Command | Description | Example | |---|---|---| | tools list | List all available MCP tools | outlook-cli tools list | | tools schema | Show schema for a specific tool | outlook-cli tools schema list-emails |

Examples:

# See all tools
outlook-cli tools list

# Inspect a tool's parameters
outlook-cli tools schema send-email
outlook-cli tools schema create-event

call — Generic Tool Invocation

Invoke any MCP tool directly by name with JSON arguments.

outlook-cli call <tool-name> --args-json '<json>'

Examples:

# List emails via generic call
outlook-cli call list-emails --args-json '{"folder":"inbox","count":5}'

# Send email via generic call
outlook-cli call send-email --args-json '{"to":"[email protected]","subject":"Hi","body":"Hello"}'

# With JSON output
outlook-cli call list-events --args-json '{"count":10}' --json

agents — AI Agent Guide

Shows best-practice command flow for AI agents (Claude, Codex, VS Code, automation scripts).

outlook-cli agents guide

Agent workflow (recommended):

outlook-cli auth status --json
outlook-cli tools list --json
outlook-cli tools schema send-email --json
outlook-cli call list-emails --args-json '{"folder":"inbox","count":5}' --ai

doctor — Diagnostics

Runs a series of diagnostic checks and reports what's working and what needs fixing.

outlook-cli doctor

Checks: Node.js version, environment variables, token file presence, token validity, server connectivity.

update — Update the CLI

# Check for updates
outlook-cli update

# Run the update automatically
outlook-cli update --run

Or update via npm directly:

npm i -g outlook-cli@latest

Output Flags (All Commands)

| Flag | Description | |---|---| | --json | Output raw JSON instead of human-readable text | | --ai | Agent-safe alias for JSON mode (suppresses rich UI output) | | --theme k9s|ocean|mono | Select color theme for text output | | --plain | No colors or formatting | | --no-color | Disable color only | | --no-animate | Disable spinner animations |

In JSON mode, responses include both:

• result (original MCP tool payload)
• structured (normalized machine-friendly fields like summary, items, and parsed metadata)

Examples:

outlook-cli auth status --json
outlook-cli tools list --ai
outlook-cli email list --count 10 --json
outlook-cli --theme ocean --help
outlook-cli calendar list --plain

Complete MCP Tool Catalog

All 21 tools are available through the shared MCP tool registry — used by Claude and other AI assistants, and also callable via outlook-cli call <tool-name>.

Authentication Tools

| Tool | What it does | Required | Optional | |---|---|---|---| | about | Returns server name, version, description | none | none | | authenticate | Starts OAuth flow, returns auth URL | none | force (boolean) | | check-auth-status | Returns current auth status | none | none |

Calendar Tools

| Tool | What it does | Required | Optional | |---|---|---|---| | list-events | List upcoming calendar events | none | count (1–50) | | create-event | Create a new event | subject, start, end | attendees (array), body | | decline-event | Decline an event invitation | eventId | comment | | cancel-event | Cancel an event and notify attendees | eventId | comment | | delete-event | Delete an event silently | eventId | none |

Email Tools

| Tool | What it does | Required | Optional | |---|---|---|---| | list-emails | List recent emails from a folder | none | folder, count | | search-emails | Search with text and filter criteria | none | query, folder, from, to, subject, hasAttachments, unreadOnly, count | | read-email | Read full content of one email | id | none | | list-attachments | List attachments on a message | messageId | count | | get-attachment | Get one attachment metadata and optionally download it | messageId, attachmentId | savePath, includeContent, expandItem, overwrite | | send-email | Send a new email | to, subject, body | cc, bcc, importance, saveToSentItems | | mark-as-read | Mark email read or unread | id | isRead (boolean, default true) |

Folder Tools

| Tool | What it does | Required | Optional | |---|---|---|---| | list-folders | List all mail folders | none | includeItemCounts, includeChildren | | create-folder | Create a new folder | name | parentFolder | | move-emails | Move emails to another folder | emailIds (comma-separated), targetFolder | sourceFolder |

Rules Tools

| Tool | What it does | Required | Optional | |---|---|---|---| | list-rules | List inbox rules by execution order | none | includeDetails | | create-rule | Create inbox rule (1 condition + 1 action minimum) | name + condition + action | isEnabled, sequence | | edit-rule-sequence | Change rule execution order | ruleName, sequence | none |

MCP Server Mode (for Claude and AI Assistants)

Run as a standard MCP stdio server for use with Claude Desktop or other MCP clients:

npm run mcp-server
# or
node index.js

Claude Desktop Configuration

Add to your Claude Desktop config file (claude-config-sample.json is included as a reference):

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/path/to/outlook-mcp/index.js"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "outlook": {
      "command": "outlook-cli",
      "args": ["mcp-server"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

AI Assistant Skill

A complete skill reference for AI assistants (Claude and others) is in skill/outlook-mcp.md. This document covers every tool, every parameter, common workflows, and examples — useful for RAG systems or as a system prompt addition.

Token Behavior

• Tokens are stored at ~/.outlook-mcp-tokens.json (Windows: %USERPROFILE%\.outlook-mcp-tokens.json)
• Tokens survive package updates and reinstalls — no need to re-authenticate after upgrading
• Access tokens auto-refresh when expired (using the refresh token)
• Force re-authentication anytime with outlook-cli auth login --force or authenticate { force: true }

Test Mode

USE_TEST_MODE=true outlook-cli email list

With USE_TEST_MODE=true, all API calls use mock data — no real Microsoft account needed. Useful for development and CI testing.

Troubleshooting

| Problem | Solution | |---|---| | AADSTS7000215 error | You're using the Secret ID instead of the secret Value in Azure | | Auth server won't start | Run npx kill-port 3333 then try again | | "Not authenticated" after token exists | Token expired with no refresh token — run auth login again | | create-rule fails on folder | Folder doesn't exist — run folder create first | | move-emails partial failure | Some email IDs were invalid — verify IDs with email list | | Missing dependencies | Run npm install |

AI Assistant Skill

The skills/outlook-automation/ folder contains a structured skill for Claude Code, OpenAI Codex, and VS Code.

Install the skill

# Claude Code — personal
uv run python tools/install_skill.py --personal

# Claude Code — project/team
uv run python tools/install_skill.py --project

# OpenAI Codex
uv run python tools/install_skill.py --codex

# Verify
uv run python tools/install_skill.py --verify --personal

Note: OpenAI Codex skills require the experimental feature flag. Add to ~/.codex/config.toml:

[features]
skills = true

Skill structure

| File | Contents | |---|---| | skills/outlook-automation/SKILL.md | Main skill entry — overview, behavioral rules, quick examples, install instructions | | skills/outlook-automation/reference/cli.md | Complete CLI command reference — every command, flag, and example | | skills/outlook-automation/reference/json-schema.md | JSON schemas for all 21 MCP tools | | skills/outlook-automation/reference/security.md | OAuth flow, token lifecycle, permission scopes, AI safety rules | | skills/outlook-automation/reference/troubleshooting.md | Common errors, diagnostic checklist, step-by-step fixes |

Documentation

| File | Contents | |---|---| | docs/REFERENCE.md | Full parameter-by-parameter API reference | | CLI.md | CLI quick reference card | | QUICKSTART.md | Setup walkthrough for new users | | docs/PROJECT-STRUCTURE.md | Codebase architecture and module overview | | docs/PUBLISHING.md | Publishing checklist for maintainers | | claude-config-sample.json | Sample Claude Desktop MCP config |

Scripts Reference

| Script | Command | Description | |---|---|---| | npm start | node cli.js | Run the CLI | | npm run mcp-server | node index.js | Run as MCP stdio server | | npm run cli | node cli.js | CLI alias | | npm run auth-server | node outlook-auth-server.js | Start OAuth callback server on port 3333 | | npm run doctor | node cli.js doctor | Run diagnostics | | npm run inspect | MCP Inspector | Test MCP server interactively | | npm test | Jest | Run unit tests |