Skip to main content
Glama
@dockndevai/mcp-outlook

@dockndevai/mcp-outlook

mcp-outlook

npm CI licence

A safe-by-default Model Context Protocol server for Microsoft Outlook mail, over Microsoft Graph. It lets an agent read and operate a mailbox — list folders and messages, full-text search, read bodies and attachment metadata, list contacts, and (in higher modes) create drafts, send / reply / forward, mark read, move messages, and delete. It also manages OneDrive files — browse, search, download, upload, create folders, move/rename, and delete — and the calendar — list calendars and events, check free/busy, and (gated) create, update, respond to, cancel and delete events.

Browser sign-in: on first run it opens your browser to the Microsoft sign-in page, then caches the token and refreshes it silently — the server never sees your password.

Part of the dockndevai MCP server suite — one governance model across all of them.

What it gives an agent

The server starts read-only (see Safe by default); higher-capability tools are only registered when you raise the mode.

Tool

For

Needs mode

whoami

confirm which mailbox is in use

read-only

list_folders

mail folders with unread/total counts

read-only

list_messages

recent messages (by folder, unread-only)

read-only

search_messages

full-text search across the mailbox

read-only

get_message

one message with full body + recipients

read-only

list_attachments

attachment metadata (bytes not returned)

read-only

list_contacts

personal contacts

read-only

create_draft

prepare a draft without sending

read-write

send_mail

compose & send a new email

read-write + OUTLOOK_ALLOW_SEND

reply_mail / forward_mail

reply (all) / forward a message

read-write + OUTLOOK_ALLOW_SEND

mark_read

mark read / unread (reversible)

read-write

move_message

move to another folder (asks a human first)

read-write

delete_message

delete (to Deleted Items)

admin + OUTLOOK_ALLOW_DELETE

list_drive_items / get_drive_item

browse OneDrive files & folders

read-only

search_drive_files

search OneDrive

read-only

download_drive_file

read a OneDrive file's text

read-only

upload_drive_file

create/overwrite a OneDrive file (asks a human first)

read-write

create_drive_folder

create a folder (additive; never replaces an existing one, no prompt)

read-write

move_drive_item

move / rename a OneDrive item (asks a human first)

read-write

delete_drive_item

delete a OneDrive item (→ recycle bin)

admin + OUTLOOK_ALLOW_DELETE

list_calendars / list_events / get_event

browse calendars & events (window expands recurrences)

read-only

get_free_busy

check availability for people before scheduling

read-only

create_event / update_event

create / update a meeting (invites attendees)

read-write + OUTLOOK_ALLOW_SEND

respond_to_event

accept / decline / tentatively accept an invite

read-write + OUTLOOK_ALLOW_SEND

cancel_event / delete_event

cancel a meeting / delete an event

admin + OUTLOOK_ALLOW_DELETE

Access is ultimately governed by your Microsoft account's granted scopes. Calendar tools need the Calendars.ReadWrite delegated scope (included in the defaults). If your token wasn't consented for it, Graph returns 403 — the suite's modes/flags are defence in depth on top of that Microsoft-level control. Downscope with OUTLOOK_SCOPES (e.g. drop Calendars.ReadWrite, or use Calendars.Read for read-only).

Related MCP server: outlook-mcp

Install

npx -y @dockndevai/mcp-outlook

You need an Entra (Azure AD) app registration. For the default browser sign-in, register a public client and add the redirect URI http://localhost (platform: Mobile and desktop applications), then use its Application (client) ID as OUTLOOK_CLIENT_ID. Grant delegated Mail.Read (and Mail.Send / Mail.ReadWrite if you want to send or organize). No client secret is needed for interactive use.

Prefer automation? Use app-only auth instead: set OUTLOOK_CLIENT_SECRET + OUTLOOK_TENANT_ID + OUTLOOK_USER (see Authentication).

Configure

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-outlook"],
      "env": {
        "OUTLOOK_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "OUTLOOK_TENANT_ID": "common",
        "OUTLOOK_MODE": "read-only"
      }
    }
  }
}

On first use the server opens your browser to sign in and caches the token at ~/.mcp-outlook/token.json (0600); later runs refresh silently.

See docs/CLIENTS.md for Claude Code / Cursor / Codex / VS Code / Windsurf snippets, and .env.example for every supported variable.

