How do I use outlook-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@outlook-mcp-server find emails from Amazon with invoices" 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.

outlook-mcp-server

by dhtim135

Overview Schema Related Servers Score Discussions

Python

Local

outlook-mcp-server

A lightweight Model Context Protocol (MCP) server for personal Microsoft Outlook / Hotmail accounts. It connects Claude (or any MCP-compatible AI) to your inbox via the Microsoft Graph API, using OAuth 2.0 device-code flow — no service account or admin consent required.

Tools

Tool	Parameters	Description
`search_emails`	`query`, `max_results`	Search your inbox using KQL (Keyword Query Language). Supports filtering by sender, subject, date, attachment presence, and more.
`read_email`	`message_id`	Fetch the full body (plain text + HTML) and headers of a specific email.
`list_attachments`	`message_id`	List all attachments on an email, including their IDs, names, sizes, and content types.
`download_attachment`	`message_id`, `attachment_id`, `save_path`	Download an attachment and save it to a local file path.
`mark_as_read`	`message_id`, `read`	Mark an email as read or unread.
`move_email`	`message_id`, `folder`	Move an email to a folder by well-known name (e.g. `inbox`, `deleteditems`, `archive`) or folder ID.

These tools compose naturally for email-automation workflows — for example: search by sender → read body → download attachments → mark read → move to archive.

Related MCP server: Outlook Email MCP Server

Setup

1. Azure App Registration (one-time)

Personal Microsoft accounts still require an Azure App Registration to call Graph.

Go to https://portal.azure.com → Microsoft Entra ID → App registrations → New registration.
Name: outlook-mcp-server (or anything).
Supported account types: choose "Personal Microsoft accounts only".
Redirect URI: leave blank for now.
After creation, copy the Application (client) ID — this is your OUTLOOK_MCP_CLIENT_ID.
Open Authentication → enable "Allow public client flows" = Yes → Save.
Open API permissions → Add a permission → Microsoft Graph → Delegated permissions → check Mail.ReadWrite → Add. (No admin consent needed for personal accounts.)

2. Install

git clone https://github.com/dhtim135/outlook-mcp-server
cd outlook-mcp-server
uv sync

3. Authenticate (one-time)

export OUTLOOK_MCP_CLIENT_ID="<your-client-id>"
uv run python login.py

Follow the device code prompt — visit the URL in any browser, enter the code, sign in with your Hotmail/Outlook.com account, and approve the Mail.ReadWrite permission.

The token is cached at ~/.config/outlook-mcp/token-cache.json (mode 0600). Refresh tokens are rotated automatically as long as the server is used at least every ~90 days.

4. Register with Claude Code

claude mcp add outlook \
  --env OUTLOOK_MCP_CLIENT_ID="<your-client-id>" \
  -- uv --directory /path/to/outlook-mcp-server run python server.py

Or add manually to your MCP config:

{
  "mcpServers": {
    "outlook": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/outlook-mcp-server",
        "run", "python", "server.py"
      ],
      "env": {
        "OUTLOOK_MCP_CLIENT_ID": "<your-client-id>"
      }
    }
  }
}

KQL search examples

from:amazon.com
subject:invoice
from:receipts@uber.com received>=2026-01-01
hasattachment:yes from:doordash.com

Multiple terms are AND-ed. Quote phrases with spaces.

Re-authentication

If you see Token refresh failed, just re-run uv run python login.py.

Available Tools

6 tools

download_attachmentB

Download an attachment to save_path (absolute path; parent dirs auto-created).

Returns {path, bytes_written, name}.

ParametersJSON Schema

