Outlook Assistant MCP server for Outlook email, calendar, and contacts — let your AI assistant manage your inbox directly from the conversation. Outlook Assistant connects AI assistants to your Microsoft Outlook account through the Model Context Protocol. Ask your AI assistant to search your inbox, send emails, schedule meetings, manage contacts, and configure mailbox settings — without leaving th
Add this skill
npx mdskills install littlebearapps/outlook-assistantComprehensive Outlook MCP server with 22 tools, safety controls, and excellent documentation
1<p align="center">2 <img src="https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/assets/outlook-assistant-logo-full.png" height="200" alt="Outlook Assistant" />3</p>45<h1 align="center">Outlook Assistant</h1>67<p align="center">8 <strong>MCP server for Outlook email, calendar, and contacts — let your AI assistant manage your inbox directly from the conversation.</strong>9</p>1011<p align="center">12 <a href="https://www.npmjs.com/package/@littlebearapps/outlook-assistant"><img src="https://img.shields.io/npm/v/@littlebearapps/outlook-assistant" alt="npm version" /></a>13 <a href="https://www.npmjs.com/package/@littlebearapps/outlook-assistant"><img src="https://img.shields.io/npm/dm/@littlebearapps/outlook-assistant" alt="npm downloads" /></a>14 <a href="https://github.com/littlebearapps/outlook-assistant/actions/workflows/ci.yml"><img src="https://github.com/littlebearapps/outlook-assistant/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>15 <a href="https://github.com/littlebearapps/outlook-assistant/actions/workflows/codeql.yml"><img src="https://github.com/littlebearapps/outlook-assistant/actions/workflows/codeql.yml/badge.svg" alt="CodeQL" /></a>16 <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>17</p>1819Outlook Assistant connects AI assistants to your Microsoft Outlook account through the [Model Context Protocol](https://modelcontextprotocol.io/). Ask your AI assistant to search your inbox, send emails, schedule meetings, manage contacts, and configure mailbox settings — without leaving the conversation. Works with Claude, Cursor, Windsurf, and any MCP-compatible client.2021**Works with personal Outlook.com and work/school Microsoft 365 accounts.**2223<div align="center">24 <br />25 <a href="docs/demo/outlook-assistant-demo.mp4">26 <img src="docs/demo/outlook-assistant-demo.gif" alt="Outlook Assistant Demo — searching emails, reading, and drafting a reply" width="720" style="border-radius: 12px; box-shadow: 0 8px 32px rgba(0,0,0,0.12);" />27 </a>28 <br />29 <sub>Search inbox → read & summarise → draft a reply — all from the conversation</sub>30 <br /><br />31</div>3233### What you can do3435- 📨 **Search and read emails** — find messages by sender, subject, date, or keywords; read full threads with conversation grouping; batch flag, move, export, or categorise multiple emails at once36- 🛡️ **Send emails with safety controls** — dry-run preview, pre-send mail tips (out-of-office, mailbox full, delivery restrictions), session rate limiting, and recipient allowlist to prevent mistakes37- ✏️ **Draft emails for review** — create, update, and send drafts; reply and forward as drafts; preview before saving with dry-run mode38- 📅 **Manage your calendar** — view upcoming events, schedule meetings with attendees, decline or cancel invitations39- 📦 **Export emails** — save to Markdown, EML, MBOX, JSON, or HTML for archiving, analysis, or migration; export search results or entire threads in one call40- 🔍 **Investigate email headers** — check DKIM, SPF, and DMARC authentication; trace delivery chains; analyse spam scores — useful for phishing investigation and compliance41- 🗂️ **Organise your inbox** — create folders, set up inbox rules, colour-code with categories, manage Focused Inbox — all work together for complete inbox automation42- 🔄 **Track inbox changes** — delta sync detects new, modified, and deleted emails since your last check, with tokens for incremental polling43- 👥 **Manage contacts** — search your contact book and organisational directory, create and update contact records44- ⚙️ **Configure settings** — set out-of-office auto-replies, working hours, and time zone45- 📬 **Access shared mailboxes** — read team inboxes and service accounts (Microsoft 365)46- 🏢 **Find meeting rooms** — search by building, floor, capacity, AV equipment, and wheelchair accessibility (Microsoft 365)4748### Why Outlook Assistant?4950| Without Outlook Assistant | With Outlook Assistant |51|---------------------|------------------|52| Switch between your AI tool and Outlook to manage email | Read, search, send, and export emails directly from your AI assistant |53| Manually search and export email threads | Full email tools including search, threading, and bulk export |54| Context-switch for calendar and contacts | Manage calendar events, contacts, and settings in one place |55| Copy-paste email content into conversations | Your AI assistant reads your emails natively with full context |56| No programmatic access to mailbox rules or categories | Create inbox rules, manage categories, configure auto-replies |57| Manually check each email for phishing red flags | Forensic header analysis — DKIM, SPF, DMARC, spam scores, and delivery chain in one call |58| Poll your inbox to check for new mail | Delta sync returns only changes since your last check, with tokens for continuous polling |5960## Features6162| Module | Tools | What You Can Do |63|--------|------:|-----------------|64| **Email** | 8 | `search-emails` (list/search/delta/conversations), `read-email` (content + forensic headers), `send-email` (with dry-run + mail tips), `draft` (create/update/send/delete/reply/forward), `update-email` (read status, flags), `attachments`, `export`, `get-mail-tips` |65| **Calendar** | 3 | `list-events`, `create-event`, `manage-event` (decline/cancel/delete) |66| **Contacts** | 2 | `manage-contact` (list/search/get/create/update/delete), `search-people` |67| **Categories** | 3 | `manage-category` (CRUD), `apply-category`, `manage-focused-inbox` |68| **Settings** | 1 | `mailbox-settings` (get/set auto-replies/set working hours) |69| **Folder** | 1 | `folders` (list/create/move/stats/delete) |70| **Rules** | 1 | `manage-rules` (list/create/update/reorder/delete) |71| **Advanced** | 2 | `access-shared-mailbox`, `find-meeting-rooms` |72| **Auth** | 1 | `auth` (status/authenticate/about) |7374**22 tools total** — consolidated from 55 for optimal AI performance. See the [Tools Reference](docs/quickrefs/tools-reference.md) for complete parameter details.7576### Export Formats7778| Format | Extension | When to Use It |79|--------|-----------|----------------|80| `mime` / `eml` | `.eml` | Legal holds, forensic preservation, importing into other mail clients |81| `mbox` | `.mbox` | Archiving entire conversation threads, migrating between systems |82| `markdown` | `.md` | Pasting into documents, feeding into AI workflows |83| `json` | `.json` | Data analysis, pipeline processing, compliance reporting |84| `html` | `.html` | Visual archival with formatting intact |85| `csv` | `.csv` | Spreadsheet import, bulk metadata analysis, compliance audits |8687Export individual emails, search results, or entire conversation threads — use `target=messages` with a search query to batch-export without manually collecting IDs.8889## Account Compatibility9091Outlook Assistant works with both personal and work/school Microsoft accounts, but some features behave differently:9293| Feature | Personal (Outlook.com) | Work/School (Microsoft 365) |94|---------|----------------------|---------------------------|95| Email read, send, search | Full support | Full support |96| Calendar events | Full support | Full support |97| Contacts CRUD | Full support | Full support |98| Inbox rules | Full support | Full support |99| Folders | Full support | Full support |100| Free-text `query` search | Limited — use `subject`, `from`, `to` filters instead | Full KQL support |101| Categories | Full support | Full support |102| Mailbox settings | Full support | Full support |103| Focused Inbox | Not available | Full support |104| Shared mailboxes | Not available | Requires `Mail.Read.Shared` |105| Meeting room search | Not available | Requires `Place.Read.All` + admin consent |106107> **Note**: On personal accounts, Microsoft's `$search` API has limited support for free-text queries. Outlook Assistant handles this automatically with progressive search — if your query returns no results, it falls back through OData filters, boolean filters, and recent message listing to find your emails. For the most direct results on personal accounts, use the structured filter parameters (`from`, `subject`, `to`, `receivedAfter`).108109### What Makes This Different110111- **Progressive search** — on accounts where Microsoft's `$search` API is limited, Outlook Assistant automatically falls back through up to 4 search strategies to find your emails. Most Graph API wrappers fail silently; this one adapts.112- **Email forensics** — full header analysis (DKIM, SPF, DMARC, delivery chain, spam scores) built in as a first-class feature — useful for phishing investigation, compliance, and security review.113- **Delta sync** — incremental inbox monitoring returns only what changed since your last check, with tokens for continuous polling. Designed for agent workflows that need to watch a mailbox.114- **Batch operations** — flag, move, export, or categorise multiple emails in a single call. Search-driven export lets you batch-export results without collecting IDs manually.115- **Pre-send intelligence** — check recipients for out-of-office, full mailbox, delivery restrictions, and moderation status before sending — no other Outlook MCP server offers this.116- **Compound automation** — rules, categories, folders, and Focused Inbox work together. Set up complete inbox management through your AI assistant in one conversation.117118## Safety & Token Efficiency119120Outlook Assistant is designed with safety-first principles for AI-driven email access:121122**Destructive action safeguards** — Every tool carries [MCP annotations](https://modelcontextprotocol.io/docs/concepts/tools#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so AI clients can auto-approve safe reads and prompt for confirmation on destructive operations like sending email or deleting events.123124**Send-email protections** — The `send-email` tool includes:125- **Pre-send mail tips** (`checkRecipients: true`) — check recipients for out-of-office, mailbox full, delivery restrictions before sending126- **Dry-run mode** (`dryRun: true`) — preview composed emails without sending127- **Session rate limiting** — configurable via `OUTLOOK_MAX_EMAILS_PER_SESSION` (default: unlimited)128- **Recipient allowlist** — restrict sending to approved addresses/domains via `OUTLOOK_ALLOWED_RECIPIENTS`129130**Draft protections** — The `draft` tool shares `send-email` safety controls: dry-run preview, recipient allowlist, mail-tips validation, and rate limiting. The `send` action shares the `send-email` rate limit counter, preventing circumvention via the draft-then-send pathway.131132**Token-optimised architecture** — Tools are consolidated using the STRAP (Single Tool, Resource, Action Pattern) approach. 22 tools instead of 55 reduces per-turn overhead by ~11,000 tokens (~64%), keeping more of the AI's context window available for your actual conversation. Fewer tools also means the AI selects the right tool more accurately — research shows tool selection degrades beyond ~40 tools.133134> **Important**: These safeguards are defence-in-depth measures that reduce risk, but they are not a guarantee against unintended actions. AI-driven access to your email is inherently sensitive — always review tool calls before approving, particularly for sends and deletes. No automated guardrail is foolproof, and you remain responsible for actions taken through your mailbox.135136## Quick Start137138### 1. Install139140```bash141npm install -g @littlebearapps/outlook-assistant142```143144Or run directly without installing:145146```bash147npx @littlebearapps/outlook-assistant148```149150### 2. Register an Azure App151152You need a Microsoft Azure app registration to authenticate. See the **[Azure Setup Guide](docs/guides/azure-setup.md)** for a detailed walkthrough (including first-time Azure account creation), or if you've done this before:1531541. Create a new app registration at [portal.azure.com](https://portal.azure.com/)1552. Add Microsoft Graph delegated permissions (Mail, Calendar, Contacts)1563. Create a client secret and copy the **Value** (not the Secret ID)1574. Under Authentication > **Add a platform** > **Mobile and desktop applications** — check `nativeclient` URI1585. Enable **"Allow public client flows"** in Authentication > Advanced settings1596. _(Optional)_ Set redirect URI to `http://localhost:3333/auth/callback` — only needed for browser auth flow160161### 3. Configure Your MCP Client162163Add to your MCP client config:164165<details>166<summary><strong>Claude Desktop</strong> (<code>claude_desktop_config.json</code>)</summary>167168```json169{170 "mcpServers": {171 "outlook": {172 "command": "npx",173 "args": ["@littlebearapps/outlook-assistant"],174 "env": {175 "OUTLOOK_CLIENT_ID": "your-application-client-id",176 "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"177 }178 }179 }180}181```182</details>183184<details>185<summary><strong>Claude Code</strong> (CLI)</summary>186187```bash188claude mcp add outlook -- npx @littlebearapps/outlook-assistant189```190191Then set environment variables in your `.env` or shell.192</details>193194<details>195<summary><strong>Cursor</strong> (<code>.cursor/mcp.json</code>)</summary>196197[](cursor://anysphere.cursor-deeplink/mcp/install?name=Outlook%20Assistant&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsaXR0bGViZWFyYXBwcy9vdXRsb29rLWFzc2lzdGFudCJdLCJlbnYiOnsiT1VUTE9PS19DTElFTlRfSUQiOiIiLCJPVVRMT09LX0NMSUVOVF9TRUNSRVQiOiIifX0=)198199Or add manually to `.cursor/mcp.json`:200201```json202{203 "mcpServers": {204 "outlook": {205 "command": "npx",206 "args": ["@littlebearapps/outlook-assistant"],207 "env": {208 "OUTLOOK_CLIENT_ID": "your-application-client-id",209 "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"210 }211 }212 }213}214```215</details>216217<details>218<summary><strong>Windsurf</strong> (<code>~/.codeium/windsurf/mcp_config.json</code>)</summary>219220```json221{222 "mcpServers": {223 "outlook": {224 "command": "npx",225 "args": ["@littlebearapps/outlook-assistant"],226 "env": {227 "OUTLOOK_CLIENT_ID": "your-application-client-id",228 "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"229 }230 }231 }232}233```234</details>235236### 4. Authenticate2372381. Start the auth server: `outlook-assistant-auth` (or `npx @littlebearapps/outlook-assistant-auth`)2392. In your AI assistant, use the `auth` tool with `action=authenticate` to get an OAuth URL2403. Open the URL, sign in with your Microsoft account, and grant permissions2414. Tokens are saved locally and refresh automatically242243> **Note**: The auth server needs `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` environment variables. Your MCP client's `"env"` config only applies to the MCP server process — when running the auth server separately, ensure these are set in a `.env` file or exported in your shell.244245## Installation246247### Prerequisites248249- **Node.js** 18.0.0 or higher250- **npm** (included with Node.js)251- **Azure account** for app registration ([free tier works](https://azure.microsoft.com/free/))252253### From npm (recommended)254255```bash256npm install -g @littlebearapps/outlook-assistant257```258259### From source260261```bash262git clone https://github.com/littlebearapps/outlook-assistant.git263cd outlook-assistant264npm install265```266267## Azure App Registration268269> **First time with Azure?** The [Azure Setup Guide](docs/guides/azure-setup.md) covers everything from creating an account to your first authentication, including billing setup and common pitfalls.270271### Create the App2722731. Open [Azure Portal](https://portal.azure.com/)2742. Sign in with a Microsoft Work or Personal account2753. Search for **App registrations** and click **New registration**2764. Enter a name (e.g. "Outlook Assistant Server")2775. Select **Accounts in any organizational directory and personal Microsoft accounts**2786. Set redirect URI: platform **Web**, URI `http://localhost:3333/auth/callback`2797. Click **Register**2808. Copy the **Application (client) ID**281282### Add Permissions2832841. Go to **API permissions** > **Add a permission** > **Microsoft Graph** > **Delegated permissions**2852. Add these **required** permissions:286 - `offline_access` — refresh tokens between sessions287 - `User.Read` — basic profile288 - `Mail.Read`, `Mail.ReadWrite`, `Mail.Send` — email operations289 - `Calendars.Read`, `Calendars.ReadWrite` — calendar operations290 - `Contacts.Read`, `Contacts.ReadWrite` — contact management291 - `MailboxSettings.ReadWrite` — settings, auto-replies, categories292 - `People.Read` — people search2933. Optionally add **org-only** permissions (work/school accounts only):294 - `Mail.Read.Shared` — shared mailbox access295 - `Place.Read.All` — meeting room search (requires admin consent)2964. Click **Add permissions**297298### Create a Client Secret2993001. Go to **Certificates & secrets** > **New client secret**3012. Enter a description and select expiration3023. Click **Add**3034. **Copy the secret Value immediately** — you won't be able to see it again. Use the **Value**, not the Secret ID.304305## Configuration306307### Environment Variables308309Create a `.env` file from the example:310311```bash312cp .env.example .env313```314315Edit with your Azure credentials:316317```bash318OUTLOOK_CLIENT_ID=your-application-client-id319OUTLOOK_CLIENT_SECRET=your-client-secret-VALUE320USE_TEST_MODE=false321```322323> **Note:** The server also accepts `MS_CLIENT_ID` and `MS_CLIENT_SECRET` for backwards compatibility.324325### MCP Client Configuration326327See [Quick Start — Configure Your MCP Client](#3-configure-your-mcp-client) above for Claude Desktop, Claude Code, Cursor, and Windsurf configs.328329If installed from source, use `node` instead of `npx`:330331```json332{333 "mcpServers": {334 "outlook": {335 "command": "node",336 "args": ["/path/to/outlook-assistant/index.js"],337 "env": {338 "OUTLOOK_CLIENT_ID": "your-application-client-id",339 "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"340 }341 }342 }343}344```345346## Authentication Flow347348### Device Code Flow (Default — Recommended)349350No auth server needed. Works everywhere, including remote/headless environments.3513521. Ask your AI assistant to authenticate (calls `auth` tool with `action=authenticate`)3532. Visit the URL shown (`microsoft.com/devicelogin`) on **any** browser, **any** device3543. Enter the code, sign in with your Microsoft account, and grant permissions3554. Tell your AI assistant to complete authentication (calls `auth` with `action=device-code-complete`)3565. Tokens are saved to `~/.outlook-assistant-tokens.json` and **refresh automatically**357358> **Prerequisite**: Enable "Allow public client flows" in Azure Portal > your app > Authentication > Advanced settings.359360### Browser Redirect Flow (Alternative)361362For localhost development or if you prefer the traditional OAuth flow:363364```bash365npm run auth-server366```367368This starts a local server on port 3333 to handle the OAuth callback.3693701. In your AI assistant, use the `auth` tool with `action=authenticate, method=browser`3712. Open the provided URL in your browser3723. Sign in and grant permissions — tokens are saved automatically373374> **Note**: The auth server reads `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` from environment variables. Your MCP client's `"env"` config only applies to the MCP server process, not a separately-started auth server.375376## Directory Structure377378```379outlook-assistant/380├── index.js # Main entry point (22 tools)381├── config.js # Configuration settings382├── outlook-auth-server.js # OAuth server (port 3333)383├── auth/ # Authentication module (1 tool)384├── email/ # Email module (7 tools)385│ ├── mail-tips.js # Pre-send recipient validation386│ ├── headers.js # Email header retrieval387│ ├── mime.js # Raw MIME/EML content388│ ├── conversations.js # Thread listing/export389│ ├── attachments.js # Attachment operations390│ └── ...391├── calendar/ # Calendar module (3 tools)392├── contacts/ # Contacts module (2 tools)393├── categories/ # Categories module (3 tools)394├── settings/ # Settings module (1 tool)395├── folder/ # Folder module (1 tool)396├── rules/ # Rules module (1 tool)397├── advanced/ # Advanced module (2 tools)398└── utils/399 ├── graph-api.js # Microsoft Graph API client (includes $batch)400 ├── safety.js # Rate limiting, recipient allowlist, dry-run401 ├── odata-helpers.js # OData query building402 ├── field-presets.js # Token-efficient field selections403 ├── response-formatter.js # Verbosity levels404 └── mock-data.js # Test mode data405```406407## Troubleshooting408409### "Cannot find module '@modelcontextprotocol/sdk/server/index.js'"410411```bash412npm install413```414415### "EADDRINUSE: address already in use :::3333"416417```bash418npx kill-port 3333419npm run auth-server420```421422### "Invalid client secret" (AADSTS7000215)423424You're using the Secret **ID** instead of the Secret **Value**. Go to Azure Portal > Certificates & secrets and copy the **Value** column.425426### Authentication URL doesn't work427428If using browser flow: start the auth server first with `npm run auth-server`. If using device code flow: visit `microsoft.com/devicelogin` instead.429430### Device code "invalid_client"431432Enable "Allow public client flows" in Azure Portal > App registrations > Authentication > Advanced settings.433434### Empty API responses435436Check authentication status with the `auth` tool (action=status). Tokens may have expired — re-authenticate if needed.437438## Development439440### Running Tests441442```bash443npm test # Jest unit tests444npm run inspect # MCP Inspector (interactive)445```446447### Test Mode448449Run with mock data (no real API calls):450451```bash452USE_TEST_MODE=true npm start453```454455### Extending the Server4564571. Create a new module directory (e.g. `tasks/`)4582. Implement tool handlers in separate files4593. Export tool definitions from the module's `index.js`4604. Import and add tools to the `TOOLS` array in main `index.js`4615. Add tests in `test/`4626. Update `docs/quickrefs/tools-reference.md`463464## Documentation465466| Guide | Description |467|-------|-------------|468| [Getting Started](docs/how-to/getting-started/connect-outlook-to-claude.md) | Install, configure, and authenticate — start here |469| [Azure Setup Guide](docs/guides/azure-setup.md) | Azure account creation, app registration, permissions, and secrets |470| [How-To Guides](docs/how-to/index.md) | 28 practical guides for email, calendar, contacts, and settings |471| [Troubleshooting & FAQ](docs/how-to/getting-started/verify-your-connection.md#common-connection-problems) | Common problems, re-authentication, and frequently asked questions |472| [Tools Reference](docs/quickrefs/tools-reference.md) | All 22 tools with parameters |473| [AI Agent Guide](docs/how-to/ai-agents/using-outlook-assistant-in-agents.md) | Tool selection and workflow patterns for AI agents |474475Full documentation: [docs/](docs/README.md)476477## Known Limitations478479- **Personal account search**: Free-text `query` and `kqlQuery` rely on Microsoft's `$search` API, which has limited support on personal Outlook.com accounts. Outlook Assistant mitigates this with progressive search fallback (trying OData filters automatically), but for the most direct results, use structured filters (`from`, `subject`, `to`, `receivedAfter`).480- **Focused Inbox**: Only available on work/school Microsoft 365 accounts.481- **Shared mailboxes**: Require `Mail.Read.Shared` permission and a work/school account.482- **Meeting room search**: Requires `Place.Read.All` permission with admin consent (work/school accounts only).483- **Export default path**: Exports save to the system temp directory by default. Use `savePath` or `outputDir` to specify a different location.484485## Contributing486487Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.488489## Security490491For security concerns, please see our [Security Policy](SECURITY.md). Do not open public issues for vulnerabilities.492493## Changelog494495See [CHANGELOG.md](CHANGELOG.md) for version history.496497## Listed On498499<a href="https://glama.ai/mcp/servers/littlebearapps/outlook-assistant"><img width="190" height="100" src="https://glama.ai/mcp/servers/littlebearapps/outlook-assistant/badge" alt="Outlook Assistant on Glama" /></a>500501## About502503Built and maintained by [Little Bear Apps](https://littlebearapps.com). Outlook Assistant is open source under the [MIT License](LICENSE).504
Full transparency — inspect the skill content before installing.