# Outlook Assistant Server

> Give Claude full access to your Outlook email, calendar, and contacts through the Microsoft Graph API.

Built by [Little Bear Apps](https://littlebearapps.com).

## Key Information

- **Package**: `@littlebearapps/outlook-assistant` on npm
- **Install**: `npm install -g @littlebearapps/outlook-assistant` or `npx @littlebearapps/outlook-assistant`
- **License**: MIT
- **Node.js**: >= 18.0.0
- **Authentication**: OAuth 2.0 with Microsoft Graph API (requires Azure app registration)
- **Tools**: 22 tools across 9 modules (reduced from 55 for optimal AI performance)

## Why Outlook Assistant?

- Read, search, send, and export emails directly from Claude instead of switching apps
- 8 email tools covering search, conversations, attachments, bulk export, pre-send mail tips, and draft management
- Manage calendar events, contacts, rules, categories, and mailbox settings in one place
- Export to multiple formats: MIME/EML, MBOX, Markdown, JSON, HTML

## Key Differentiators

- **Progressive search**: Automatically falls back through 4 search strategies when Microsoft's `$search` API is unavailable (personal accounts) — most Graph API wrappers fail silently. Explicit "no results" messaging instead of unfiltered fallback.
- **Remote-friendly auth**: Device code flow (default) — no auth server, no port forwarding, no SSH tunnels. State persists across MCP server restarts. Works from Untether, mosh, SSH, and headless environments.
- **Email forensics**: Built-in header analysis for DKIM, SPF, DMARC authentication, delivery chains, and spam scores — useful for phishing investigation and compliance
- **Delta sync**: Incremental inbox monitoring — returns only new, modified, and deleted emails since last check, with tokens for continuous polling
- **Batch operations**: Flag, move, export, or categorise multiple emails in a single tool call; search-driven export for batch archiving without collecting IDs
- **Pre-send intelligence**: Check recipients for out-of-office, mailbox full, delivery restrictions, and moderation before sending — no other Outlook MCP server offers this
- **Compound automation**: Rules + categories + folders + Focused Inbox for complete inbox management in one conversation

## Safety & Token Efficiency

- **MCP safety annotations** on all 22 tools — AI clients auto-approve reads and prompt for destructive operations
- **Send-email protections**: pre-send mail tips, dry-run preview, session rate limiting, recipient allowlist
- **Rule protections**: dry-run preview on create/update, rate limiting, recipient allowlist on forward/redirect, no permanent-delete action
- **Token-optimised**: 22 tools instead of 55 saves ~11,000 tokens per turn (~64% reduction), improving AI accuracy and context efficiency
- These safeguards reduce risk but are not foolproof — always review actions before approving

## Quick Start

```json
{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}
```

Requires an Azure app registration with Microsoft Graph delegated permissions. See README for full setup.

## Tool Categories

- **Authentication (1 tool)**: `auth` — OAuth flow, status, about
- **Email (8 tools)**: `search-emails`, `read-email`, `send-email`, `draft`, `update-email`, `attachments`, `export`, `get-mail-tips`
- **Calendar (3 tools)**: `list-events`, `create-event`, `manage-event`
- **Contacts (2 tools)**: `manage-contact`, `search-people`
- **Folders (1 tool)**: `folders` — list, create, move, stats
- **Rules (1 tool)**: `manage-rules` — list, create, update, reorder, delete
- **Categories (3 tools)**: `manage-category`, `apply-category`, `manage-focused-inbox`
- **Settings (1 tool)**: `mailbox-settings` — get, set auto-replies, set working hours
- **Advanced (2 tools)**: `access-shared-mailbox`, `find-meeting-rooms`

## Documentation

- [README](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/README.md): Full documentation including setup, Azure configuration, and usage
- [Tools Reference](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/quickrefs/tools-reference.md): All 22 tools with parameters and safety annotations
- [Connect Outlook to Claude](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/how-to/getting-started/connect-outlook-to-claude.md): Step-by-step setup guide for Claude Desktop / Claude Code
- [Verify Your Connection](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/how-to/getting-started/verify-your-connection.md): Test and troubleshoot the connection after installation
- [Azure Setup](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/guides/azure-setup.md): Azure app registration and API permissions walkthrough
- [FAQ](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/faq/faq.md): Frequently asked questions — install, accounts, permissions, tokens, send safety, updates, uninstall (also at <https://littlebearapps.com/help/outlook-assistant/faq/>)
- [CLAUDE.md](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CLAUDE.md): Quick reference for development
- [CONTRIBUTING](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CONTRIBUTING.md): Contribution guidelines
- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.8.0 — `manage-event` gains an `update` action covering 12 fields with `dryRun` (#173, closes #124); new `OUTLOOK_AUTH_AUDIENCE` env var fixes AADSTS9002331 for personal-only Azure apps (#174); new `OUTLOOK_DEFAULT_TIMEZONE` env var overrides the hardcoded Australia/Melbourne default (#175))
- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.8.x polish, v3.9.0 new Graph APIs)
- [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls