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

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
     • Calendars.Read, Calendars.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-run 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 rules it is null.

Receipt & Invoice-Run Tools (v1.1)

Five tools support autonomous expense-receipt collection (e.g. a scheduled monthly invoice 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.

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 1MB limit 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
• Calendars.Read, Calendars.ReadWrite - Calendar 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

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