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.