io.github.littlebearapps/outlook-assistant

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 the conversation. Works with Claude, Cursor, Windsurf, and any MCP-compatible client.

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

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?

Features

22 tools total — consolidated from 55 for optimal AI performance. See the Tools Reference for complete parameter details.

Export Formats

Format support varies by target:

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:

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

npm install -g @littlebearapps/outlook-assistant

Or run directly without installing:

npx @littlebearapps/outlook-assistant

2. Register an Azure App

You need a Microsoft Azure app registration to authenticate. See the Azure Setup Guide 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
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:

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

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

Then set environment variables in your .env or shell.

Or add manually to .cursor/mcp.json:

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

{
  "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)

From npm (recommended)

npm install -g @littlebearapps/outlook-assistant

From source

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 covers everything from creating an account to your first authentication, including billing setup and common pitfalls.

Create the App

1. Open Azure Portal
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:

cp .env.example .env

Edit with your Azure credentials:

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_CLIENT_SECRET for backwards compatibility.

Optional overrides (v3.8.0+) — see .env.example for the full list with commented worked examples:

MCP Client Configuration

See Quick Start — Configure Your MCP Client above for Claude Desktop, Claude Code, Cursor, and Windsurf configs.

If installed from source, use node instead of npx:

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

Authentication Flow

Device Code Flow (Default — Recommended)

No auth server needed. Works everywhere, including remote/headless environments.

1. Ask your AI assistant to authenticate (calls auth tool with action=authenticate)
2. Visit the URL shown (microsoft.com/devicelogin) on any browser, any device
3. Enter the code, sign in with your Microsoft account, and grant permissions
4. Tell your AI assistant to complete authentication (calls auth with action=device-code-complete)
5. Tokens are saved to ~/.outlook-assistant-tokens.json and refresh automatically

Prerequisite: Enable "Allow public client flows" in Azure Portal > your app > Authentication > Advanced settings.

Server restarts (v3.7.2+): Device code state is persisted to ~/.outlook-assistant-pending-auth.json, so device-code-complete works even if the MCP server restarts between steps 1 and 4 (e.g., Untether/Telegram bridge, Claude Desktop session changes).

Browser Redirect Flow (Alternative)

For localhost development or if you prefer the traditional OAuth flow:

npm run auth-server

This starts a local server on port 3333 to handle the OAuth callback.

1. In your AI assistant, use the auth tool with action=authenticate, method=browser
2. Open the provided URL in your browser
3. Sign in and grant permissions — tokens are saved automatically

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.

Directory Structure

outlook-assistant/
├── index.js                 # Main entry point (22 tools)
├── config.js                # Configuration settings
├── outlook-auth-server.js   # OAuth server (port 3333)
├── auth/                    # Authentication module (1 tool)
├── email/                   # Email module (7 tools)
│   ├── mail-tips.js         # Pre-send recipient validation
│   ├── headers.js           # Email header retrieval
│   ├── mime.js              # Raw MIME/EML content
│   ├── conversations.js     # Thread listing/export
│   ├── attachments.js       # Attachment operations
│   └── ...
├── calendar/                # Calendar module (3 tools)
├── contacts/                # Contacts module (2 tools)
├── categories/              # Categories module (3 tools)
├── settings/                # Settings module (1 tool)
├── folder/                  # Folder module (1 tool)
├── rules/                   # Rules module (1 tool)
├── advanced/                # Advanced module (2 tools)
└── utils/
    ├── graph-api.js         # Microsoft Graph API client (includes $batch)
    ├── safety.js            # Rate limiting, recipient allowlist, dry-run
    ├── odata-helpers.js     # OData query building
    ├── field-presets.js     # Token-efficient field selections
    ├── response-formatter.js # Verbosity levels
    └── mock-data.js         # Test mode data

Troubleshooting

"Cannot find module '@modelcontextprotocol/sdk/server/index.js'"

npm install

"EADDRINUSE: address already in use :::3333"

npx kill-port 3333
npm run auth-server

"Invalid client secret" (AADSTS7000215)

You're using the Secret ID instead of the Secret Value. Go to Azure Portal > Certificates & secrets and copy the Value column.

Authentication URL doesn't work

If using browser flow: start the auth server first with npm run auth-server. If using device code flow: visit microsoft.com/devicelogin instead.

Device code "invalid_client"

Enable "Allow public client flows" in Azure Portal > App registrations > Authentication > Advanced settings.

Token refresh fails after ~60 minutes (device code auth)

Fixed in v3.7.2. Earlier versions sent client_secret in token refresh requests for device-code auth, which Microsoft rejects for public client flows. Update to v3.7.2+ or re-authenticate.

Empty API responses

Check authentication status with the auth tool (action=status). Tokens may have expired — re-authenticate if needed.

Development

Running Tests

npm test                     # Jest unit tests
npm run inspect              # MCP Inspector (interactive)

Test Mode

Run with mock data (no real API calls):

USE_TEST_MODE=true npm start

Extending the Server

1. Create a new module directory (e.g. tasks/)
2. Implement tool handlers in separate files
3. Export tool definitions from the module's index.js
4. Import and add tools to the TOOLS array in main index.js
5. Add tests in test/
6. Update docs/quickrefs/tools-reference.md

Documentation

Full documentation: docs/

Known Limitations

• 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).
• Focused Inbox: Only available on work/school Microsoft 365 accounts.
• Shared mailboxes: Require Mail.Read.Shared permission and a work/school account.
• Meeting room search: Requires Place.Read.All permission with admin consent (work/school accounts only).
• Export default path: Exports save to the system temp directory by default. Use savePath or outputDir to specify a different location.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Security

For security concerns, please see our Security Policy. Do not open public issues for vulnerabilities.

Changelog

See CHANGELOG.md for version history.

About

Built and maintained by Little Bear Apps. Outlook Assistant is open source under the MIT License.