Skip to main content
Glama
deenesjakoruzh
Zacccck

Claude-Read-Outlook-Attachments

by Zacccck
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

M365 Attachment Reader MCP Local

Claude-MCP-Read-Email-Attachments MCP server

A local stdio MCP server for Claude Desktop that reads Outlook emails and their attachments — and sends local files (e.g. a daily dashboard .pptx) as Outlook attachments — through the Microsoft Graph API.

Status: Functional for personal single-user local use with Claude Desktop.

What's New in v0.2.0

  • send_outlook_email — compose an Outlook email with local files attached (e.g. a .pptx) and either save it as a draft for review (default) or send it immediately (send_now: true). Small attachments only (each < 3 MB, inlined via Microsoft Graph).

  • read_email — read the full text/body of a specific Outlook email (subject, sender, recipients, date; HTML converted to plain text). The original tools read attachments; this reads the message body itself.

  • list_recent_messages now also returns a bodyPreview snippet per message.

  • Persistent login — the MSAL token cache (incl. the refresh token) is now persisted to disk, so auth survives app/process restarts: sign in once and the server silently refreshes tokens (no more re-auth every restart). This makes unattended/scheduled use possible.

  • Scopes widened to User.Read, Mail.ReadWrite, Mail.Send (was User.Read, Mail.Read). Existing users must add the new delegated permissions in Entra and re-consent.

  • Manifest upgraded to DXT v0.2 (mcp_config nested under server) so it installs as a Desktop Extension (.mcpb) on current Claude Desktop. New optional config: M365_SEND_MAX_BYTES, M365_SEND_ALLOWED_DIRS.

Related MCP server: Outlook MCP Python

Why This Exists

Claude's built-in Microsoft 365 connector can list emails, read message bodies, and check calendars. But it cannot read the actual content inside email attachments.

That means when you say "What does the PDF in my latest email say?", Claude can see the attachment metadata, but not the text, tables, images, or nested documents inside it.

This project fills that gap — running entirely on your local machine over stdio, with no public endpoints or tunnels required.

Recognition / Distribution

Claude-MCP-Read-Email-Attachments MCP server

What It Does

This server runs as a local MCP process started by Claude Desktop. It:

  1. Authenticates with Microsoft 365 via device code flow

  2. Lists Outlook emails and their attachments through Microsoft Graph

  3. Downloads and parses attachment contents locally

  4. Returns structured text and image blocks directly to Claude Desktop

  5. Reads the text/body of a specific email (HTML converted to plain text) via read_email

  6. Composes outgoing Outlook emails with local files attached (e.g. PPTX), saved as a draft for review or sent immediately

Supported Formats

Format

What Gets Extracted

PDF

Full text content

Scanned PDF

OCR text, plus optional rendered page images

DOCX

Text and embedded images

DOC

Text content

PPTX / PPTM / PPSX / POTX

Slide text, notes, and embedded images

PPT

Best-effort legacy text extraction

XLSX / XLS / CSV

All sheets converted to CSV

JPG / JPEG / PNG / GIF / WEBP / BMP / TIFF

Returned as MCP image blocks for visual analysis

ZIP / RAR / 7Z

Archive contents recursively parsed file by file

MSG

Subject, sender, body, and embedded attachments

TXT / MD / JSON / XML / HTML

Raw text

Outlook itemAttachment

Text content

MCP Tools

Tool

Description

health_check

Check if the server is alive

begin_auth

Start device code login flow

auth_status

Check authentication status

list_recent_messages

List recent Outlook emails

list_email_attachments

List attachments for a specific email

read_email_attachment

Download, parse, and return attachment content

read_email

Read the full text/body of a specific Outlook email (subject, sender, recipients, date, body)

send_outlook_email

Attach local files (e.g. .pptx) and save a draft (default) or send immediately