Authentication

Auth mode is chosen automatically (override with OUTLOOK_AUTH):

  • interactive (default) — only OUTLOOK_CLIENT_ID set. Authorization-code + PKCE with a loopback redirect: the browser opens, you approve once, and the access + refresh token are cached on disk. Operates on the signed-in user's mailbox (/me). The server never handles your password.

  • client-credentials (app-only) — OUTLOOK_CLIENT_SECRET present. The server fetches an app token itself; requires OUTLOOK_TENANT_ID and OUTLOOK_USER (the mailbox to act on, since an app token has no signed-in user). Grant the app application Mail permissions with admin consent.

  • token — OUTLOOK_TOKEN set to a pre-obtained Graph bearer token. You manage its lifetime.

Safe by default

The access model is enforced by src/security.ts — defence in depth on top of the Graph token's own scopes/roles:

  • OUTLOOK_MODE — read-only (default) → read-write → admin. A tool is registered only if the mode allows its capability. Read-only exposes the 7 read tools; drafts/moves need read-write; deletes need admin.

  • OUTLOOK_ALLOW_SEND — sending mail (send / reply / forward) can't be undone, so on top of read-write it also requires this flag. Drafting is always allowed in read-write; nothing leaves the mailbox until sent.

  • OUTLOOK_ALLOW_DELETE — deletes require this flag on top of admin mode.

  • OUTLOOK_FOLDER_ALLOWLIST / OUTLOOK_PROTECTED_FOLDERS — confine which folders can be written to / moved into; mark folders (e.g. sentitems, archive) that may be read but never modified.

  • Interactive confirmation — when the client supports MCP elicitation, sending mail (send_mail / reply_mail / forward_mail), calendar invitations/changes/responses (create_event / update_event / respond_to_event), cancel_event, the delete tools (delete_message / delete_drive_item / delete_event) and the writes that change an existing object (upload_drive_file, move_message, move_drive_item) pause and ask the human to approve before running. The prompt shows the tool, the exact (secret-redacted) arguments and a fingerprint of them; for sends the recipients (to/cc/bcc) and subject are listed separately so they stay visible when a long body is truncated in the arguments dump (the dump is cut at 1500 characters). upload_drive_file shows the path, whether it overwrites an existing file (with its size) or creates a new one, and the byte length; the moves show the item and where it goes from and to. For existing objects (delete_message, delete_drive_item, cancel_event, delete_event, update_event, move_message, move_drive_item, and the file at an upload_drive_file path — or its absence) the target's version (Graph changeKey for messages and events, eTag for OneDrive items) is pinned across the prompt and the action is refused if it changed. A prompt nobody answers is a refusal. Clients that can't elicit fall back to the OUTLOOK_ALLOW_SEND / OUTLOOK_ALLOW_DELETE gates.

  • OUTLOOK_REQUIRE_HUMAN_APPROVAL — when true (default false), the operations above are refused if the client cannot elicit, instead of falling back to the OUTLOOK_ALLOW_* gates alone.

  • OUTLOOK_DRY_RUN — validate and log writes without executing them.

  • OUTLOOK_AUDIT_LOG — a JSON audit line per guarded operation, on stderr (default on).

  • Attachment bytes are never returned — list_attachments returns metadata only.

See SECURITY.md.

Developing

npm install
npm run build
# introspect the tool list without signing in (uses a fake token, no network):
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | OUTLOOK_TOKEN=x node dist/index.js
npm test

Licence

MIT

Available Tools

15 tools
download_drive_fileDownload a OneDrive fileA
Read-onlyIdempotent

Download a OneDrive file's contents as text (capped at ~1 MB). Best for text/markdown/JSON/CSV; binary files come back as best-effort UTF-8, so prefer webUrl for those. Give path or item_id.

Inputs: path, item_id.

get_drive_itemGet OneDrive itemA
Read-onlyIdempotent

Fetch metadata for a single OneDrive file or folder by path or item_id.

Inputs: path, item_id.

get_eventGet a calendar eventA
Read-onlyIdempotent

Fetch one event by id, with its full body, attendees, recurrence and online-meeting details.

Inputs: id (required).

get_free_busyGet free/busy scheduleA
Read-onlyIdempotent

