Outlook Assistant

Name: Outlook Assistant
Author: Little Bear Apps

Let your AI assistant manage your Outlook email, calendar, and contacts from the conversation.

22 tools for Outlook email, calendar, and contacts, with read-only mode, dry-run previews, a recipient allowlist, and 64% fewer tokens.

Microsoft

MCP Released

Get Started View on GitHub

What it does

Everything you'd normally do in Outlook, but from Claude

Email management

Read, search, draft, send, and organise emails, with a dry-run preview before anything goes out. Export full threads as Markdown, EML, MBOX, JSON, HTML, or CSV.

Export an email thread as Markdown for documentation

Calendar and scheduling

View upcoming or past events, create meetings, update, decline, or cancel them, and find meeting rooms — all through conversation.

Check your next meeting's details without opening Outlook

Contact and people search

Full CRUD for contacts plus relevance-based people search across your organisation.

Find a colleague's contact info by asking Claude

Mailbox automation

Create inbox rules, manage categories, configure Focused Inbox overrides, set automatic replies.

Create an inbox rule — move emails from billing@example.com with "invoice" in the subject to the Finance folder, except from internal senders

What Outlook Assistant includes

Email search and filtering
Search by sender, date, keyword, and attachment type. Filter by folder, read/unread status, and importance.
Read and compose
Read emails and compose new messages with to, cc, and bcc support. Plain text or HTML.
Draft management
Create, edit, and send email drafts through conversation. Reply and forward drafts auto-populate recipients and threading headers. Preview with dry-run mode and validate recipients before sending.
Thread export in 6 formats
Export conversations as Markdown, EML, MBOX, JSON, HTML, or CSV. Full MIME with headers for forensics and archival.
Calendar management
View upcoming events or look back at past ones, find events by date range and subject, create meetings with attendees, and update, decline, or cancel them. A retried create can't book the same meeting twice.
Contact management
Full CRUD for personal contacts plus relevance-based people search across your organisation.
Inbox rules
Create, update, reorder, and delete rules with 12 condition types (sender, subject, body, importance, sensitivity, boolean routing), 9 action types (move, copy, mark read, mark importance, forward, redirect, categorise, stop processing, delete), exception handling, and dry-run preview. Describe what you want in natural language.
Categories and Focused Inbox
Create categories with custom colours, apply to messages, and configure Focused Inbox overrides.
Automatic replies and settings
Set up out-of-office messages, configure working hours, timezone, and mailbox preferences.
Shared mailbox access
Opt-in on work/school accounts: read and organise team inboxes and service accounts, including custom subfolders and nested folder paths. Sending from a shared mailbox isn't supported.
Folder management
Create nested folders addressable by path (Parent/Child), move emails between folders, and view folder statistics and hierarchy.
Follow-up flags and meeting rooms
Set follow-up flags on messages with due dates, and search available meeting rooms in your organisation.
OAuth2 authentication
Device code flow (default) works headless and remote — no auth server, port forwarding, or client secret needed. State persists across MCP server restarts (v3.7.2+), so remote bridges like Telegram work reliably. Browser-based OAuth available as alternative. Automatic token refresh handles both public and confidential clients. Scoped to your account, revocable any time.
MCP safety annotations
Every tool sets all four annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) explicitly, so AI clients can auto-approve safe reads and prompt before sends or deletes. Claude asks before every send-email and create-event call.
Read-only mode
Set OUTLOOK_READ_ONLY=true and every call that isn't a read is refused before it runs: no sends, drafts, moves, deletes, rule or settings changes, exports, or dry runs. Searching, reading, and signing in still work.
Send limits and recipient allowlist
Cap sends, drafts, rule changes, and new events per session, and restrict recipients to approved domains or addresses. The allowlist covers sends, drafts, rule forwards, and calendar invitations.
Dry-run previews
See what a call would do without changing or sending anything: sends, drafts, new events (who would be invited, and how many are external), event updates and cancellations (who would be emailed), automatic replies, and rules.
Plugin with a safety hook
A plugin for Claude Code, GitHub Copilot CLI, and Cursor bundles the server, a skill that teaches the model who each send, reply-all, or cancellation reaches, and a hook that asks before risky calls. The server also tells every client to treat email content as data, not instructions.
Progressive search
Falls back through up to four search strategies on personal accounts (server $search → contains-subject → client-side body/subject/from scan). Every response carries _meta.searchMetadata so agents can detect when filters are dropped or which strategy actually returned the matches.
Email header forensics
DKIM, SPF, DMARC authentication checks, delivery chain tracing, and spam score analysis — built in for phishing investigation and compliance.
Delta sync
Incremental inbox monitoring — returns only new, modified, and deleted emails since your last check, with tokens for continuous polling.
Batch operations
Flag, move, export, or categorise multiple emails in a single call. Up to 20 Graph API requests per $batch. Search-driven export lets you batch-export results without collecting IDs.
Pre-send mail tips
Check recipients before sending — detects out-of-office, mailbox full, delivery restrictions, moderation, and external recipients. If anything is flagged, the send is refused with the warnings listed until you acknowledge them.
Immutable IDs
Opt-in immutable IDs — message and event IDs persist through folder moves for more reliable cross-tool workflows.

