Microsoft Outlook MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Microsoft Outlook email and calendar through the Microsoft Graph API.

Features

• Email Operations: Read, search, send, reply to emails and download attachments

• SharePoint Integration: Access SharePoint files via sharing links or direct file IDs. Download files shared to you via emails.

• Calendar Management: View and manage calendar events and appointments

• Office Document Processing: Parse PDF, Word, PowerPoint, and Excel files with extracted text content

• Receipt & Invoice Collection: Discover emailed receipts by sender/subject/date, save them as verified and consistently named PDFs (attachment, billing link, or rendered fallback), and stage a review draft — built for scheduled, non-interactive runs

• Large File Support: Automatic handling of files that exceed MCP response size limits

Related MCP server: MCP Outlook Server

Quick Start

Choose your installation method:

Prerequisites: Before installing, you'll need to set up an Azure application to get your Client ID and Tenant ID.

Installation

Installing as DXT Extension

For Claude Desktop users, DXT extensions provide the simplest installation experience.

Option 1: Download Pre-built Extension

1. Download outlook-mcp.dxt from the Releases page

2. In Claude Desktop, go to Settings → Extensions

3. Click Install from file and select the .dxt file

4. Enter your Azure Client ID, Tenant ID, and optional download directory when prompted

Option 2: Build from Source

1. Clone and install dependencies:

   git clone https://github.com/XenoXilus/outlook-mcp.git
   cd outlook-mcp
   npm install

2. Install the DXT CLI: npm install -g @anthropic-ai/dxt

3. Pack the extension:

   dxt pack . outlook-mcp.dxt

4. Install the generated .dxt file in Claude Desktop as above

Using with CLI Tools

For CLI-based MCP clients (Claude Code, mcp CLI, etc.), configure the server directly.

1. Clone and Install:

git clone https://github.com/XenoXilus/outlook-mcp.git
cd outlook-mcp
npm install

2. Configure your MCP client:

Add the following to your MCP servers configuration (location varies by client):

{
  "outlook-mcp": {
    "command": "node",
    "args": ["/absolute/path/to/outlook-mcp/server/index.js"],
    "env": {
      "AZURE_CLIENT_ID": "your-azure-client-id",
      "AZURE_TENANT_ID": "your-azure-tenant-id",
      "MCP_OUTLOOK_WORK_DIR": "/optional/download/directory"
    }
  }
}

Common config file locations:

• Claude Code: ~/.claude.json or project-level .mcp.json

• mcp CLI: ~/.config/mcp/servers.json

3. Alternative: Use environment variables

Instead of specifying env in the config, you can export the variables in your shell:

export AZURE_CLIENT_ID="your-azure-client-id"
export AZURE_TENANT_ID="your-azure-tenant-id"
export MCP_OUTLOOK_WORK_DIR="/optional/download/directory"

Azure Setup Guide

To use this MCP server, you need to register an application in Microsoft Azure.

For Business/Work Accounts (Recommended)

1. Go to the Azure Portal and search for "App registrations".

2. Click New registration.

   • Name: Outlook MCP (or similar)

   • Supported account types: Accounts in this organizational directory only (Single tenant)

   • Redirect URI: Select Web and enter http://localhost/callback

3. Click Register.

4. Go to Authentication in the sidebar.

   • Under "Advanced settings", set Allow public client flows to Yes.

   • Click Save.

5. On the Overview page, copy:

   • Application (client) ID → This is your AZURE_CLIENT_ID

   • Directory (tenant) ID → This is your AZURE_TENANT_ID

6. Go to API permissions in the sidebar.

   • Click Add a permission -> Microsoft Graph -> Delegated permissions.

   • Add these permissions:

     • Mail.Read, Mail.ReadWrite, Mail.Send, Mail.Read.Shared, Mail.ReadWrite.Shared, Mail.Send.Shared

     • Calendars.Read, Calendars.ReadWrite

     • Contacts.Read, Contacts.ReadWrite

     • Tasks.Read, Tasks.ReadWrite

     • User.Read, MailboxSettings.Read

     • Files.Read.All, Files.ReadWrite.All

     • Sites.Read.All, Sites.ReadWrite.All

     • offline_access

   • Click Add permissions.

   • (Optional) If you are an admin, click Grant admin consent to suppress consent prompts for users.

