# Outlook Assistant

> MCP server for Outlook email, calendar, and contacts — let your AI assistant manage your inbox directly from the conversation.

- **Type:** MCP server
- **Install:** `agentstack add mcp-littlebearapps-outlook-assistant`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [littlebearapps](https://agentstack.voostack.com/s/littlebearapps)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [littlebearapps](https://github.com/littlebearapps)
- **Source:** https://github.com/littlebearapps/outlook-assistant
- **Website:** https://littlebearapps.com/builds/outlook-assistant

## Install

```sh
agentstack add mcp-littlebearapps-outlook-assistant
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

**Works with personal Outlook.com and work/school Microsoft 365 accounts.**

  
  
    
  
  
  Search inbox → read & summarise → draft a reply — all from the conversation
  

### What you can do

- 📨 **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 once
- 🛡️ **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 mistakes
- ✏️ **Draft emails for review** — create, update, and send drafts; reply and forward as drafts; preview before saving with dry-run mode
- 📅 **Manage your calendar** — view upcoming events, schedule meetings with attendees, decline or cancel invitations
- 📦 **Export emails** — save individual messages to Markdown, EML, JSON, or CSV; export full conversation threads to MBOX or HTML; bulk-export search results in one call
- 🔍 **Investigate email headers** — full raw header access (DKIM, SPF, DMARC, delivery chain, X-Mailer, X-Originating-IP) for phishing investigation and compliance review
- 🗂️ **Organise your inbox** — create folders, set up inbox rules, colour-code with categories, manage Focused Inbox — all work together for complete inbox automation
- 🔄 **Track inbox changes** — delta sync detects new, modified, and deleted emails since your last check, with tokens for incremental polling
- 👥 **Manage contacts** — search your contact book and organisational directory, create and update contact records
- ⚙️ **Configure settings** — set out-of-office auto-replies, working hours, and time zone
- 📬 **Access shared mailboxes** — read team inboxes and service accounts (Microsoft 365)
- 🏢 **Find meeting rooms** — search by building, floor, capacity, AV equipment, and wheelchair accessibility (Microsoft 365)

### Why Outlook Assistant?

| Without Outlook Assistant | With Outlook Assistant |
|---------------------|------------------|
| Switch between your AI tool and Outlook to manage email | Read, search, send, and export emails directly from your AI assistant |
| Manually search and export email threads | Full email tools including search, threading, and bulk export |
| Context-switch for calendar and contacts | Manage calendar events, contacts, and settings in one place |
| Copy-paste email content into conversations | Your AI assistant reads your emails natively with full context |
| No programmatic access to mailbox rules or categories | Create inbox rules, manage categories, configure auto-replies |
| Manually check each email for phishing red flags | Forensic header analysis — DKIM, SPF, DMARC, spam scores, and delivery chain in one call |
| Poll your inbox to check for new mail | Delta sync returns only changes since your last check, with tokens for continuous polling |

## Features

| Module | Tools | What You Can Do |
|--------|------:|-----------------|
| **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` |
| **Calendar** | 3 | `list-events`, `create-event`, `manage-event` (update/decline/cancel/delete) |
| **Contacts** | 2 | `manage-contact` (list/search/get/create/update/delete), `search-people` |
| **Categories** | 3 | `manage-category` (CRUD), `apply-category`, `manage-focused-inbox` |
| **Settings** | 1 | `mailbox-settings` (get/set auto-replies/set working hours) |
| **Folder** | 1 | `folders` (list/create/move/stats/delete) |
| **Rules** | 1 | `manage-rules` (list/create/update/reorder/delete) |
| **Advanced** | 2 | `access-shared-mailbox`, `find-meeting-rooms` |
| **Auth** | 1 | `auth` (status/authenticate/about) |

**22 tools total** — consolidated from 55 for optimal AI performance. See the [Tools Reference](docs/quickrefs/tools-reference.md) for complete parameter details.

### Export Formats

Format support varies by `target`:

| Format | Extension | `target=message` (single) | `target=messages` (batch) | `target=conversation` (thread) |
|--------|-----------|--------|--------|--------|
| `mime` / `eml` | `.eml` | ✅ | – | ✅ |
| `mbox` | `.mbox` | – | – | ✅ |
| `markdown` | `.md` | ✅ | ✅ | ✅ |
| `json` | `.json` | ✅ | ✅ | ✅ |
| `html` | `.html` | – | – | ✅ |
| `csv` | `.csv` | ✅ | ✅ | ✅ |

Export individual emails, search results, or entire conversation threads — use `target=messages` with a search query (or the `query` shortcut) to batch-export without manually collecting IDs.

## Account Compatibility

Outlook Assistant works with both personal and work/school Microsoft accounts, but some features behave differently:

| Feature | Personal (Outlook.com) | Work/School (Microsoft 365) |
|---------|----------------------|---------------------------|
| Email read, send, search | Full support | Full support |
| Calendar events | Full support | Full support |
| Contacts CRUD | Full support | Full support |
| Inbox rules | Full support | Full support |
| Folders | Full support | Full support |
| Free-text `query` search | Limited — use `subject`, `from`, `to` filters instead | Full KQL support |
| Categories | Full support | Full support |
| Mailbox settings | Full support | Full support |
| Focused Inbox | API works (overrides stored) but mail routing not affected | Full support |
| Shared mailboxes | Not available | Requires `Mail.Read.Shared` |
| Meeting room search | Not available | Requires `Place.Read.All` + admin consent |

> **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`).

### What Makes This Different

- **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.
- **Email forensics** — raw header access for DKIM, SPF, DMARC, delivery chain, X-Mailer, X-Originating-IP, and spam scores. Returns the full data so you can investigate phishing, audit compliance, or trace delivery issues. (Auto-verdict is on the v3.8.0 roadmap; today the data is surfaced and analysed in-conversation.)
- **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.
- **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.
- **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.
- **Compound automation** — rules, categories, folders, and Focused Inbox work together. Set up complete inbox management through your AI assistant in one conversation.

## Safety & Token Efficiency

Outlook Assistant is designed with safety-first principles for AI-driven email access:

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

**Send-email protections** — The `send-email` tool includes:
- **Pre-send mail tips** (`checkRecipients: true`) — check recipients for out-of-office, mailbox full, delivery restrictions before sending
- **Dry-run mode** (`dryRun: true`) — preview composed emails without sending
- **Session rate limiting** — configurable via `OUTLOOK_MAX_EMAILS_PER_SESSION` (default: unlimited)
- **Recipient allowlist** — restrict sending to approved addresses/domains via `OUTLOOK_ALLOWED_RECIPIENTS`

> **Recommended setup**: enable both safety belts in your `.mcp.json` from day one. They're off by default; `auth action=about` reports their state and prints a setup hint when unset. See [`.mcp.json.example`](.mcp.json.example) for a copy-paste template.
>
> ```json
> "env": {
>   "OUTLOOK_CLIENT_ID": "…",
>   "OUTLOOK_CLIENT_SECRET": "…",
>   "OUTLOOK_MAX_EMAILS_PER_SESSION": "10",
>   "OUTLOOK_ALLOWED_RECIPIENTS": "your-domain.com,trusted@example.com"
> }
> ```

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

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

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

## Quick Start

### 1. Install

```bash
npm install -g @littlebearapps/outlook-assistant
```

Or run directly without installing:

```bash
npx @littlebearapps/outlook-assistant
```

### 2. Register an Azure App

You 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:

1. Create a new app registration at [portal.azure.com](https://portal.azure.com/)
2. Add Microsoft Graph delegated permissions (Mail, Calendar, Contacts)
3. Create a client secret and copy the **Value** (not the Secret ID)
4. Under Authentication > **Add a platform** > **Mobile and desktop applications** — check `nativeclient` URI
5. Enable **"Allow public client flows"** in Authentication > Advanced settings
6. _(Optional)_ Set redirect URI to `http://localhost:3333/auth/callback` — only needed for browser auth flow

### 3. Configure Your MCP Client

Add to your MCP client config:

Claude Desktop (claude_desktop_config.json)

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

Claude Code (CLI)

```bash
claude mcp add outlook -- npx @littlebearapps/outlook-assistant
```

Then set environment variables in your `.env` or shell.

Cursor (.cursor/mcp.json)

[](cursor://anysphere.cursor-deeplink/mcp/install?name=Outlook%20Assistant&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsaXR0bGViZWFyYXBwcy9vdXRsb29rLWFzc2lzdGFudCJdLCJlbnYiOnsiT1VUTE9PS19DTElFTlRfSUQiOiIiLCJPVVRMT09LX0NMSUVOVF9TRUNSRVQiOiIifX0=)

Or add manually to `.cursor/mcp.json`:

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

Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### 4. Authenticate

1. Start the auth server: `outlook-assistant-auth` (or `npx @littlebearapps/outlook-assistant-auth`)
2. In your AI assistant, use the `auth` tool with `action=authenticate` to get an OAuth URL
3. Open the URL, sign in with your Microsoft account, and grant permissions
4. Tokens are saved locally and refresh automatically

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

## Installation

### Prerequisites

- **Node.js** 18.0.0 or higher
- **npm** (included with Node.js)
- **Azure account** for app registration ([free tier works](https://azure.microsoft.com/free/))

### From npm (recommended)

```bash
npm install -g @littlebearapps/outlook-assistant
```

### From source

```bash
git clone https://github.com/littlebearapps/outlook-assistant.git
cd outlook-assistant
npm install
```

## Azure App Registration

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

### Create the App

1. Open [Azure Portal](https://portal.azure.com/)
2. Sign in with a Microsoft Work or Personal account
3. Search for **App registrations** and click **New registration**
4. Enter a name (e.g. "Outlook Assistant Server")
5. Select **Accounts in any organizational directory and personal Microsoft accounts**
6. Set redirect URI: platform **Web**, URI `http://localhost:3333/auth/callback`
7. Click **Register**
8. Copy the **Application (client) ID**

### Add Permissions

1. Go to **API permissions** > **Add a permission** > **Microsoft Graph** > **Delegated permissions**
2. Add these **required** permissions:
   - `offline_access` — refresh tokens between sessions
   - `User.Read` — basic profile
   - `Mail.Read`, `Mail.ReadWrite`, `Mail.Send` — email operations
   - `Calendars.Read`, `Calendars.ReadWrite` — calendar operations
   - `Contacts.Read`, `Contacts.ReadWrite` — contact management
   - `MailboxSettings.ReadWrite` — settings, auto-replies, categories
   - `People.Read` — people search
3. Optionally add **org-only** permissions (work/school accounts only):
   - `Mail.Read.Shared` — shared mailbox access
   - `Place.Read.All` — meeting room search (requires admin consent)
4. Click **Add permissions**

### Create a Client Secret

1. Go to **Certificates & secrets** > **New client secret**
2. Enter a description and select expiration
3. Click **Add**
4. **Copy the secret Value immediately** — you won't be able to see it again. Use the **Value**, not the Secret ID.

## Configuration

### Environment Variables

Create a `.env` file from the example:

```bash
cp .env.example .env
```

Edit with your Azure credentials:

```bash
OUTLOOK_CLIENT_ID=your-application-client-id
OUTLOOK_CLIENT_SECRET=your-client-secret-VALUE
USE_TEST_MODE=false
```

> **Note:** The server also accepts `MS_CLIENT_ID` and `MS_CL

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [littlebearapps](https://github.com/littlebearapps)
- **Source:** [littlebearapps/outlook-assistant](https://github.com/littlebearapps/outlook-assistant)
- **License:** MIT
- **Homepage:** https://littlebearapps.com/builds/outlook-assistant

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-littlebearapps-outlook-assistant
- Seller: https://agentstack.voostack.com/s/littlebearapps
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.