How it works

Your AI agent talks directly to Microsoft Graph. I'm not in the middle.

Direct to Microsoft

OAuth delegated permissions

Free and open source

22 tools across 9 modules

What exactly does it access?

What it accesses

Your Outlook mailbox via Microsoft Graph API (delegated permissions)
Email, calendar, contacts, and settings you explicitly grant access to

Where it stores

OAuth tokens: ~/.outlook-assistant-tokens.json
Azure client ID (not a secret): ~/.outlook-assistant-config.json

Delete ~/.outlook-assistant-tokens.json and ~/.outlook-assistant-config.json to remove local tokens and settings

Network calls

Microsoft Graph API (graph.microsoft.com)
Microsoft sign-in (login.microsoftonline.com)
No Little Bear Apps servers involved

Remove from MCP config to disable

Requires a Microsoft account

Get started in 60 seconds

Copy this prompt and paste it into any AI assistant:

I want to install the Outlook Assistant server (https://github.com/littlebearapps/outlook-assistant) on my computer. My operating system is Mac. My AI tool is [Claude Desktop/Claude Code/GitHub Copilot/Cursor/VS Code/Windsurf/Codex CLI/Gemini CLI/OpenCode]. Please guide me step-by-step, including the Azure app registration.

Or configure it yourself

Pick your AI agent and add the config manually

Requires an Azure app registration — see the Azure Setup Guide first

Windows/MacOS/Linux

Terminal

IDE

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-azure-client-id"
      }
    }
  }
}

Restart Claude Desktop after saving. Then ask Claude to connect to Outlook — it gives you a short code to enter at microsoft.com/devicelogin on any device.

Plugin (recommended)

claude plugin marketplace add littlebearapps/outlook-assistant
claude plugin install outlook-assistant@littlebearapps

The plugin adds the skill and safety hook, and asks for your client ID, send limit, allowed recipients, read-only mode, and confirmation level when you enable it. Without the plugin: claude mcp add outlook -e OUTLOOK_CLIENT_ID=your-azure-client-id -- npx -y @littlebearapps/outlook-assistant

~/.codex/config.toml

[mcp_servers.outlook]
command = "npx"
args = ["-y", "@littlebearapps/outlook-assistant"]
env = { "OUTLOOK_CLIENT_ID" = "your-azure-client-id" }

Save config and restart Codex CLI. Then ask it to connect to Outlook and enter the code it gives you at microsoft.com/devicelogin.

~/.gemini/settings.json

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-azure-client-id"
      }
    }
  }
}

Save config and restart Gemini CLI. Then ask it to connect to Outlook and enter the code it gives you at microsoft.com/devicelogin.

opencode.json

{
  "mcp": {
    "outlook": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@littlebearapps/outlook-assistant"],
      "environment": {
        "OUTLOOK_CLIENT_ID": "your-azure-client-id"
      }
    }
  }
}

Add to opencode.json in your project root or ~/.config/opencode/opencode.json for global config.

~/.cursor/mcp.json

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-azure-client-id"
      }
    }
  }
}

