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.
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.
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.
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 (reversible) | read-write |
| delete (to Deleted Items) | admin + |
Related MCP server: outlook-mcp
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).
{
"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.
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.
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 and deleting a message pause and ask the human to approve before running; clients that can't elicit fall back to the OUTLOOK_ALLOW_SEND / OUTLOOK_ALLOW_DELETE gates.
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.
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 testMIT
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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Message id (from list_messages or search_messages) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds value by disclosing the exact response contents: body, recipients, importance, and conversation id, which is beyond annotation data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the action and return fields, then provide the id-sourcing hint. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required parameter, rich annotations, and the description listing the key fields returned, an agent has enough to call the tool correctly. Since there is no output schema, the description reasonably conveys the expected return content, though it does not address error/not-found behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already documents that 'id' is a message id from list_messages or search_messages. The description repeats this guidance without adding new parameter semantics, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Fetch a single message by id' with its full body, recipients, importance, and conversation id. It distinguishes itself from sibling list/search tools by emphasizing the single-message-by-id scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent where to obtain valid ids ('Get ids from list_messages or search_messages'), which acts as contextual usage guidance. It does not explicitly state when not to use this tool, but the id-sourcing instruction makes the workflow clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a message's attachments as metadata only (id, name, contentType, size, isInline). Attachment bytes are intentionally not returned.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Message id (from list_messages or search_messages) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false EB, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by explicitly stating that only metadata is returned and attachment bytes are intentionally omitted, which is a meaningful behavioral constraint an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler. It front-loads the core action and resource, then immediately specifies the output scope and the intentional exclusion of bytes. Every word contributes to the agent's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is simple, has one well-documented parameter, strong annotations, and no output schema is present, the description provides all essential context: what is listed, what fields are returned, and what is not returned. Nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains that 'id' is a message id from list_messages or search_messages. The tool description adds no additional parameter-level meaning beyond 'a message's attachments,' so the baseline of 3 is appropriate since the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List a message's attachments as metadata only.' It also clarifies the tool returns metadata fields like id, name, contentType, size, and isInline, and explicitly excludes attachment bytes, which distinguishes it from any content-returning alternative. This is unambiguous and directly tied to the tool's name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is used when a message's attachments are needed, and the schema reinforces the input comes from list_messages or search_messages. It does not explicitly state when not to use it or name alternatives among siblings, but none of the siblings provide attachment listing, so the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the mailbox's personal contacts (display name, email addresses, company).
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum contacts to return (capped by OUTLOOK_MAX_RESULTS) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the specific returned fields but does not disclose additional behavioral details like pagination behavior, ordering, or that results are limited by OUTLOOK_MAX_RESULTS; that constraint appears only in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action and resource, with the output fields parenthetically. Every word earns its place, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter, the description plus annotations and schema are complete. The return fields are explicitly listed, and read-only/idempotent behavior is covered by annotations, so an agent has enough context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the 'top' parameter is already documented in the schema with its minimum, maximum, and purpose. The description adds no parameter-specific meaning, but the baseline of 3 applies because the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List), the resource (the mailbox's personal contacts), and the returned fields (display name, email addresses, company). This makes it immediately distinguishable from sibling tools like list_folders, list_messages, and search_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for retrieving personal contacts, and no sibling tool overlaps with that responsibility. It doesn't explicitly state when not to use it or name alternatives, but for a simple resource-specific list operation the usage context is sufficiently implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by clarifying the listing is 'top-level' and by disclosing the exact returned information (ids, display names, unread/total counts). This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The first sentence states the action and output shape; the second provides the most valuable follow-up instruction. The structure is well front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a zero-parameter, safe, idempotent listing endpoint. The description fully covers return content and the natural next step (passing a folder id to list_messages). No output schema is present, but the description explicitly names the output fields, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tooool has zero parameters and the input schema has no properties, so there is no parameter semantics for the description to add. The 0-parameter baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('the mailbox's top-level mail folders') and lists the returned fields: ids, display names, and unread/total counts. It also distinguishes itself from message-level siblings like list_messages by specifying folder scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear follow-up guidance: 'Use a folder id or well-known name (inbox, sentitems, drafts, archive) with list_messages.' It implies when this tool is useful—when you need folder identifiers to query messages—and names list_messages as the relevant sibling. It does not explicitly exclude other siblings, but that is unnecessary for a simple top-level listing tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum messages to return (capped by OUTLOOK_MAX_RESULTS) | |
| folder | No | Mail folder id or well-known name (inbox, sentitems, drafts, archive, deleteditems). Defaults to the whole mailbox. | |
| unread_only | No | Only return unread messages |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond those flags: results are ordered most-recent-first, output is limited to compact summary fields, and folder/unread filtering is supported. This is richer than a mere safety flag and gives the agent an accurate mental model of the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler. The core action and ordering are front-loaded, scoping is summarized, the return format is specified in parentheticals, and the pointer to get_message is the final sentence. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description properly enumerates the returned fields, so the agent knows what to expect and can distinguish this list tool from get_message. Annotations cover the safety/idempotence profile, and sibling names put the tool in context. Nothing essential for a correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: all three parameters (top, folder, unread_only) already have descriptive docs. The description echoes folder and unread_only but does not add syntax, defaults, or the meaning of top beyond what the schema provides. This is the expected baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the verb-resource pair 'List messages' and immediately specifies ordering ('most recent first'), optional scoping ('folder'/'unread'), and the output shape ('compact summaries with id, subject, from, received, isRead, hasAttachments, preview'). It distinguishes the tool from get_message by pointing out it returns summaries not full bodies, and the sibling search_messages is implicitly separate because this tool lists rather than searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly routes to get_message for full bodies ('Fetch full bodies with get_message'), giving a clear alternative. It also states when optional scoping applies (folder, unread). It does not explicitly compare against search_messages or state when not to use list_messages, but the context is clear enough for an agent to pick between listing and searching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum results (capped by OUTLOOK_MAX_RESULTS) | |
| query | Yes | Search text, e.g. "quarterly report" or "from:bob@contoso.com" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, non-destructive behavior. The description adds useful behavioral context beyond that: it uses Microsoft Graph $search, searches specific message fields, and returns compact summaries rather than full messages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with a small example list and a final note on output format. Every part earns its place, and the key behavioral distinction is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with one required parameter, read-only annotations, and no output schema, the description is mostly complete. It could more fully describe the returned summary fields, but 'compact summaries' plus the schema and examples provide enough guidance for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters well, so the baseline is 3. The description adds extra meaning by giving concrete query examples such as 'from:alice@contoso.com' and 'subject:release', which illustrate the field-scoped syntax beyond the schema's simple examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Full-text search') and resource ('the mailbox'), and scopes it to subject, body, sender, and recipients. This clearly distinguishes it from sibling tools like list_messages, which would be a plain listing rather than a search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear this is the search-oriented tool and even shows query syntax with examples. It does not explicitly say 'do not use this to list all messages' or name alternatives, but the context is strong enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds value by explaining the operational rationale (confirming the mailbox identity before actions), which is beyond the structured metadata. It doesn't detail potential edge cases, but for a simple read-only look-up, this is adequate given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the action and output, then gives usage context. No filler or redundancy; every word earns its place. Ideal for quick scanning by an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only identity tool with no output schema, the description is complete: it states what is returned and when to use it. There is no missing information an agent would need to invoke it correctly. The tool's simplicity means the description fully covers operational needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema needs no description. The description usefully lists the exact fields returned (display name, UPN, id), which helps an agent understand the output even without an output schema. With schema coverage at 100% (trivially) and no params, the baseline of 4 applies, and the description adds relevant info about return values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and resource ('signed-in mailbox's identity') with concrete output fields (display name, user principal name, id). It also signals a unique purpose—confirming which mailbox the server is on—that distinguishes it from sibling operations like list_folders or get_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using the tool 'before reading or writing,' giving a clear contextual trigger. It doesn't enumerate alternatives or when-not-to-use, but as a standalone identity check, it competes with no sibling tool, so the guidance is sufficient for an agent to know when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_messagelist_attachmentslist_contactslist_folderslist_messagessearch_messageswhoamiScored across 7 tools
Each tool targets a distinct operation, and list_messages vs search_messages are differentiated by browsing a folder vs full-text search. The only mild ambiguity is that both return message summaries, but the descriptions clarify when to use each.
Tools mostly follow a verb_noun snake_case pattern with list_/get_/search_ prefixes. whoami is the clear outlier and does not match the naming convention.
Seven tools is an appropriate scope for an Outlook-focused server. Each tool has a clear role with no redundancy.
The set covers read-only mailbox navigation, message retrieval, search, attachment metadata, and contacts. However, there are no write/action tools such as send, reply, move, delete, or mark-as-read, and attachment bytes are intentionally unavailable, so the surface is incomplete for a full Outlook workflow.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Task-scoped email inboxes for AI agents: read mail, extract verification codes, and reply.
Stateful email for AI agents — read inboxes, reply in-thread, draft with approval.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