Name	Required	Description	Default
`message_id`	Yes
`attachment_id`	Yes
`save_path`	Yes

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses auto-creation of parent directories and return fields (path, bytes_written, name), but does not mention side effects, error conditions, or if it is destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with key information front-loaded. No unnecessary words, but the structure could be improved by listing parameters more clearly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Missing context: no explanation of where message_id/attachment_id come from, no mention of errors, file size limits, or response behavior. Given no output schema and no annotations, the description is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% with no parameter descriptions. The description only explains save_path ('absolute path; parent dirs auto-created'), ignoring message_id and attachment_id. This is insufficient for a 3-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Download an attachment') and the resource (attachment), and specifies the result format. It distinguishes from sibling tools like 'list_attachments' which list attachments, or 'read_email' which reads email content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no prerequisites mentioned (e.g., need message_id and attachment_id from list_attachments), and no indication of when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_attachmentsB

List attachments on a message. Returns list of {id, name, contentType, size}.

ParametersJSON Schema

Name	Required	Description	Default
`message_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries full burden. It discloses the output shape and that it lists attachments, which is adequate but lacks details on pagination, limits, or authentication needs. The description is honest but not rich in behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the purpose and output, with no unnecessary words. It earns its place in the documentation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool, the description covers the basics but omits details like pagination behavior, what happens with no attachments, and whether the list is complete. With a sibling like download_attachment, more context on scope could help.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description does not explain the message_id parameter beyond its name. It adds no semantic meaning, such as how to obtain the id or any constraints, leaving the schema as the sole source of information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action is to list attachments on a message and specifies the output format with fields id, name, contentType, size. This distinguishes it from siblings like download_attachment, which likely handles a single attachment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like download_attachment, nor any prerequisites beyond the required message_id. There's no mention of when not to use it or context for its use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mark_as_readA

Mark a message as read (default) or unread. Returns {id, isRead}.

ParametersJSON Schema

Name	Required	Description	Default
`message_id`	Yes
`read`	No

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must convey behavioral traits. It correctly indicates the action (toggling read) and the return format {id, isRead}. However, it does not disclose potential side effects, authorization requirements, or limits, which is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently states the purpose and includes the return type. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two parameters and no output schema, the description covers the essential action and result. It lacks usage context but is largely sufficient for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, yet the description does not elaborate on the parameters beyond their names. 'message_id' is self-explanatory, but 'read' could benefit from more context (e.g., that it defaults to true). The description adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'mark' and the resource 'message', and specifies the action (as read or unread). It distinguishes itself from sibling tools like move_email and read_email by focusing on the read/unread toggle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as read_email or search_emails. There is no mention of prerequisites or scenarios for toggling read status.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

move_emailA

Move a message to a folder.

folder = well-known name (archive, inbox, deleteditems, junkemail, sentitems, drafts) or a folder ID returned by another Graph call. Returns {id, parentFolderId}.

ParametersJSON Schema

Name	Required	Description	Default
`message_id`	Yes
`folder`	Yes

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It mentions the return value but does not disclose behavioral traits like idempotency, error cases, or permissions needed for the move operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with three sentences, each adding value. The first sentence states the action, followed by parameter details and return value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity and no output schema, the description covers purpose and parameters adequately but lacks behavioral context and usage guidelines. It is minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It explains the 'folder' parameter with examples of well-known names and folder IDs, but 'message_id' is not described beyond the schema type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Move a message to a folder', specifying the verb and resource. It distinguishes from sibling tools like read_email and search_emails, which perform different actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when needing to move an email, but does not provide explicit guidance on when to use this tool versus alternatives or any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_emailB

Read full body + headers of one message.

Returns {id, subject, from, to, received, body, body_type, hasAttachments}.

ParametersJSON Schema

Name	Required	Description	Default
`message_id`	Yes

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description lists return fields but does not disclose side effects, authentication needs, rate limits, or error conditions. Since annotations are absent, the tool's read-only nature is implied but not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: one for purpose, one for output structure. No wasted words, front-loaded with core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool, the description covers basic functionality and output. Missing details like usage prerequisites, error handling, or operational context (e.g., whether reading marks as read). Adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'message_id' lacks description beyond its type. With 0% schema description coverage, the description should compensate by explaining where to obtain the ID or its format, which it does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Read full body + headers') and the resource ('one message'), and distinguishes from sibling tools like search_emails and move_email by specifying it is for a single message's full content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs. alternatives. It does not mention prerequisites (e.g., using search_emails to find an ID) or when not to use it (e.g., for multiple messages).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_emailsA

Search emails using Graph KQL syntax.

Examples: 'from:amazon.com', 'subject:invoice', 'from:receipts@x.com received>=2026-01-01'.
Returns list of {id, subject, from, received, snippet, hasAttachments, isRead}.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`max_results`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden of disclosure. It states the return format but does not explicitly indicate that the operation is read-only or mention any side effects, permissions, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences plus examples and a clear return field list. Every sentence serves a purpose without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the moderate complexity (2 parameters, output schema exists), the description covers query syntax, examples, and return fields. It lacks details on pagination or error handling, but the output schema provides some structure, making it fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds meaning via examples for the 'query' parameter, but does not explain 'max_results'. The return list description helps interpret the output, but parameter semantics are only partially addressed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: searching emails using Graph KQL syntax. It distinguishes from sibling tools (e.g., read_email, download_attachment) by its search focus and unique query language.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides examples of valid queries, implying usage, but does not explicitly state when to use this tool over alternatives like read_email for a single email or list_attachments for attachments.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

6 tool updatesv0.1.0May 28, 2026
- First observeddownload_attachment
- First observedlist_attachments
- First observedmark_as_read
- First observedmove_email
- First observedread_email
- First observedsearch_emails

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Disambiguation5/5

Each tool targets a distinct operation (downloading, listing, marking, moving, reading, searching) with no overlap. The resource (email or attachment) and action are clearly separated.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case (download_attachment, list_attachments, etc.), making it predictable and easy to navigate.

Tool Count5/5

6 tools is a well-scoped number for an email client MCP server. It covers the essential operations without being bloated or too sparse.

Completeness4/5

The set covers reading, searching, moving, marking read, and attachment handling. Missing send/compose and delete operations, which are common but not critical for a read-focused server.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

nylas A
io.usefulapi
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
Email Calendar Management CRM
152
mailtempo
com.mailtempo
MCP server for MailTempo's public free temporary email inboxes.
Email Testing & QA Tools
2
email A
dev.primitive
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email Communication
302
MCP Emails AOAuth
com.mcpemails
Read, search, send, organize, draft and schedule email across your inboxes from any MCP client.
Communication Email
25

Related MCP Servers

mcp-outlook-lite
Email Calendar Management
w21180239
A
license
Not graded
quality
D
maintenance
Lightweight MCP server that enables AI agents to manage Microsoft Outlook email, calendar, and files using PKCE authentication with only a Client ID.
Updated 6 months ago (2026-03-18 21:58 UTC)
MIT
Outlook Email MCP Server
Email Communication Cloud Platforms
nhatho0001
F
license
A
quality
B
maintenance
An MCP server that enables reading and managing Microsoft 365 / Outlook emails through Microsoft Graph API, allowing users to list, search, send, draft, and authenticate using device code flow.
Updated 2 months ago (2026-07-16 15:59 UTC)
17
-
outlook-mcp
ajs117
F
license
Not graded
quality
B
maintenance
Local MCP server for personal Outlook.com/Hotmail/Live accounts, enabling email triage, folder management, bulk operations, and newsletter unsubscribe via Microsoft Graph.
Updated 2 months ago (2026-07-20 19:36 UTC)
-
Outlook MCP
lanSall
A
license
A
quality
C
maintenance
A local stdio MCP server that enables reading, sending, and searching emails, as well as listing calendar events via Microsoft Graph API, using device-code authentication.
Updated 2 months ago (2026-07-21 01:11 UTC)
10
114
MIT

Appeared in Searches

An MCP server for reading emails

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dhtim135/outlook-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server