Add via Cursor Settings → MCP → Add Server, or edit ~/.cursor/mcp.json directly. Cursor v3.14.0+ can also load the plugin, which adds the safety hook.

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "outlook-client-id",
      "description": "Azure application (client) ID"
    }
  ],
  "servers": {
    "outlook": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "${input:outlook-client-id}"
      }
    }
  }
}

VS Code asks for the client ID the first time the server starts and stores it securely. Use it from Copilot Chat in Agent mode.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-azure-client-id"
      }
    }
  }
}

Enable MCP in Windsurf Settings → Cascade → MCP first, then add this config.

Try these prompts now

Copy one of these into your AI agent to see it in action

"Show me my unread emails from today"

Great first test — reads your inbox

"What meetings do I have this week?"

Checks your Outlook calendar

"Search my emails for invoices from last month"

Uses email search with date filtering

"Draft a reply to that last email from Sarah"

Creates a draft reply without sending

"I was tired of copying emails into Claude conversations just to get help drafting replies or summarising threads."

—

Nathan

Help & support

v3.14.1

Getting Started

Set up Outlook Assistant step by step

How-To Guides

25 practical guides

All Outlook Assistant Help

Guides, reference, and more

Related Resources

Dogfooding found 22 bugs my 1,548 tests missed The 55→20 STRAP tool consolidation, progressive search fallbacks, and two security vulnerabilities I found through real use.

Questions about Outlook Assistant

Does Outlook Assistant store or send my emails to Little Bear Apps?

No. All data flows directly between your AI client and Microsoft via the Graph API. Little Bear Apps never sees, stores, or processes your email content.

Does this work with personal Outlook.com and work/school Microsoft 365?

Yes. Outlook Assistant supports both personal Microsoft accounts (Outlook.com, Hotmail) and work/school Microsoft 365 accounts. Work accounts may require admin consent.

Is the Azure app registration free?

Yes. Azure app registration and Microsoft Graph API delegated calls are free. Azure requires a payment method on file, but the services used by Outlook Assistant incur no charges.

What permissions does it need?

Delegated permissions only — offline_access, User.Read, Mail.Read, Mail.ReadWrite, Mail.Send, Calendars.Read, Calendars.ReadWrite, Contacts.Read, Contacts.ReadWrite, MailboxSettings.ReadWrite, and People.Read. Shared-mailbox permissions are opt-in for work/school accounts via OUTLOOK_SHARED_MAILBOX: Mail.Read.Shared, plus Mail.ReadWrite.Shared with full access. Place.Read.All (meeting rooms) is optional and not requested by default. All scoped to your account and revocable at any time.

Does this work with Claude.ai or mobile apps?

No. MCP servers require a desktop client (Claude Desktop, Claude Code, GitHub Copilot, Cursor, VS Code, Windsurf, Codex CLI, Gemini CLI, or OpenCode) that can run local processes. Web-based interfaces and mobile apps don't support MCP.

Can I access shared mailboxes?

Yes, on work/school Microsoft 365 accounts, as an opt-in. Set OUTLOOK_SHARED_MAILBOX=read to read, or =true to read and organise (move, flag, categorise, create folders), then restart and sign in again. Custom subfolders work. Sending, drafts, replies, and forwards from a shared mailbox aren't supported, and shared mailboxes aren't available on personal Outlook.com accounts.

What export formats are supported?

Six formats: EML/MIME (forensics and archival), MBOX (batch archive), Markdown (human-readable), JSON (programmatic), HTML (visual archival), and CSV (spreadsheet import and compliance audits).

How do I revoke access?

Delete ~/.outlook-assistant-tokens.json and ~/.outlook-assistant-config.json locally, and revoke the app from your Microsoft account at account.microsoft.com → Privacy → Apps and services.

Can I stop it sending or changing anything?

Yes. OUTLOOK_READ_ONLY=true refuses every call that isn't a read before it runs. Short of that, OUTLOOK_MAX_EMAILS_PER_SESSION caps sends and other writes per session, OUTLOOK_ALLOWED_RECIPIENTS limits who mail and invitations can reach, and dryRun: true previews a send, event, or rule without doing it. These reduce risk rather than guarantee it, so review sends and deletes before you approve them.

Do I need an Azure client secret?