Outbound send is opt-in per call. send_outlook_email defaults to creating a draft in your Drafts folder — nothing leaves your mailbox until you review and send it in Outlook. Pass send_now: true to send directly. Each attachment must be under 3 MB (see Limitations).

Real-World Use Cases

Retail / Sales Operations

"Pull the last 5 Daily Dashboard emails, read the Excel attachments, and analyze the sales trend across all store locations over the past week."

Finance / Accounting

"Find the latest email from our vendor with 'Invoice' in the subject, read the PDF attachment, and extract the total amount, due date, and line items."

Legal / Contract Review

"Open the most recent email from legal@partner.com, read the Word or PowerPoint attachment, and summarize the key terms."

HR / Recruiting

"Find emails from recruiting@company.com with attachments, read each resume PDF, and create a comparison table of candidates."

Sending a report (outbound)

"Attach ~/Desktop/Daily Dash.pptx and save a draft to my manager with the subject 'Daily Dash — today' — I'll review it before sending."

"Send ~/Desktop/Daily Dash.pptx to jane@contoso.com right now with the subject 'Daily Dash' and a one-line note."

Prerequisites

  • Windows 10/11, macOS, or Linux

  • Node.js 20 or later

  • Claude Desktop

  • A Microsoft 365 / Outlook account

  • A Microsoft Entra app registration (see Step 1 below)

Setup

1. Create a Microsoft Entra App Registration

Go to Microsoft Entra admin center → App registrations → New registration.

  • Name: anything you like, e.g. m365-mcp-local

  • Supported account types: Accounts in any organizational directory and personal Microsoft accounts

Then:

  1. Copy the Application (client) ID from the Overview page

  2. Go to Authentication → enable Allow public client flows → Save

  3. Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions → add User.Read, Mail.ReadWrite, and Mail.Send → Grant admin consent

  4. Go to Manifest → find requestedAccessTokenVersion (it may be nested inside api) → set it to 2 → Save

Why Mail.ReadWrite + Mail.Send? Reading emails/attachments needs read access (Mail.ReadWrite includes the old Mail.Read). Saving a draft needs Mail.ReadWrite; sending needs Mail.Send. The send_outlook_email tool uses both. If you only ever want to read, you can drop down to User.Read + Mail.Read and edit SCOPES in server.mjs accordingly.

Already set up an earlier read-only version? Adding new scopes does not upgrade an existing login automatically. After adding Mail.ReadWrite and Mail.Send (and granting consent), restart Claude Desktop and run begin_auth again — you'll be prompted to consent to the new permissions, and a fresh token with send rights is issued.

Why step 4? When your app supports personal Microsoft accounts, Microsoft Entra requires access tokens to be v2. The portal doesn't always set this automatically, and the common endpoint will fail with AADSTS50059 if the token version is still null or 1. If you skip this step you will get invalid_grant errors during begin_auth.

Using v1 API integrations? Only set this to 2 if all your Graph/API permissions support v2 tokens (all Microsoft Graph delegated permissions do). If you're integrating custom APIs that only accept v1 tokens, use M365_TENANT_ID=consumers (personal accounts only) or a specific tenant ID instead of common, and leave requestedAccessTokenVersion at its default.

2. Clone and Install

git clone https://github.com/Zacccck/Claude-MCP-Read-Email-Attachments.git
cd Claude-MCP-Read-Email-Attachments
npm install

3. Configure Environment Variables

Copy the example file:

cp .env.example .env

Edit .env and fill in your client ID:

M365_CLIENT_ID=your-application-client-id-here
M365_TENANT_ID=common
M365_AUTO_OPEN_BROWSER=true

Variable reference:

Variable

Required

Description

M365_CLIENT_ID

✅ Yes

Your Entra app's Application (client) ID

M365_TENANT_ID

No

Default common works for most accounts

M365_AUTO_OPEN_BROWSER

No

Set true to auto-open Microsoft login page

M365_MCP_DATA_DIR

No

Custom path for auth cache; auto-detected if omitted