Note: No client secret is required (PKCE auth flow).

For Personal Accounts (outlook.com, hotmail.com)

Personal Microsoft accounts can also register apps in Azure:

1. Sign in to the Azure Portal with your personal Microsoft account (outlook.com, hotmail.com, etc.).

2. If prompted to create a directory, follow the steps to create a free Azure directory.

3. Follow the same steps as above for Business accounts.

4. When configuring, use Accounts in any organizational directory and personal Microsoft accounts for supported account types.

Configuration Reference

Environment Variables

The desktop extension (DXT) exposes only the mail settings above. The receipt/invoice behaviour below is configured by the calling process (e.g. a scheduled routine's MCP server config) via environment variables — it is intentionally not part of the extension settings UI:

Vendor rules (RECEIPT_RULES_PATH)

outlook_extract_receipt / outlook_collect_receipts work with zero configuration for receipts issued via payment processors that put the vendor in the subject line ("Your receipt from Acme #1234"). For senders that need explicit mapping, or to capture product labels, point RECEIPT_RULES_PATH at a JSON file (see receipt-rules.example.json):

• vendorSenders: [{ "pattern": "<case-insensitive regex on the from address>", "vendor": "<name>" }] — checked before the subject heuristic.

• productLabels: ["<case-insensitive regex>", ...] — first match becomes productLabel; without a match it falls back to the line-item descriptions (see Extracted fields).

Receipt & Invoice Tools

Five tools support autonomous expense-receipt collection (e.g. a scheduled monthly run):

outlook_create_draft additionally accepts attachmentPaths (absolute local file paths, ≤ 3 MB each) and returns the draft's webLink — it stages the email for review and never sends.

Collect results

outlook_collect_receipts returns { period, manifest, missing, failed, unmatched, summary, notes }. Every manifest entry has a status:

• failed[] has one object per fetch_failed entry: attemptedRoute (search, message, attachment, link or render), attemptedRoutes (the attachment content routes tried, e.g. ["json", "value"]), messageId, attachmentId/attachmentName (attachment route) and the verbatim graphError. "Nothing to collect" and "found it but could not save it" are therefore never confused.

• When a formal PDF (attachment or link) cannot be saved, the entry stays fetch_failed and gets a renderedFallback — a rendering of the email saved under its own (rendered) name — and the entry itself carries method: rendered and isFormalInvoice: false, so it is never mistaken for the invoice (savedPath is only inside renderedFallback).

• unmatched[] lists every message that matched a rule's sender/subject but was rejected by the product matchers of every such rule: { messageId, date, subject, sender, productLabel, rejectedBy }. It does not block the run.

• summary counts entries per status plus unmatched; notes carries run-level remarks (e.g. a Sent Items/Drafts folder that could not be resolved, or messages excluded by product matchers).

• Duplicates: forwarded and replied copies of one receipt are grouped when they share a receipt, invoice or order number — but never when the group would hold two different numbers of one kind or two different known totals (two charges on one order stay two receipts, even with equal totals when their receipt numbers differ; a receipt number shared by different totals adds a numberConflict note to both). Identical PDF bytes (sha256) catch the rest after saving, under the same rule (otherwise both are kept and sameFileAs names the other). The copy carrying the PDF (preferring an Invoice-*.pdf) is kept, and a copy with no total never replaces one carrying the PDF and the total; the others become duplicate with duplicate_of (e.g. receiptNumber:… or sha256:…). Messages in Sent Items and Drafts are ignored.

• File names come from the template ({vendor} {DDMmmYY} Invoice.pdf). When several receipts in one run would get the same name (one vendor, one day), each gets its own receipt/invoice/order number appended (Acme 10Jun26 Invoice 1001-2002.pdf), so re-runs map every receipt to the same file; an ordinal (2) is used only for receipts with no number, assigned oldest first. A receipt saved under the plain name by an earlier run, before a same-day sibling arrived, keeps that file (reported skipped) instead of being saved again under its new name.

• Entries carry sender, a forwarded flag and, for forwards with a quoted header, originalSender.

• Amounts are structured and gross: amounts is { subtotal, tax, credits, total, amountPaid, currency, source, totalLabel }, and amount/taxAmount are the total charged and the tax sum. For attachment and link saves the figures are re-read from the saved PDF when its total is labelled (totalLabel is amount paid, total or amount due; amountSource: pdf). An unlabelled (guessed) PDF figure never replaces the email's total — it is used only when the email has none — and sets pdfTotalGuessed: true. A PDF total of zero (e.g. only Balance due $0.00) never replaces a positive email total. amountMismatch ({ body, pdf }) appears when the two disagree.

• A billing link is used only when it is unique to one receipt in the run; a link shared by several receipts is skipped (linkSkipped).

Product matchers

A vendor rule passed to outlook_collect_receipts may also carry productContains and/or productExcludes (a string or an array of strings). Terms are case-insensitive substrings matched against the receipt's product label and its line-item descriptions, so one sender can be split into several labelled streams:

"vendors": [
  { "vendor": "Acme Hosting", "from": "billing@acme.example", "productContains": ["hosting", "domain"] },
  { "vendor": "Acme Support", "from": "billing@acme.example", "productContains": "support plan" },
  { "vendor": "Acme Other",   "from": "billing@acme.example" }
]

• A receipt whose product matches a productContains rule belongs to that rule; it beats a rule without product matchers (here, Acme Other only receives what the other two reject). productExcludes can replace the catch-all: { "vendor": "Acme Other", "from": "billing@acme.example", "productExcludes": ["hosting", "domain", "support plan"] }.

• When the email body names no product (no product label or line items) and a rule depends on one, the product is read from the PDF attachment before deciding (productSource: pdf).

• If several rules still claim a receipt, or its product cannot be read from the email or the PDF while a rule depends on it, the entry is ambiguous with candidates (and pdfProductError if the PDF could not be read) — it is never guessed or silently accepted. A receipt that every matching rule rejects is listed in unmatched[], never silently dropped.

Extracted fields

Besides vendor, productLabel and attachmentIds, outlook_extract_receipt returns:

• amounts — { subtotal, tax, credits, total, amountPaid, currency, source, totalLabel } (totalLabel says which row gave the total — amount paid, total or amount due — and is null when it had to be guessed). amount is the gross total charged (not the pre-tax subtotal) and taxAmount the tax sum. Credit and discount lines are summed; currency prefixes such as CA$, A$/AU$, NZ$, US$, HK$ and ISO codes are recognised.

• lineItems[] — { description, quantity, amount }. productLabel falls back to their descriptions when no configured productLabels pattern matches.

• receiptNumber, invoiceNumber (also read from an Invoice-<CODE>-<NNNN>.pdf attachment name) and orderNumber.

• Reply/forward handling: normalisedSubject (Re:/Fw: stripped), replyOrForward and quotedFrom ({ name, address } of the innermost quoted From: header).

• billingPdfUrl and receiptPdfUrl — per-receipt PDF download links on allowlisted hosts only; click-tracking wrappers are unwrapped, and image or logo links are never returned.

Matching and download notes

• A vendor rule's from and subjectContains combine as OR — either signal matches a receipt (subjects are compared with Re:/Fw: prefixes ignored), and each manifest entry reports matchedBy (from, from-normalised, subject, and/or product:… signals).

• Plus-addressed senders (invoice+statements+acct_...@stripe.com) match both exactly and via a plus-stripped fallback: when an exact from finds nothing, the collector retries on the base local part and keeps only messages whose normalised sender matches, noting searchNote in the manifest.

• periodStart/periodEnd (and outlook_search_emails' startDate/endDate) accept bare dates: 2026-08-31 as an end covers the whole last day instead of stopping at midnight.

• outlook_download_attachment accepts saveToFile/destDir/fileName/onExisting to write raw bytes server-side and return only {savedPath, size, sha256} — use this for real invoice PDFs instead of inline base64. The saved file is byte-exact with no inline size ceiling.

• outlook_download_attachment and outlook_save_attachment read the attachment content from its JSON item and fall back to the raw /$value endpoint, so attachment ids containing -, _ and = work. Only file attachments have downloadable bytes: attached emails (item attachments) and reference attachments are rejected with a clear message, and a failure on both routes reports the routes tried, the ids and the Graph error.

Email search

A free-text outlook_search_emails query (without a folder restriction) uses KQL, and its date range is sent to Microsoft Graph as a real property restriction with ISO UTC dates, e.g. "receipt AND received:2026-06-01..2026-06-30" — not matched as a literal phrase, and independent of the host's locale and time zone. Other searches use $filter.

• Results are re-checked against the requested date window, sender and subject. Anything the service failed to filter is dropped and counted in searchSummary.droppedOutsideFilters.

• A folder restriction is bound by the endpoint: a multi-folder search queries each folder and merges the results, rather than silently searching the whole mailbox.

• KQL values are quoted only when they contain whitespace or KQL syntax; an unparseable date is a validation error.

Shared mailboxes (v1.3)

Every mail, folder, and attachment tool — and every receipt tool (collect_receipts, extract_receipt, save_attachment, render_email_pdf, fetch_billing_pdf) — accepts an optional mailbox argument (e.g. careers@yourcompany.com). Precedence: per-call mailbox → the MCP_OUTLOOK_SHARED_MAILBOX setting → your own mailbox. Requirements:

• Exchange Full Access delegation to the shared mailbox for the signed-in user (Send As or Send on Behalf additionally governs how sends appear). One styling note: signatures and font styling are always the signed-in user's own — a send from a shared mailbox carries your personal signature, so consider preserveUserStyling: false for shared sends.

• The Mail.*.Shared delegated scopes — added in v1.3, so each user must re-consent once: the interactive flow prompts automatically on next sign-in; headless setups re-run npm run auth:bootstrap once.

Graph offers no delegated API that lists the mailboxes you hold Full Access to, so discovery is candidate-based: outlook_list_shared_mailboxes probes the addresses in the Known Shared Mailboxes setting (MCP_OUTLOOK_KNOWN_MAILBOXES), the Shared Mailbox setting, and any candidates you pass, then reports which ones actually open (with inbox counts) and which are denied, missing, or malformed. Feed an accessible address straight back as the mailbox argument.

Calendar tools stay on your own calendar in this release.

Headless (Scheduled) Runs

1. Seed tokens once, interactively: npm run auth:bootstrap (opens the browser PKCE flow and stores an encrypted refresh token).

2. Set MCP_OUTLOOK_AUTH_MODE=headless for the scheduled run. The server refreshes silently and never launches a browser; if re-consent is genuinely required it fails fast with an actionable error telling you to re-run the bootstrap.

3. Optionally set MCP_OUTLOOK_REFRESH_TOKEN_PATH to point the run at a specific token store directory.

Large File Handling

When downloading large attachments or SharePoint files, the server automatically detects when the response would exceed the MCP response cap (~30k characters by default — the practical tool-output token budget; override with MCP_OUTLOOK_MAX_RESPONSE_CHARS) and saves the content to local files instead.

• If MCP_OUTLOOK_WORK_DIR is set, large files are saved to this directory

• If not set, files are saved to the system temp directory

• Files are automatically named with timestamps to avoid conflicts

• Old files are periodically cleaned up to manage disk space

Example Prompts

Once installed, you can ask the AI assistant things like:

Email Management

• "Show me my unread emails from this week"

• "Find all emails from John about the project proposal"

• "Send a reply to the last email from Sarah thanking her for the update"

• "Draft an email to the team summarizing today's meeting"

Calendar

• "What meetings do I have tomorrow?"

• "Schedule a 30-minute call with Alex next Tuesday afternoon"

• "Show me my availability for the rest of the week"

Attachments & SharePoint

• "Download and summarize the PDF attachment from the latest email from Finance"

• "Get the contents of this SharePoint link: [paste link]"

• "What files were attached to emails from Legal this month?"

Receipts & Invoices

• "Collect all my June receipts into my receipts folder and give me the manifest"

• "Save the invoice PDF from the latest Acme receipt email as 'Acme 29Jun26 Invoice.pdf'"

• "Draft an email to my accountant with last month's receipt PDFs attached — don't send it"

Office Document Processing

The server automatically parses:

• PDF files: Extracts text content

• Word documents (.docx): Extracts text content

• PowerPoint (.pptx): Extracts slide text

• Excel (.xlsx): Parses data into structured format

Authentication

The server uses OAuth 2.0 with PKCE for secure authentication:

1. First run will open a browser for Microsoft authentication

2. Tokens are encrypted and stored locally (uses OS keychain if available, otherwise encrypted file storage)

3. Automatic token refresh for long-term usage

4. No sensitive data stored in plain text

Required Permissions

The app requests these Microsoft Graph permissions:

• Mail.Read, Mail.ReadWrite, Mail.Send - Email access

• Mail.Read.Shared, Mail.ReadWrite.Shared, Mail.Send.Shared - Shared/delegated mailbox email access (v1.3)

• Calendars.Read, Calendars.ReadWrite - Calendar access

• Contacts.Read, Contacts.ReadWrite - Contact access

• Tasks.Read, Tasks.ReadWrite - Task access

• User.Read, MailboxSettings.Read - User profile

• Files.Read.All, Files.ReadWrite.All - OneDrive/SharePoint files

• Sites.Read.All, Sites.ReadWrite.All - SharePoint sites

• offline_access - Refresh tokens

Troubleshooting

Large File Issues

• Problem: "Result exceeds maximum length" error

• Solution: Ensure MCP_OUTLOOK_WORK_DIR is set and writable

• Alternative: Files automatically save to system temp if work dir not configured

Authentication Issues

• Problem: Authentication failures

• Solution: Verify Azure AD app permissions and client ID

• Reset: Clear stored tokens and re-authenticate

Graph API Errors

• Problem: A tool fails with a Microsoft Graph error

• Details: The error text includes the HTTP status, Graph error code and message, the request-id and client-request-id, and the request method and URL as sent (never the auth header), e.g. HTTP 400 BadRequest: <message> [request-id: …; client-request-id: …] GET https://graph.microsoft.com/…. The same data is returned structured as _errorDetails.graphError (plus retryAfter when Graph throttles), and per entry as graphError in outlook_collect_receipts' failed[].

• Solution: Quote the request ids when raising the failure with Microsoft support

SharePoint Access Issues

• Problem: Cannot access SharePoint files

• Solution: Ensure sharing links are valid and user has access permissions

• Alternative: Use direct file ID access if available

Development

Project Structure

outlook-mcp/
├── server/
│   ├── index.js              # Main MCP server
│   ├── auth/                 # Authentication management
│   ├── graph/                # Microsoft Graph API client
│   ├── schemas/              # MCP tool schemas
│   ├── tools/                # MCP tool implementations
│   │   ├── attachments/      # Attachment tools
│   │   ├── calendar/         # Calendar tools
│   │   ├── email/            # Email tools
│   │   ├── folders/          # Folder management
│   │   ├── receipts/         # Receipt/invoice tools
│   │   └── sharepoint/       # SharePoint tools
│   └── utils/                # Utility modules
└── package.json

Running Tests

npm test                    # Run all tests
npm run test:watch          # Watch mode
npm run test:benchmark      # Performance benchmarks

Debugging

npm run test:graph          # Test Graph API connection

Support

If this tool saved you time, consider supporting the development!

License

MIT License

Contributing

1. Fork the repository

2. Create a feature branch

3. Make changes with tests

4. Submit a pull request