outlook-mcp
# outlook-mcp
A Model Context Protocol (MCP) server for sending and managing Microsoft Outlook email via the Microsoft Graph API.
## Features
- **Send email** — To, CC, BCC, plain text or HTML body, file attachments (max 3 MB each)
- **Save draft** — Save a message to Drafts without sending
- **Update draft** — Partially edit a saved Draft (only supplied fields change)
- **Send draft** — Transmit a saved Draft to its recipients
- **List mail folders** — Discover all folders including custom ones
- **List messages** — Browse any folder with full-text search or OData filter
- **Get message** — Read full message body (plain text or HTML) + attachment metadata
- **Reply / Forward** — Reply to or forward an existing message
- **Mark message** — Mark as read or unread
- **Delete message** — Move to Deleted Items (recoverable)
- **List contact folders** — Browse personal contact lists (folders) and their contacts
- **List contacts** — Search personal Outlook address book
- **List M365 Group members** — Find everyone in a Microsoft 365 Group
- **List distribution groups** — Find mail-enabled distribution lists in the organisation
- **List users** — Search or browse Azure AD users across the organisation
## Authentication
Uses OAuth 2.0 **Device Code Flow** — no browser redirect required. Tokens are stored locally at `.access-token.txt` and refreshed automatically.
```
auth_start → visit the URL, enter the code → auth_poll
```
> **Note:** `auth_start` should only be called when another tool returns an authentication error. Do not call it proactively — all tools load the stored token automatically.
## Setup
### 1. Install dependencies and build
```bash
npm install
npm run build
```
### 2. Register in Claude Code
Add to your project's `.mcp.json`:
```json
{
"mcpServers": {
"outlook": {
"type": "stdio",
"command": "node",
"args": ["C:\\Users\\staff\\Documents\\mcp\\outlook-mcp\\build\\index.js"]
}
}
}
```
### 3. Authenticate
Call `auth_start` once, follow the instructions, then call `auth_poll` to complete login.
## Tools
### Authentication
| Tool | Description |
|------|-------------|
| `auth_start` | Start the Microsoft authentication flow |
| `auth_poll` | Complete authentication after signing in |
### Sending & Drafts
| Tool | Description |
|------|-------------|
| `send_email` | Send an email immediately |
| `save_draft` | Save an email as a draft |
| `update_draft` | Partially edit a saved draft (only supplied fields change) |
| `send_draft` | Send a previously saved draft by its ID |
### Reading Mail
| Tool | Description |
|------|-------------|
| `list_mail_folders` | List all mail folders including custom ones |
| `list_messages` | List messages from any folder; supports search and filter |
| `get_message` | Read full message content (body + attachment metadata) |
### Mail Actions
| Tool | Description |
|------|-------------|
| `reply_message` | Reply to a message (thread history preserved) |
| `forward_message` | Forward a message to new recipients |
| `mark_message` | Mark a message as read or unread |
| `delete_message` | Move a message to Deleted Items |
### Address Book & Directory
| Tool | Description |
|------|-------------|
| `list_contact_folders` | List personal contact folders; pass `folderId` to list contacts inside |
| `list_contacts` | List personal Outlook contacts (supports search) |
| `list_group_members` | List members of a Microsoft 365 Group |
| `list_distribution_groups` | List mail-enabled distribution groups in the org |
| `list_users` | Search or list Azure AD users in the organisation |
## send_email / save_draft Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | `string[]` | ✅ | Recipient email addresses |
| `subject` | `string` | ✅ | Email subject |
| `body` | `string` | ✅ | Email body content |
| `cc` | `string[]` | — | CC recipients |
| `bcc` | `string[]` | — | BCC recipients |
| `contentType` | `"text" \| "html"` | — | Body format (default: `"text"`) |
| `attachments` | `string[]` | — | Local file paths to attach (max 3 MB each) |
## Scopes
This MCP requests the following Microsoft Graph permissions:
- `Mail.Send` — Send email
- `Mail.ReadWrite` — Save drafts
- `Group.Read.All` — List group members and distribution groups
- `GroupMember.Read.All` — Read group membership
- `Directory.Read.All` — Browse the directory
- `Contacts.Read` — Read personal contacts
- `User.Read.All` — Search/list organisation users
- `offline_access` — Keep the session alive with a refresh token
## Token Storage
Tokens are stored at `outlook-mcp/.access-token.txt` (excluded from git via `.gitignore`).
## Attachment Limits
Attachments are encoded inline (base64). Files larger than **3 MB** are rejected with a clear error before any API call is made. For larger files, share a link instead.
TDQS
Scored across 22 tools
Each tool targets a fairly distinct resource+action, and the message/draft suffix pattern clearly separates immediate-send operations (reply_message, forward_message) from draft-creating ones (reply_draft, forward_draft). The closest overlaps are reply_message vs reply_all_message and send_email vs send_draft, but descriptions make the intent clear enough that misselection risk is low.
Nearly all tools follow a clean verb_noun snake_case convention (list_messages, get_message, send_draft, delete_message), which is very predictable. The only deviations are the two auth tools (auth_start, auth_poll) that use noun_verb order, a minor inconsistency in an otherwise uniform set.
22 tools is on the heavy side for a mailbox client, with a large cluster of near-sibling reply/forward variants (immediate vs draft, single vs all) that multiply the surface. Each tool does earn a place in the draft workflow, so it is defensible but not tightly scoped.
Core mail lifecycle is well covered: list/read, send, reply, reply-all, forward, draft create/update/send, delete, mark read/unread, plus folder, contact, and user lookup for addressing. Notable gaps remain — attachments are metadata-only (no download of file content), no move/copy between folders, and no folder creation — but agents can work around these for most tasks.