M365_SEND_MAX_BYTES

No

Total attachment-size budget for send_outlook_email (default 3145728 = 3 MB; must stay under Graph's ~4 MB request limit)

M365_SEND_ALLOWED_DIRS

No

OS-path-separated allowlist of directories send_outlook_email may read from. Empty (default) = any readable path

4. Find Your Node.js Path

You'll need the full path to node.exe (Windows) or node (macOS/Linux) in the next step.

# Windows
where.exe node

# macOS / Linux
which node

Example output: C:\Program Files\nodejs\node.exe

5. Open Claude Desktop's Config File

Locate and open the config file for your platform:

Platform

Path

Windows (standard)

%APPDATA%\Claude\claude_desktop_config.json

Windows (Store)

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

If the file does not exist yet, create it.

6. Add the Server to Claude Desktop

Add the following entry to claude_desktop_config.json:

{
  "mcpServers": {
    "m365-attachment-reader-local": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\path\\to\\Claude-MCP-Read-Email-Attachments\\server.mjs"
      ],
      "env": {
        "M365_CLIENT_ID": "your-client-id",
        "M365_TENANT_ID": "common",
        "M365_AUTO_OPEN_BROWSER": "true"
      }
    }
  }
}

Tips:

  • Use the full absolute path from Step 4 for command.

  • Replace args[0] with the actual path to server.mjs on your machine.

  • If you already have other MCP servers in the config, merge this entry into the existing mcpServers object — do not overwrite the whole file.

7. Restart Claude Desktop

Completely quit Claude Desktop and reopen it. Claude Desktop starts the MCP server automatically — you do not need to run node server.mjs manually.

8. Authenticate with Microsoft 365

In Claude Desktop, type:

Please call begin_auth

