outlook-mcp

A Model Context Protocol (MCP) server for sending and managing Microsoft Outlook email via the Microsoft Graph API.

Features

Send email — To, CC, BCC, plain text or HTML body, file attachments (max 3 MB each)
Save draft — Save a message to Drafts without sending
Update draft — Partially edit a saved Draft (only supplied fields change)
Send draft — Transmit a saved Draft to its recipients
List mail folders — Discover all folders including custom ones
List messages — Browse any folder with full-text search or OData filter
Get message — Read full message body (plain text or HTML) + attachment metadata
Reply / Forward — Reply to or forward an existing message
Mark message — Mark as read or unread
Delete message — Move to Deleted Items (recoverable)
List contact folders — Browse personal contact lists (folders) and their contacts
List contacts — Search personal Outlook address book
List M365 Group members — Find everyone in a Microsoft 365 Group
List distribution groups — Find mail-enabled distribution lists in the organisation
List users — Search or browse Azure AD users across the organisation

Authentication

Uses OAuth 2.0 Device Code Flow — no browser redirect required. Tokens are stored locally at .access-token.txt and refreshed automatically.

auth_start  →  visit the URL, enter the code  →  auth_poll

Note: auth_start should only be called when another tool returns an authentication error. Do not call it proactively — all tools load the stored token automatically.

Setup

1. Install dependencies and build

npm install
npm run build

2. Register in Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "outlook": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\Users\\staff\\Documents\\mcp\\outlook-mcp\\build\\index.js"]
    }
  }
}

3. Authenticate

Call auth_start once, follow the instructions, then call auth_poll to complete login.

Tools

Authentication

Tool	Description
`auth_start`	Start the Microsoft authentication flow
`auth_poll`	Complete authentication after signing in

Sending & Drafts

Tool	Description
`send_email`	Send an email immediately
`save_draft`	Save an email as a draft
`update_draft`	Partially edit a saved draft (only supplied fields change)
`send_draft`	Send a previously saved draft by its ID

Reading Mail

Tool	Description
`list_mail_folders`	List all mail folders including custom ones
`list_messages`	List messages from any folder; supports search and filter
`get_message`	Read full message content (body + attachment metadata)

Mail Actions

Tool	Description
`reply_message`	Reply to a message (thread history preserved)
`forward_message`	Forward a message to new recipients
`mark_message`	Mark a message as read or unread
`delete_message`	Move a message to Deleted Items

Address Book & Directory

Tool	Description
`list_contact_folders`	List personal contact folders; pass `folderId` to list contacts inside
`list_contacts`	List personal Outlook contacts (supports search)
`list_group_members`	List members of a Microsoft 365 Group
`list_distribution_groups`	List mail-enabled distribution groups in the org
`list_users`	Search or list Azure AD users in the organisation

send_email / save_draft Parameters

Parameter	Type	Required	Description
`to`	`string[]`	✅	Recipient email addresses
`subject`	`string`	✅	Email subject
`body`	`string`	✅	Email body content
`cc`	`string[]`	—	CC recipients
`bcc`	`string[]`	—	BCC recipients
`contentType`	`"text" \| "html"`	—	Body format (default: `"text"`)
`attachments`	`string[]`	—	Local file paths to attach (max 3 MB each)

Scopes

This MCP requests the following Microsoft Graph permissions:

Mail.Send — Send email
Mail.ReadWrite — Save drafts
Group.Read.All — List group members and distribution groups
GroupMember.Read.All — Read group membership
Directory.Read.All — Browse the directory
Contacts.Read — Read personal contacts
User.Read.All — Search/list organisation users
offline_access — Keep the session alive with a refresh token

Token Storage

Tokens are stored at outlook-mcp/.access-token.txt (excluded from git via .gitignore).

Attachment Limits

Attachments are encoded inline (base64). Files larger than 3 MB are rejected with a clear error before any API call is made. For larger files, share a link instead.