Outlook MCP Server: Setup, Tools & Real Limits
Microsoft now offers a preview Outlook mail connection through Work IQ MCP, but its licensing, consent, and write risks make it a deliberate infrastructure choice rather than a quick inbox add-on.
An Outlook MCP server lets an AI agent search, read, draft, send, reply to, update, and delete Outlook mail through Microsoft Graph. The best-supported choice is now Microsoft's Work IQ Mail server, but it remains preview software, requires Microsoft 365 tenant configuration, and should start with tightly controlled permissions and human approval for every write.
Table of contents
- What Outlook MCP actually is
- What exists today
- How to set it up
- Tools you get
- Permissions and blast radius
- Real limits
- When not to use it
What Outlook MCP actually is
An Outlook MCP connection translates between an MCP-capable agent and Outlook mail operations exposed through Microsoft Graph. The model does not log into the Outlook desktop app; the server presents typed tools, accepts arguments, calls Microsoft services, and returns structured results.
An agent can find messages about a customer, fetch one by ID, prepare a draft, reply to a thread, or send approved mail. Work IQ Mail also supports categories, importance, sent-item listing, and deletion. Search covers subject, body, content, and attachments using KQL-style queries, though results must still fit the agent's working context (Work IQ Mail reference).
MCP standardizes discovery and tool calling; Microsoft Graph still governs identity, mailbox access, paging, throttling, and mutation. For how tools differ from resources and prompts, see the MCP Directory guide to MCP capabilities.
What exists today
There is a first-party option, but it is not a general-availability Outlook plug-in for every client. Microsoft calls it Work IQ Mail, identifies it as mcp_MailTools, hosts it per tenant, and labels it preview—not intended for production, with names and parameters subject to change (Microsoft's reference).
| Option | Hosting and maturity | Best fit | Main trade-off |
|---|---|---|---|
| Microsoft Work IQ Mail | Microsoft-hosted, first-party, preview | Governed Microsoft 365 agents | Better tenant controls; substantial licensing and admin setup |
ryaker/outlook-mcp | Local, community-maintained source | Reviewed prototypes | Broader features; you own security and upgrades |
| Direct Microsoft Graph script | Your runtime, no MCP layer | Fixed workflows | Less agent flexibility; easier testing and smaller attack surface |
The community repository documents email, calendar, folders, rules, OneDrive, and Power Automate tools, plus local token storage. It requires cloning source, installing dependencies, registering an Entra app, and running its auth flow (ryaker/outlook-mcp on GitHub). I would use it only after code, dependency, secret-storage, and test-tenant review—not against an executive mailbox on a directory's recommendation. Compare the best MCP servers and Microsoft's entries in the official collection.
How to set it up
For Microsoft's server, register a public client in Microsoft Entra, grant the Work IQ Mail permission, configure a redirect URI, and connect to the tenant endpoint. You need an Entra account, app registration or consent rights, a compatible client, and a Microsoft 365 Copilot license (Work IQ MCP overview).
- Select or create an Entra app registration. Record its client ID and tenant ID.
- Add the WorkIQ-MailServer API permission and complete consent. If user consent is disabled, involve an administrator.
- Add the client redirect URI. Microsoft's Claude Code walkthrough uses
http://localhost:8080/callback. - Configure the real tenant and client IDs, then authenticate from the client.
- Inspect discovered tools and test with a non-sensitive mailbox before enabling writes.
For Claude Code, Microsoft publishes this exact shape:
{
"mcpServers": {
"WorkIQ-MailServer": {
"type": "http",
"url": "https://agent365.svc.cloud.microsoft/agents/tenants/{tenantId}/servers/mcp_MailTools",
"oauth": {
"clientId": "{clientId}",
"callbackPort": 8080
}
}
}
}
Do not paste it unchanged into another client: VS Code and GitHub Copilot CLI use different fields in Microsoft's guide. The MCP config generator offers a starting point, but vendor client schemas remain authoritative. Failures commonly trace to a wrong tenant ID, unregistered callback, missing consent, tenant policy, or unavailable license/region.
Tools you get
Work IQ Mail currently publishes ten mail tools, covering the read-compose-send loop but not all of Outlook or Graph. These identifiers come from Microsoft's preview reference, so treat them as discoverable runtime contracts rather than permanent names.
| Tool name | What it does |
|---|---|
mcp_MailTools_graph_mail_createMessage | Creates a text or HTML draft |
mcp_MailTools_graph_mail_deleteMessage | Deletes a message by ID |
mcp_MailTools_graph_mail_getMessage | Retrieves one message by ID |
mcp_MailTools_graph_mail_listSent | Lists sent messages with query options |
mcp_MailTools_graph_mail_reply | Replies to one message |
mcp_MailTools_graph_mail_replyAll | Replies to all recipients |
mcp_MailTools_graph_mail_searchMessages | Searches messages with KQL-style queries |
mcp_MailTools_graph_mail_sendDraft | Sends an existing draft |
mcp_MailTools_graph_mail_sendMail | Sends as the signed-in user |
mcp_MailTools_graph_mail_updateMessage | Changes subject, body, categories, or importance |
Absent are attachment transfer, forward, folder management, inbox rules, and calendar operations. Graph supports more, and the community project exposes some of it, but the first-party mail server does not advertise those tools (tool reference).
Permissions and blast radius
Start read-only where the design allows it; if a server bundles reads and writes behind one permission, require client confirmation and isolate the mailbox. A dedicated integration account limits history, delegated access, and the ability to impersonate a trusted sender.
A careless write is costly: sendMail sends as the user, replyAll can disclose text to a thread, updateMessage alters content or categories, and deleteMessage changes mailbox state. Email can also contain prompt injection. Review recipients, subject, body, links, and exact action—not merely a generic “allow tool” dialog.
Graph recommends least privilege and distinguishes reading, read/write access, and sending (Graph permissions reference). For app-only community deployments, scope access to selected mailboxes with current Exchange App RBAC; Microsoft marks Application Access Policies as legacy (Exchange guidance). Log tool, mailbox, message ID, recipients, and outcome while redacting bodies and tokens.
Real limits
The constraints are paging, model context, throttling, preview churn, and missing tools—not MCP syntax. Feeding hundreds of full messages into one prompt is expensive and hurts relevance; search narrowly, select minimal fields, summarize in batches, and fetch full content only for shortlisted IDs.
Graph's list-messages API defaults to 10 items and permits $top from 1 to 1,000, but large pages with full payloads can cause HTTP 504 timeouts (list messages documentation). Work IQ decides which Graph controls its tools expose, so raw-API pagination is not guaranteed.
Graph can also return 429 Too Many Requests; clients should honor Retry-After, back off, and avoid polling. Outlook limits apply per app-and-mailbox alongside broader limits, and Microsoft recommends Data Connect rather than REST for bulk extraction (Graph throttling guidance).
The server cannot automate all of Outlook. It has no calendar, rules, folders, forwarding, or attachment transfer tools. Preview names may change, regional availability may lag, and protected, shared, or delegated mailboxes can behave differently. Build around discovered tools and explicit failure handling, not the assumption that “Outlook access” means the whole product.
When not to use it
Do not use an Outlook MCP server for personal inbox assistance, a deterministic batch, or production work that cannot tolerate a changing preview contract. Choose the narrowest mechanism that completes the task.
Use Copilot in Outlook for thread summaries, drafting, coaching, prioritization, or inbox chat inside Outlook. Microsoft documents limits around primary versus shared or archive mailboxes and protected messages (Copilot in Outlook FAQ). MCP adds credentials and operations without a new outcome here.
Use a Graph script when inputs, rules, and outputs are fixed—for example, label matching mail or send a templated report. Code offers deterministic retries, idempotency, tests, and audit events. Use MCP when an agent must choose among mail tools from changing natural-language requests; the trade-off is permission risk, non-determinism, and context management. My default is read-only search first, drafts second, and autonomous sending or deletion only for constrained integration accounts with review and recovery procedures.