@dockndevai/mcp-outlook
Summary: A safe-by-default MCP server that gives an agent scoped access to a Microsoft Outlook mailbox, OneDrive files and calendar over Microsoft Graph — read-only by default, with write/send/delete capabilities unlocked by mode and flags.
Mailbox identity & browsing —
whoami,list_folders(with unread/total counts),list_messages(by folder, unread-only, paginated).Search & read mail —
search_messagesfull-text search (subject/body/sender/recipients),get_messagefor full body and recipients,list_attachmentsfor attachment metadata (bytes never returned).Contacts —
list_contactsfor personal contacts (name, emails, company).OneDrive read access —
list_drive_items,get_drive_item,search_drive_files,download_drive_file(text content up to ~1 MB).Calendar read access —
list_calendars,list_events(time windows with recurrences expanded),get_event,get_free_busyto check availability before scheduling.Gated write operations (need
read-write/adminmode) — create drafts, send/reply/forward (plusOUTLOOK_ALLOW_SEND), mark read/unread, move messages, upload/create/move OneDrive items, and create/update/respond to events.Gated destructive operations (need
admin+OUTLOOK_ALLOW_DELETE) — delete messages, delete OneDrive items, cancel/delete events.Safety controls — folder allowlists/protected folders, human approval prompts with version pinning,
OUTLOOK_REQUIRE_HUMAN_APPROVAL, dry-run mode, and JSON audit logging; auth via browser sign-in with cached tokens, app-only client credentials, or a supplied bearer token.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@dockndevai/mcp-outlook search my inbox for unread emails from Sarah about the Q3 report"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-outlook
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 |
| confirm which mailbox is in use | read-only |
| mail folders with unread/total counts | read-only |
| recent messages (by folder, unread-only) | read-only |
| full-text search across the mailbox | read-only |
| one message with full body + recipients | read-only |
| attachment metadata (bytes not returned) | read-only |
| personal contacts | read-only |
| prepare a draft without sending | read-write |
| compose & send a new email | read-write + |
| reply (all) / forward a message | read-write + |
| mark read / unread (reversible) | read-write |
| move to another folder (asks a human first) | read-write |
| delete (to Deleted Items) | admin + |
| browse OneDrive files & folders | read-only |
| search OneDrive | read-only |
| read a OneDrive file's text | read-only |
| create/overwrite a OneDrive file (asks a human first) | read-write |
| create a folder (additive; never replaces an existing one, no prompt) | read-write |
| move / rename a OneDrive item (asks a human first) | read-write |
| delete a OneDrive item (→ recycle bin) | admin + |
| browse calendars & events (window expands recurrences) | read-only |
| check availability for people before scheduling | read-only |
| create / update a meeting (invites attendees) | read-write + |
| accept / decline / tentatively accept an invite | read-write + |
| cancel a meeting / delete an event | admin + |
Access is ultimately governed by your Microsoft account's granted scopes. Calendar tools need the
Calendars.ReadWritedelegated 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 withOUTLOOK_SCOPES(e.g. dropCalendars.ReadWrite, or useCalendars.Readfor read-only).
Related MCP server: outlook-mcp
Install
npx -y @dockndevai/mcp-outlookYou 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_IDset. 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_SECRETpresent. The server fetches an app token itself; requiresOUTLOOK_TENANT_IDandOUTLOOK_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_TOKENset 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 needread-write; deletes needadmin.OUTLOOK_ALLOW_SEND— sending mail (send / reply / forward) can't be undone, so on top ofread-writeit 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 ofadminmode.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_fileshows 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 anupload_drive_filepath — or its absence) the target's version (GraphchangeKeyfor messages and events,eTagfor 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 theOUTLOOK_ALLOW_SEND/OUTLOOK_ALLOW_DELETEgates.OUTLOOK_REQUIRE_HUMAN_APPROVAL— whentrue(defaultfalse), the operations above are refused if the client cannot elicit, instead of falling back to theOUTLOOK_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_attachmentsreturns 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 testLicence
MIT
Available Tools
15 toolsdownload_drive_fileDownload a OneDrive fileARead-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 itemARead-onlyIdempotent
Fetch metadata for a single OneDrive file or folder by path or item_id.
Inputs: path, item_id.
get_eventGet a calendar eventARead-onlyIdempotent
Fetch one event by id, with its full body, attendees, recurrence and online-meeting details.
Inputs: id (required).
get_free_busyGet free/busy scheduleARead-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 messageARead-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 attachmentsARead-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 calendarsARead-onlyIdempotent
List the calendars in the mailbox (id, name, owner, whether you can edit). Needs the Calendars scope.
Inputs: no named parameters.
list_contactsList contactsARead-onlyIdempotent
List the mailbox's personal contacts (display name, email addresses, company).
Inputs: top.
list_drive_itemsList OneDrive itemsARead-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 eventsARead-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 foldersARead-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 messagesARead-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 OneDriveARead-onlyIdempotent
Search across OneDrive for files and folders matching a query (name/content).
Inputs: query (required), top.
search_messagesSearch messagesARead-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 IARead-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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Give AI agents their own email inboxes: list, read and send mail via scoped, revocable OAuth grants.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.1ISC
- AlicenseBqualityCmaintenanceEnables AI assistants to manage Microsoft Outlook email and calendar through the Microsoft Graph API, including reading, sending, searching emails, and handling calendar events.4389 npm30MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with Microsoft 365 Outlook Mail, allowing email operations via natural language.119 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage Microsoft Outlook emails through the Microsoft Graph API, supporting operations like listing, reading, sending, and moving emails.MIT