No, not for the default device-code sign-in: the client ID is enough. You only need a client secret for the optional browser redirect flow. You can also give your client ID when you first sign in instead of putting it in the config.

Is there a plugin?

Yes, for Claude Code, GitHub Copilot CLI, and Cursor. It bundles the server, the using-outlook-assistant skill, and a safety hook that asks before risky calls. In Claude Code, run claude plugin marketplace add littlebearapps/outlook-assistant, then claude plugin install outlook-assistant@littlebearapps. Other MCP clients use the manual config and still get the server's own checks.

What changes

• Instead of copying emails into Claude to draft replies, let Claude read and write directly from your mailbox.
• Instead of switching to Outlook to check your calendar before scheduling, ask Claude to check your upcoming events and create the meeting.
• Instead of manually exporting emails for documentation, ask Claude to export a thread as Markdown or EML in one step.
• Instead of navigating Outlook settings to set up rules, describe the rule in natural language and Claude creates it.
• Instead of searching through your contacts app, ask Claude to find the person by name, role, or department.

Roadmap

Have a feature idea? Let us know!

v3.14.2 — Fix queue

Next patch after v3.14.1: user-facing bug fixes that are small and safe to ship alone. Search and export query bugs (#261, #263), find-meeting-rooms classification (#240), the broken Docker image, the critical proxy-addr advisory, delta minimal output, calendar preview counts, the Mail-Advanced.ReadWrite check before 31 Dec 2026 (#131) and auto-reply docs (#305). Repo-only items (#319 release workflow, #119 citation) land before this release so it exercises them.

TBD

2/24 issues

v3.15.0 — Structured outputs, paging & Hermes

Machine-readable results and real paging: outputSchema + structuredContent on every tool, with the structured and text halves each standing alone (#285); opaque cursors for search-emails, list-events and access-shared-mailbox (#286), after list-events moves to calendarView (#239); runtime validation of nested objects, formats and ranges (#288); consistent parameter names with deprecated aliases kept until v4 (#289); descriptions that match behaviour, with a description/schema test (#243, #93); bounded parallel MIME export (#264). Also Hermes Agent support (#309, #310), the v3.14.0 follow-ups (#299), skill-eval grading fixes and supply-chain hardening (#290). Verified across the cross-client matrix.

TBD

0/15 issues

30%

v3.16.0 — Calendar, tasks & contacts

Next feature minor after v3.15.0. Recurring events with a series guard (#125), contact email fields and folders (#127, #250), Microsoft To Do behind an opt-in scope (#89), a Sent Items search hint (#117), and real $batch for bulk updates (#245). New scopes are opt-in and reported by auth action=about; nothing changes for existing sign-ins.

TBD

3/10 issues

v4.0.0 — MCP 2026-07-28 & server-side confirmation

Breaking. Migrate to MCP TypeScript SDK v2 (@modelcontextprotocol/server) and protocol 2026-07-28: stateless requests, server/discover, multi-round-trip requests and URL-mode elicitation for device-code sign-in (#291). Requires Node 22+ (Node 18 and 20 are end of life). Progress notifications and cancellation on the new handler context (#287). Server-side confirmation for outward, destructive and persistent actions, driven by the risk-class map (#269). Split mixed read/write tools, trim the tool count and remove the aliases deprecated in v3.15.0 (#292). SDK v1.x gets fixes until at least late January 2027.

TBD

0/5 issues

View roadmap on GitHub →

Changelog

v3.14.1

2 weeks ago

github-actions[bot]

•chore(release): v3.14.1 — live-test fixes

See release details on GitHub

v3.14.0

3 weeks ago

github-actions[bot]

•docs: roadmap for v3.14.0 safety skill/hooks, v3.15.0 structured outputs, v4.0.0
•v3.14.0 PR A: protocol and correctness (risk classes, JSON-RPC errors, isError, registry)
•v3.14.0 PR B: safety fixes (mail tips, rules, dry-run previews, read-only mode, log privacy)
•v3.14.0 PR C: plugin skill, safety hook and prompt-injection evals

See release details on GitHub

View all releases on GitHub →

Latest release update

Outlook Assistant v3.7.4 — JSON-Stringified Arrays + KQL Search Fixed

Also by Little Bear Apps