A browser window will open (or you'll receive a login URL + device code). Complete the Microsoft login flow, then verify:

Please call auth_status

You should see your Microsoft account listed as authenticated.

9. Verify It Works

Run a quick health check:

Please call health_check

Then try a real request:

Show me my recent Outlook emails with attachments
Summarize the contents of the attachments from the latest email

Suggested Claude Prompts

Please call begin_auth
Please call auth_status
Show me my recent Outlook emails with attachments
Summarize the contents of the attachments from the email
Find the latest invoice email and extract the total amount, due date, and line items from the PDF attachment
Attach ~/Desktop/Daily Dash.pptx and save a draft to my manager — I'll send it from Outlook

Sending Email with Local Attachments

The send_outlook_email tool composes an outgoing Outlook message with one or more local files attached and either saves it as a draft (default) or sends it.

Parameter

Type

Default

Description

to

string | string[]

— (required)

Recipient(s). A comma/semicolon-separated string or an array.

cc, bcc

string | string[]

—

Optional additional recipients.

subject

string

""

Email subject.

body

string

""

Email body.

bodyType

"Text" | "HTML"

"Text"

Body content type.

attachments

string[]

[]

Local file paths to attach (e.g. a .pptx).

send_now

boolean

false

false saves a draft for review; true sends immediately.

save_to_sent

boolean

true

When sending, also save to Sent Items.

mailbox

string

"me"

Mailbox to act as (defaults to the signed-in user).

Behavior

  • Draft (default): creates the message via POST /me/messages and returns the draft's webLink so you can open, review, and send it in Outlook.

  • Send now (send_now: true): sends via POST /me/sendMail in a single call.

  • Size guard: each file must be under 3 MB and the total stays within M365_SEND_MAX_BYTES. Oversize files are rejected with a clear message (large-attachment upload sessions are not enabled in this build).

  • Path access: by default any readable path is allowed. Set M365_SEND_ALLOWED_DIRS to restrict reads to specific folders.

Troubleshooting

Problem

Solution

Claude cannot find MCP tools

Restart Claude Desktop completely. Check that command and args paths in the config are correct and absolute.

invalid_grant error with empty userCode in logs

Almost always a token-version or account-type mismatch on the Entra app. See the next two rows.

AADSTS50059: No tenant-identifying information found

Your app does not support the common endpoint. Open the Entra app → Authentication → set Supported account types to Accounts in any organizational directory and personal Microsoft accounts, then save.

Property api.requestedAccessTokenVersion is invalid when saving account types

Open the Entra app → Manifest → set requestedAccessTokenVersion to 2 → save. Then retry changing the account type.

Device code not showing

Make sure begin_auth was called successfully. Do not manually enter a code.

Want to switch Microsoft accounts

Restart Claude Desktop and call begin_auth again in a private browser window.

send_outlook_email fails with a permissions/ErrorAccessDenied error

Your login predates the send scopes. Add Mail.ReadWrite + Mail.Send to the Entra app, grant consent, restart Claude Desktop, and run begin_auth again to re-consent.

"Attachment … exceeds the 3.00 MB per-file limit"

This build only inlines attachments under 3 MB. Compress the file or split the deck; large-attachment upload sessions are not enabled.

"File is outside the allowed send directories"

The file is not under M365_SEND_ALLOWED_DIRS. Move the file into an allowed folder or update that env var (leave it blank to allow any path).

Debug log location

<M365_MCP_DATA_DIR>\debug.log — defaults to a subdirectory auto-created next to server.mjs.

Manual Development Run

For debugging outside Claude Desktop, start the server manually:

cd Claude-MCP-Read-Email-Attachments
node .\server.mjs

Note: Do not type into that terminal. It is a stdio MCP process and expects an MCP client on standard input/output.

Docker

A Dockerfile is included for containerized testing:

docker build -t m365-attachment-reader-mcp-local .
docker run --rm -i `
  -e M365_CLIENT_ID=your-client-id `
  -e M365_TENANT_ID=common `
  -e M365_AUTO_OPEN_BROWSER=false `
  m365-attachment-reader-mcp-local

The container still runs as a stdio server. For everyday Claude Desktop use, the direct node approach in Step 6 is simpler.

Project Structure

Claude-MCP-Read-Email-Attachments/
├── server.mjs
├── package.json
├── manifest.json
├── server.json
├── glama.json
├── Dockerfile
├── .env.example
├── .gitignore
├── LICENSE
└── README.md

Limitations

  • Single-user only — one server instance supports one Microsoft account at a time

  • Auth persists across restarts — the MSAL token cache (incl. refresh token) is written to msal-cache.json in the data dir (gitignored); after one begin_auth the server silently refreshes tokens. You only re-authenticate if the refresh token expires (~90 days) or is revoked

  • You must create your own Entra app and supply your own client ID

  • Very large images may be downscaled or skipped to stay within Claude Desktop payload limits

  • Legacy .xls parsing is best-effort and less reliable than .xlsx

  • Outbound attachments are capped at ~3 MB each — send_outlook_email inlines files in a single Graph request; large files (which need chunked upload sessions) are rejected

  • Not suitable for public or multi-user hosting

License

MIT

Available Tools

6 tools
auth_statusMicrosoft 365 Auth StatusA

Check whether Microsoft 365 login for this local MCP process has completed.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior2/5

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

No annotations provided; description only states 'check whether login has completed' without disclosing what 'completed' means, return format, or side effects.

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?

Single 10-word sentence, front-loaded with verb and resource, no wasted words.

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?

Minimal for a simple tool; lacks explanation of what 'completed' means or what the output looks like. Without output schema, more detail would help.

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

Parameters4/5

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

No parameters in schema; description adds context about 'local MCP process', which is useful. Baseline 4 for 0 params.

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?

Clearly states the verb 'Check whether' and the resource 'Microsoft 365 login for this local MCP process'. Distinguishes from siblings like begin_auth and health_check.

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?

Implies usage after beginning auth or to check login state, but no explicit when-to-use or when-not-to-use compared to alternatives.

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

begin_authBegin Microsoft 365 AuthA

Start Microsoft 365 device-code login for the local Claude Desktop MCP process.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden. It only says 'start' without explaining the device-code flow, user interaction required, or what the tool returns. This lacks transparency about the process and side effects.

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, concise sentence that directly states purpose without unnecessary words. It is front-loaded and efficient.

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?

Given the tool's complexity (initiating an authentication flow), the description is insufficient. It omits expected return values, required user action (e.g., entering device code), and how to proceed after the call. An output schema or more descriptive text would improve completeness.

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

Parameters4/5

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

The input schema has zero parameters (100% coverage by schema). For zero-parameter tools, the baseline is 4. The description adds no param-level details, but no details are needed.

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 'Start Microsoft 365 device-code login for the local Claude Desktop MCP process.' It uses a specific verb ('Start') and resource ('Microsoft 365 device-code login'), and distinguishes itself from siblings like 'auth_status' which likely checks authentication state.

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 indicates the tool's function (initiate device-code login) but provides no explicit guidance on when to use it versus alternatives like 'auth_status'. It does not mention prerequisites or 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.

health_checkHealth CheckA

Verify that the local Outlook attachment reader MCP server is running and report auth state.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

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

No annotations provided, but description clearly conveys two behaviors: verifying server running and reporting auth state. Adequate for a simple tool.

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?

Single sentence, front-loaded with key info, no wasted 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?

Simple tool with no parameters or output schema; description covers essential purpose and behavior, though response format is unspecified.

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

Parameters4/5

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

No parameters, schema coverage 100%, baseline score of 4 applies; description adds no parameter info but none needed.

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?

Clearly states the tool verifies server running and reports auth state, with specific verb 'verify' and resource 'server and auth state'. Distinguishes from siblings like auth_status.

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?

Implied usage as a health check before other operations, but no explicit when-not or alternatives guidance.

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

list_email_attachmentsList Email AttachmentsC

List attachments for a specific Outlook email.

ParametersJSON Schema
NameRequiredDescriptionDefault
messageIdYes
mailboxNome

TDQS

C2.7/5.0
Behavior2/5

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

No annotations provided, and the description does not disclose behavioral traits such as pagination, limits, or whether it returns metadata vs. content. The agent has no insight into side effects or safety.

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

Conciseness3/5

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

The description is concise (one sentence) but lacks structure. It is too minimal, omitting critical information that could be front-loaded.

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?

Given the absence of annotations, output schema, and parameter descriptions, the single sentence is insufficient. More context about usage and return value is necessary.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not explain what the messageId parameter represents or the significance of the mailbox parameter (default 'me'). Elaboration on these is needed for correct usage.

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 ('List') and resource ('attachments for a specific Outlook email'). It distinguishes from sibling tools like list_recent_messages (lists emails) and read_email_attachment (reads 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 on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing a messageId from list_recent_messages) or when to use read_email_attachment instead.

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

list_recent_messagesList Recent Outlook MessagesB

List recent Outlook emails from Microsoft 365. By default this searches the Inbox, prefers emails with attachments, and can filter by subject or sender name/address.

ParametersJSON Schema
NameRequiredDescriptionDefault
mailboxNome
folderNoinbox
topNo
onlyWithAttachmentsNo
subjectContainsNo
fromContainsNo

TDQS

B3.4/5.0
Behavior3/5

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

Without annotations, description carries full burden. It discloses default search location and preference for attachments, but omits auth needs, rate limits, pagination, and behavior of 'recent'.

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?

Single sentence, no redundant words. Clear structure, though 'prefers' is slightly ambiguous.

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?

Covers core functionality but lacks details on return format, error handling, and auth. Given 6 params and no output schema, more context is warranted.

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, description adds meaning for most parameters (onlyWithAttachments, subjectContains, fromContains, folder, mailbox) but omits 'top' and uses vague 'prefers'.

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?

Clearly states it lists recent Outlook emails, specifies scope (Inbox default), and mentions filtering by subject and sender. Distinct from sibling attachment tools.

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 versus alternatives like list_email_attachments or read_email_attachment. Does not state 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_email_attachmentRead Email AttachmentA

Download an Outlook attachment directly from Microsoft Graph and parse it locally. Supports PDF, OCR-scanned PDF, Word, PowerPoint, Excel, images, archives, MSG, and plain text. Large image previews are automatically downscaled to fit MCP payload limits.

ParametersJSON Schema
NameRequiredDescriptionDefault
messageIdYes
attachmentIdYes
mailboxNome

TDQS

A3.7/5.0
Behavior4/5

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

With no annotations, the description carries full burden. It discloses supported file formats and automatic downscaling of large image previews, which are important behavioral traits. However, it omits details like auth requirements 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?

Two sentences, no extraneous words. The first sentence states the core purpose, the second adds key details (formats, size handling). Very efficient and front-loaded.

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?

No output schema is provided, so the agent must infer the return format. The description does not explain what the tool returns (e.g., binary data, base64, parsed text) or how the IDs are used. Incomplete for a tool with no annotations and no output schema.

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 input schema has three parameters with no descriptions. The description does not explain what messageId, attachmentId, or mailbox represent or how to obtain them, leaving the agent without guidance despite the schema having 0% coverage.

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 and parse) and resource (Outlook attachment). It differentiates from sibling tools like list_email_attachments and list_recent_messages by specifying it downloads and parses a single attachment's content.

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 usage for reading attachment content after listing attachments, but does not explicitly state when to use or when not to, nor does it mention alternatives or prerequisites.

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.

  1. 6 tool updatesv0.1.0
    • First observedauth_status
    • First observedbegin_auth
    • First observedhealth_check
    • First observedlist_email_attachments
    • First observedlist_recent_messages
    • First observedread_email_attachment
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0