Check availability (free/busy) for one or more people over a time window — useful before proposing a meeting time. Returns each address's availability view for the window.

Inputs: end (required), start (required), schedules (required), interval_minutes.

get_messageGet messageA
Read-onlyIdempotent

Fetch a single message by id with its full body, recipients (to/cc/bcc), importance, and conversation id. Get ids from list_messages or search_messages.

Inputs: id (required).

list_attachmentsList attachmentsA
Read-onlyIdempotent

List a message's attachments as metadata only (id, name, contentType, size, isInline). Attachment bytes are intentionally not returned.

Inputs: id (required).

list_calendarsList calendarsA
Read-onlyIdempotent

List the calendars in the mailbox (id, name, owner, whether you can edit). Needs the Calendars scope.

Inputs: no named parameters.

list_contactsList contactsA
Read-onlyIdempotent

List the mailbox's personal contacts (display name, email addresses, company).

Inputs: top.

list_drive_itemsList OneDrive itemsA
Read-onlyIdempotent

List the files and folders in a OneDrive folder. Give a path relative to the drive root (e.g. "/Documents"), or an item_id from a previous result. Omit both for the root. Returns id, name, isFolder, size, childCount, lastModified, webUrl.

Inputs: path, item_id.

list_eventsList calendar eventsA
Read-onlyIdempotent

List events, newest window first. Give start and end (ISO 8601) to get a time window with recurring events expanded; omit them to list upcoming/raw events. Optionally scope to one calendar.

Inputs: end, limit, start, calendar_id.

list_foldersList mail foldersA
Read-onlyIdempotent

List the mailbox's top-level mail folders with their ids, display names, and unread/total counts. Use a folder id or well-known name (inbox, sentitems, drafts, archive) with list_messages.

Inputs: no named parameters.

list_messagesList messagesA
Read-onlyIdempotent

List messages, most recent first. Optionally scope to a folder and/or only unread messages. Returns compact summaries (id, subject, from, received, isRead, hasAttachments, preview). Fetch full bodies with get_message.

Inputs: top, folder, unread_only.

search_drive_filesSearch OneDriveA
Read-onlyIdempotent

Search across OneDrive for files and folders matching a query (name/content).

Inputs: query (required), top.

search_messagesSearch messagesA
Read-onlyIdempotent

Full-text search across the mailbox (subject, body, sender, recipients) using Microsoft Graph $search. Example queries: "invoice", "from:alice@contoso.com", "subject:release". Returns compact summaries.

Inputs: query (required), top.

whoamiWho am IA
Read-onlyIdempotent

Return the signed-in mailbox's identity (display name, user principal name, id). Use this to confirm which mailbox the server is operating on before reading or writing.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct resource+action pair across four clearly separated domains (mail, calendar, contacts, drive). The list/get/search distinctions are explicitly spelled out in the descriptions (e.g. search_messages is full-text $search vs list_messages for recent items), leaving little room for misselection.

    Naming Consistency4/5

    Nearly all tools follow a clean snake_case verb_noun convention (list_messages, get_event, download_drive_file, search_drive_files). The only deviations are the bare `whoami` and the noun-phrase `get_free_busy`, which are minor and still readable.

    Tool Count5/5

    15 tools is at the top of the well-scoped range and is justified by spanning four domains, with roughly 3-4 focused tools per domain. No tool feels redundant or padded.

    Completeness2/5

    The surface is almost entirely read-only: no send/reply/move/delete for mail, no create/update/cancel or RSVP for calendar events, no write access for contacts, and no upload for drive. The `whoami` description references 'reading or writing', implying write intent that the tool set does not deliver, so common agent workflows will dead-end.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with Microsoft Outlook via the Microsoft Graph API for managing emails and calendar events. It allows users to read and send emails, list messages, and create calendar appointments with automatic Teams links.
      1
      ISC
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to manage Microsoft Outlook email and calendar through the Microsoft Graph API, including reading, sending, searching emails, and handling calendar events.
      43
      89 npm
      30
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to interact with Microsoft 365 Outlook Mail, allowing email operations via natural language.
      119 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to manage Microsoft Outlook emails through the Microsoft Graph API, supporting operations like listing, reading, sending, and moving emails.
      MIT