Skip to main content
Glama
outlook-mcp

outlook-mcp

by Plong-Wasin

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

Related MCP server: Outlook Email MCP Server

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.

Available Tools

22 tools
auth_pollA

Check if the authentication is complete. Only call this after auth_start returned a verification URL and the user has completed sign-in on the Microsoft website. Do NOT call this unless you just ran auth_start and it returned a code/URL for the user to visit.

Inputs: no named parameters.

auth_startA

Start the Outlook authentication flow. IMPORTANT: Only call this tool when you receive an authentication error (e.g. 'Not authenticated') from another tool, or when the user explicitly requests re-authentication. Do NOT call this proactively before using other Outlook tools — they automatically use the stored token. If a valid token already exists, this returns immediately without starting a new auth flow.

Inputs: force, clientId, tenantId.

delete_messageA

Delete a Message or Draft by moving it to the Deleted Items folder. The message is NOT permanently erased — it can be recovered from Deleted Items.

Inputs: messageId (required).

forward_draftA

Create a forward Draft to new Recipients, instead of forwarding immediately. Review or edit it, then use send_draft. Returns the created Draft's id, subject, and to/cc.

Inputs: to (required), messageId (required), cc, bcc, +2 more.

forward_messageC

Forward a Message to one or more new Recipients. Optionally include a comment prepended to the forwarded message.

Inputs: to (required), messageId (required), comment.

get_messageA

Read the full content of a single Message by ID. Returns body (plain text or HTML), all recipients, and attachment metadata (name, size, type — not file content).

Inputs: messageId (required), bodyType.

list_contact_foldersA

List the user's contact folders (contact lists) from Outlook, such as 'My ThailandPostMart - Dev'. To see contacts inside a folder, use list_contacts with the folderId.

Inputs: top, skip, folderId.

list_contactsA

List personal Contacts from the authenticated user's Outlook address book. Optionally filter by name or email.

Inputs: top, skip, search.

list_distribution_groupsB

List mail-enabled Distribution Groups in the organisation (classic distribution lists). Each group has a single email address that delivers to all its members.

Inputs: top, skip, search.

list_group_membersB

List all members of a Microsoft 365 Group. Useful for finding email addresses of everyone in a group before sending.

Inputs: groupId (required), top, filter, search, +1 more.

list_mail_foldersA

List all mail folders in the authenticated user's mailbox, including custom folders. Returns folder IDs needed for list_messages with non-standard folders.

Inputs: top, skip.

list_messagesA

List Messages from a mail folder. Use folder 'inbox', 'drafts', 'sentitems', or 'deleteditems' (well-known names), or pass a folderId from list_mail_folders. Supports full-text search and OData filter — but NOT both at once.

Inputs: top, skip, filter, folder, +1 more.

list_usersA

Search or list Azure AD users in the organisation. Use 'search' to find users by name or email. Without 'search', returns all users paginated. Useful for finding recipient email addresses.

Inputs: top, skip, search, select.

mark_messageC

Mark a Message as read or unread.

Inputs: isRead (required), messageId (required).

reply_all_draftA

Create a reply-all Draft addressed to the sender and all original Recipients, instead of sending immediately. Review who it's going to, then use send_draft. Returns the created Draft's id, subject, and to/cc.

Inputs: messageId (required), comment, contentType.

reply_all_messageB

Reply to a Message, sending immediately to the sender and all original Recipients. Thread history is preserved automatically.

Inputs: comment (required), messageId (required).

reply_draftA

Create a reply Draft addressed to the original sender, instead of sending immediately. Review or edit it, then use send_draft. Returns the created Draft's id, subject, and to/cc.

Inputs: messageId (required), comment, contentType.

reply_messageB

Reply to a Message. Thread history is preserved automatically. The reply is sent immediately.

Inputs: comment (required), messageId (required).

save_draftA

Save an email as a draft in Microsoft Outlook without sending it. Recipients are optional — a Draft can be started with just a subject and body, with recipients added later via update_draft. Supports CC, BCC, plain text or HTML body, and file attachments (max 3 MB each).

Inputs: body (required), subject (required), cc, to, +3 more.

send_draftA

Send a previously saved Draft by its message ID. Use save_draft to create a Draft, update_draft to edit it, then send_draft to transmit it to Recipients.

Inputs: messageId (required).

send_emailA

Send an email immediately via Microsoft Outlook. Supports To, CC, BCC, plain text or HTML body, and file attachments (max 3 MB each).

Inputs: to (required), body (required), subject (required), cc, +3 more.

update_draftA

Partially update a saved Draft. Only fields you supply are changed — omitted fields are left as-is on the server. Use list_messages(folder: 'drafts') to find Draft IDs.

Inputs: messageId (required), cc, to, bcc, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 22 tools

    Disambiguation4/5

    Each tool targets a fairly distinct resource+action, and the message/draft suffix pattern clearly separates immediate-send operations (reply_message, forward_message) from draft-creating ones (reply_draft, forward_draft). The closest overlaps are reply_message vs reply_all_message and send_email vs send_draft, but descriptions make the intent clear enough that misselection risk is low.

    Naming Consistency4/5

    Nearly all tools follow a clean verb_noun snake_case convention (list_messages, get_message, send_draft, delete_message), which is very predictable. The only deviations are the two auth tools (auth_start, auth_poll) that use noun_verb order, a minor inconsistency in an otherwise uniform set.

    Tool Count3/5

    22 tools is on the heavy side for a mailbox client, with a large cluster of near-sibling reply/forward variants (immediate vs draft, single vs all) that multiply the surface. Each tool does earn a place in the draft workflow, so it is defensible but not tightly scoped.

    Completeness4/5

    Core mail lifecycle is well covered: list/read, send, reply, reply-all, forward, draft create/update/send, delete, mark read/unread, plus folder, contact, and user lookup for addressing. Notable gaps remain — attachments are metadata-only (no download of file content), no move/copy between folders, and no folder creation — but agents can work around these for most tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      MCP server that provides 62 tools to manage Outlook mail, calendar, contacts, and tasks for personal Microsoft accounts via Microsoft Graph API.
      71
      995 PyPI
      45
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server providing full control over Outlook.com, Hotmail, Live, or Microsoft 365 email via Microsoft Graph API, enabling reading, searching, sending, and managing messages and folders securely.
      1
      MIT