Scored across 6 tools

Disambiguation4/5

Tools are mostly distinct: auth_status and begin_auth handle authentication, health_check monitors server, list_recent_messages finds emails, list_email_attachments shows attachments for a specific email, and read_email_attachment downloads/parses attachments. However, list_recent_messages and list_email_attachments could be confused if descriptions are glossed over, as both relate to emails and attachments.

Naming Consistency3/5

Naming patterns are mixed: some tools start with verbs (begin_auth, list_recent_messages, list_email_attachments, read_email_attachment) while others are nouns (auth_status, health_check). The verb+noun pattern is not consistently applied, reducing predictability.

Tool Count5/5

With 6 tools, the server is well-scoped for its purpose. It covers authentication (begin_auth, auth_status), server health (health_check), email discovery (list_recent_messages), attachment listing (list_email_attachments), and attachment reading (read_email_attachment). No extraneous tools.

Completeness4/5

The tool surface covers the core workflow: authenticate, find emails with attachments, list attachments, and read them. Minor gaps include lack of tools for getting email metadata beyond attachments or searching other folders, but these are acceptable for an attachment-focused server.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Outlook MCP Python

    cycle-sync-ai
    F
    license
    Not graded
    quality
    D
    maintenance
    A Python-based MCP server for Microsoft Outlook integration using Microsoft Graph API, enabling email reading/sending, calendar management, and contact operations through Claude Desktop.
    1
    -

  • outlook-mcp

    hamzashahbaz
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that enables Claude to manage Outlook emails, including reading, sending, organizing, drafting, and bulk operations via Microsoft Graph API.
    15
    1
    MIT

  • hotmail-mcp

    oshann
    A
    license
    A
    quality
    C
    maintenance
    A local MCP server that connects Claude Desktop to a personal Hotmail/Outlook.com mailbox via Microsoft Graph API, enabling email management, rule handling, and composing messages.
    25
    MIT

Appeared in Searches