setonc/outlook-mcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
outlook-mcp/README.md

349 lines
No EOL
18 KiB
Markdown
Raw Permalink Blame History

# Outlook MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes Microsoft Outlook email, calendar, folders, and inbox rules through the Microsoft Graph API.
Built for use with AI agents (Claude, Hermes, etc.) that support the MCP standard — gives your assistant the ability to read, search, and send email, manage calendar events, organize folders, and automate inbox rules.
## Features
- **Email**: List, search, read, send, and reconstruct full conversation threads with quoted-reply stripping and signature deduplication
- **Shared mailboxes**: Optional `mailbox` parameter on email/folder tools; `list-mailboxes` probes seeded candidates (Graph cannot enumerate all rights)
- **Calendar**: List, create, decline, cancel, and delete events
- **Folders**: List (flat or hierarchical), create, and move emails between folders
- **Inbox Rules**: List, create, and reorder execution priority of inbox rules
- **Authentication**: MSAL device code flow with persistent token cache — no browser redirect needed
- **Test Mode**: Mock data layer for development without a real Microsoft account
## Quick Start
### Prerequisites
- Node.js ≥ 14
- A Microsoft Azure App Registration (see [Azure Setup](#azure-app-registration) below)
### Install
```bash
git clone <repo-url> outlook-mcp
cd outlook-mcp
npm install
```
### Configure
```bash
cp .env.example .env
# Edit .env and set MS_CLIENT_ID
```
### Run
```bash
npm start
```
The server communicates over stdio (standard MCP transport). Your MCP client (Claude Desktop, Hermes, etc.) launches it as a subprocess.
### Authenticate
When you first use the server, call the `authenticate` tool. It will return a URL and a short code:
```
1. Open: https://microsoft.com/devicelogin
2. Enter code: ABC123XYZ
You have 15 minutes to complete sign-in.
```
Visit the URL on any device, enter the code, and sign in with your Microsoft account. Tokens are cached to disk (`~/.outlook-mcp-tokens.json`) and silently refreshed by MSAL — you won't need to re-authenticate until the refresh token expires.
To check auth status without side effects, use `check-auth-status` (not `authenticate`).
## Azure App Registration
This server uses MSAL **device code flow** with a **public client** app registration.
1. Go to [Azure Portal → App Registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) → **New registration**
2. Name it (e.g. "Outlook MCP")
3. Supported account types: **Accounts in any organizational directory and personal Microsoft accounts** (multi-tenant)
4. Redirect URI: leave blank (device code flow doesn't need one)
5. After creation, go to **Authentication** → scroll to **Advanced settings** → enable **Allow public client flows**
6. Go to **API permissions** → add **Delegated** Microsoft Graph permissions:
- `Mail.Read`
- `Mail.ReadWrite`
- `Mail.Send`
- `Mail.Read.Shared` (shared/delegated mailboxes — work/school only)
- `Mail.ReadWrite.Shared`
- `Mail.Send.Shared`
- `User.Read`
- `Calendars.Read`
- `Calendars.ReadWrite`
- `MailboxSettings.ReadWrite`
- `offline_access`
7. **Grant admin consent** for the tenant (required for `*.Shared` in most orgs)
8. Copy the **Application (client) ID** — that's your `MS_CLIENT_ID`
No client secret is needed for public client apps.
After adding shared scopes to an existing deployment, users must **re-run device-code authenticate** so the access token's `scp` claim includes the new permissions. `check-auth-status` reports missing shared scopes.
## Configuration
All configuration is via environment variables:
| Variable | Required | Default | Description |
|---|---|---|---|
| `MS_CLIENT_ID` | Yes | — | Azure app registration client ID |
| `MS_CLIENT_SECRET` | No | — | Only for confidential client apps; leave blank for public client |
| `USE_TEST_MODE` | No | `false` | Use mock data instead of real API calls |
| `DEBUG_MODE` | No | `false` | Verbose logging (MSAL, API calls, working directory) |
| `OUTLOOK_TOKEN_STORE_PATH` | No | `~/.outlook-mcp-tokens.json` | Token cache file path (override for multi-instance setups) |
| `MS_TIMEZONE` | No | `America/New_York` | Default timezone for calendar/event display and date filters (IANA or Windows name) |
| `OUTLOOK_ENABLE_SHARED_MAILBOXES` | No | `true` | When `false`, omit shared scopes and hide `list-mailboxes` |
| `OUTLOOK_SHARED_MAILBOXES` | No | empty | Comma-separated seed list of shared mailbox UPNs/SMTPs to probe |
| `OUTLOOK_MAILBOX_CACHE_PATH` | No | `${tokenStore}.mailboxes.json` | Probe result cache path |
| `OUTLOOK_MAILBOX_PROBE_CONCURRENCY` | No | `4` | Parallel probes in `list-mailboxes` |
| `OUTLOOK_MAX_RETRIES` | No | `3` | Graph 429/503 retry count |
| `OUTLOOK_BASE_RETRY_DELAY_MS` | No | `1000` | Initial backoff delay |
| `OUTLOOK_MAX_RETRY_DELAY_MS` | No | `30000` | Backoff ceiling |
## Shared mailboxes
Microsoft Graph **does not** expose an API that lists every mailbox the signed-in user can access. This server supports shared/delegated mailboxes by:
1. **Targeting** — pass `mailbox: "shared@contoso.com"` on list/search/read/send/folder/thread tools. Calls use `users/{upn}/...` instead of `me/...`, plus an `X-AnchorMailbox` header.
2. **Discovery** — `list-mailboxes` merges primary + `OUTLOOK_SHARED_MAILBOXES` + local cache + optional `candidates[]`, then probes read/folder access. `sendAs` stays `unverified` until a successful send.
3. **Exchange rights** — Graph scopes are not enough. The user still needs Full Access / Send As / Send on Behalf on the mailbox in Exchange Online.
4. **Send** — default when `mailbox` is set: `POST /users/{mailbox}/sendMail`. Set `onBehalfOf: true` to use `me/sendMail` with `from` set to the shared address.
Message IDs are **mailbox-scoped**. Always pass the same `mailbox` value on follow-up read/thread calls.
Optional EXO admin seed (outside this MCP):
```powershell
Get-EXOMailbox -RecipientTypeDetails SharedMailbox -ResultSize Unlimited |
ForEach-Object {
Get-EXOMailboxPermission -Identity $_.Identity -User $user -ErrorAction SilentlyContinue
}
```
Pipe known addresses into `OUTLOOK_SHARED_MAILBOXES`.
## MCP Client Configuration
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"outlook": {
"command": "node",
"args": ["/path/to/outlook-mcp/index.js"],
"env": {
"MS_CLIENT_ID": "your-client-id-here"
}
}
}
}
```
### Hermes Agent
Add to `config.yaml` under `mcp_servers`:
```yaml
mcp_servers:
outlook-mcp:
command: node
args:
- /path/to/outlook-mcp/index.js
env:
MS_CLIENT_ID: your-client-id-here
```
### Multi-Account (Multiple Instances)
The server is single-account by design — `getCachedAccount()` always returns the first cached account. To use multiple accounts (e.g. work + personal), run separate instances with isolated token caches:
```yaml
mcp_servers:
outlook-mcp-work:
command: node
args: [/path/to/outlook-mcp/index.js]
env:
MS_CLIENT_ID: your-client-id
outlook-mcp-personal:
command: node
args: [/path/to/outlook-mcp/index.js]
env:
MS_CLIENT_ID: your-client-id
OUTLOOK_TOKEN_STORE_PATH: /path/to/.outlook-mcp-tokens-personal.json
```
Each instance gets its own MSAL cache — no account-selection conflicts.
## Tools Reference
The server exposes **22 tools** across six categories (21 when `OUTLOOK_ENABLE_SHARED_MAILBOXES=false`).
### Authentication (3 tools)
| Tool | Description |
|---|---|
| `about` | Returns server name and version |
| `authenticate` | Starts MSAL device code flow — returns a URL and code for the user to complete sign-in |
| `check-auth-status` | Checks if a valid cached token exists (no side effects) |
### Email (6 tools)
| Tool | Key Parameters | Description |
|---|---|---|
| `list-emails` | `folder`, `count`, `dateFrom`, `dateTo`, `dateRange`, `mailbox` | Lists emails from a folder with date filtering. Results include `conversationId`. Pass `mailbox` to target a shared mailbox. |
| `search-emails` | `query`, `from`, `to`, `subject`, `hasAttachments`, `unreadOnly`, `count`, `strict`, `mailbox` | Progressive search with KQL fallback strategies. Results include `conversationId`. Pass `mailbox` for shared mailbox search. Use `strict: true` to disable fallback to recent emails. |
| `read-email` | `id`, `mailbox` | Reads a single email with full body (auto-cleaned HTML → text). Pass the same `mailbox` used when listing/searching. |
| `read-emails` | `ids` (max 10), `mailbox` | Reads multiple emails concurrently |
| `send-email` | `to`, `cc`, `bcc`, `subject`, `body`, `importance`, `saveToSentItems`, `mailbox`, `from`, `onBehalfOf` | Sends an email (plain text or HTML). When `mailbox` is set, sends as that shared mailbox via `users/{mailbox}/sendMail` (requires Send As + `Mail.Send.Shared`). Set `onBehalfOf: true` for Send on Behalf via `me/sendMail` with `from` set. |
| `get-email-thread` | `conversationId` (preferred) or `ids` (max 20), `mailbox` | Fetches a complete conversation across all folders (inbox + sent), strips quoted replies, deduplicates signatures per sender. Pass `mailbox` when the conversation is in a shared mailbox. |
**Date filtering** supports both ISO dates (`2024-06-15`) and relative ranges (`today`, `yesterday`, `last7days`, `last30days`, `thisweek`, `lastweek`, `thismonth`, `lastmonth`).
**Search strategy**: The server uses a progressive fallback approach because Graph API doesn't allow `$search` with `$orderby` or `$filter`. It tries: (1) combined KQL search with client-side boolean filtering, (2) individual term searches, (3) boolean-filter-only with `$filter` + `$orderby`, (4) fallback to recent emails.
### Calendar (6 tools)
| Tool | Key Parameters | Description |
|---|---|---|
| `list-events` | `count`, `startDate`, `endDate` | Lists events in a date range (defaults to upcoming from now) |
| `create-event` | `subject`, `start`, `end`, `attendees`, `body` | Creates a calendar event (times in ISO 8601, timezone configurable via `MS_TIMEZONE`) |
| `accept-event` | `eventId`, `comment` | Accepts a meeting invitation |
| `decline-event` | `eventId`, `comment` | Declines a meeting invitation |
| `cancel-event` | `eventId`, `comment` | Cancels an event you organized |
| `delete-event` | `eventId` | Deletes an event from your calendar |
### Folders (3 tools)
| Tool | Key Parameters | Description |
|---|---|---|
| `list-folders` | `includeItemCounts`, `includeChildren`, `mailbox` | Lists mail folders (flat list or hierarchical tree). Pass `mailbox` for a shared mailbox's folders. |
| `create-folder` | `name`, `parentFolder`, `mailbox` | Creates a new mail folder (optionally nested under a parent). There is no delete-folder tool — avoid test folders on shared mailboxes. |
| `move-emails` | `emailIds`, `targetFolder`, `sourceFolder`, `mailbox` | Moves emails to a target folder by name within the same mailbox |
### Inbox Rules (3 tools)
| Tool | Key Parameters | Description |
|---|---|---|
| `list-rules` | `includeDetails` | Lists inbox rules sorted by execution order (sequence number) |
| `create-rule` | `name`, `fromAddresses`, `containsSubject`, `hasAttachments`, `moveToFolder`, `markAsRead`, `isEnabled`, `sequence` | Creates a new inbox rule |
| `edit-rule-sequence` | `ruleName`, `sequence` | Changes the execution order of an existing rule |
### Mailbox (1 tool, hidden when `OUTLOOK_ENABLE_SHARED_MAILBOXES=false`)
| Tool | Key Parameters | Description |
|---|---|---|
| `list-mailboxes` | `candidates` | Probes primary mailbox + `OUTLOOK_SHARED_MAILBOXES` seeds + local cache + optional `candidates[]` for read/folder access. Reports `sendAs` as `unverified` until a successful send. Graph cannot enumerate all mailboxes the user has rights to. |
## Architecture
```
index.js # Main entry point — MCP server, tool registration, request routing
config.js # Server config, Graph API endpoints, field selections, pagination limits
.env.example # Template for environment variables
auth/
index.js # ensureAuthenticated() — the gatekeeper all tools call
token-manager.js # MSAL PublicClientApplication, device code flow, persistent cache plugin
tools.js # authenticate, check-auth-status, about tool handlers
email/
index.js # Tool definitions (schemas) for email tools
list.js # list-emails handler
search.js # search-emails handler with progressive KQL fallback
read.js # read-email handler
read-multiple.js # read-emails handler (concurrent fetch)
send.js # send-email handler
folder-utils.js # resolveFolderPath(), getFolderIdByName(), getAllFolders() — shared utilities
calendar/
index.js # Tool definitions for calendar tools
list.js # list-events handler
create.js # create-event handler
decline.js # decline-event handler
cancel.js # cancel-event handler
delete.js # delete-event handler
accept.js # accept-event handler
folder/
index.js # Tool definitions for folder tools
list.js # list-folders handler (flat + hierarchical formatting)
create.js # create-folder handler
move.js # move-emails handler
mailbox/
index.js # Tool definition for list-mailboxes
list.js # list-mailboxes handler — probes primary, seeds, cache, candidates
rules/
index.js # Tool definitions for rules tools + edit-rule-sequence handler
list.js # list-rules handler + getInboxRules() utility
create.js # create-rule handler
tools/
get-email-thread.js # get-email-thread tool — conversationId-based thread fetcher
utils/
graph-api.js # callGraphAPI() — HTTPS client for Microsoft Graph (429/503 retry/backoff)
mailbox.js # normalizeMailbox(), buildPath(), withMailboxHeaders() — shared mailbox routing
bodyParser.js # HTML → text conversion, boilerplate/banner/legal block stripping, signature handling
threadBuilder.js # Quote-boundary detection, unique-content extraction, chronological thread formatting
time-formatter.js # Timezone-aware timestamp formatting for email/calendar display
timezone-mapper.js # Maps Windows timezone names to IANA for Intl-based date operations
odata-helpers.js # OData filter building, date parsing, relative date ranges
mock-data.js # Test mode mock responses
```
### Key Design Decisions
**Token persistence**: MSAL's cache plugin serializes/deserializes the token cache to disk on every access, so tokens survive process restarts. The cache file is plain JSON but contains MSAL's internal format — don't edit it manually.
**Body cleaning**: All email bodies pass through `bodyParser.cleanBody()` which: (1) converts HTML to text, (2) decodes HTML entities, (3) strips external-email caution banners, (4) strips legal boilerplate (DISCLAIMER / CONFIDENTIALITY NOTICE blocks), (5) optionally strips signature blocks (Outlook `id="Signature"` divs or text delimiters).
**Thread reconstruction**: `get-email-thread` fetches all messages matching a `conversationId` across all folders (inbox + sent items), sorts chronologically in memory (because `$filter` + `$orderby` on `conversationId` causes a Graph API 400), strips quoted replies using pattern matching (Outlook-style "From:/Sent:" headers, Gmail-style "On [date] [name] wrote:", `>`-prefixed lines, forwarded message blocks), and deduplicates signatures per sender (first occurrence keeps signature, repeats strip it).
**Progressive search**: Graph API doesn't allow `$search` with `$orderby` or `$filter`. The search handler tries multiple strategies in order and applies boolean filters (unread, attachments) client-side when needed.
**No external HTTP framework**: `graph-api.js` uses Node's native `https` module directly — no axios, no node-fetch, no dependencies beyond MSAL and the MCP SDK.
## Development
### Test Mode
```bash
npm run test-mode
```
Sets `USE_TEST_MODE=true` — the server returns mock data for all API calls instead of hitting Graph API. Useful for testing tool schemas and response formatting without a real Microsoft account.
### MCP Inspector
```bash
npm run inspect
```
Launches the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) — a web UI for interactively testing MCP tools.
## Security Notes
- **Token cache**: The `.outlook-mcp-tokens.json` file contains access and refresh tokens. It's in `.gitignore` by default. Protect it like a password.
- **No client secret in code**: For public client apps, no secret is needed. If you use a confidential client app, set `MS_CLIENT_SECRET` in the environment (not in the code).
- **Scopes are conditional**: The OAuth scopes are defined in `config.js`. When `OUTLOOK_ENABLE_SHARED_MAILBOXES` is not `false`, the scope set includes `Mail.Read.Shared`, `Mail.ReadWrite.Shared`, and `Mail.Send.Shared`. Disable shared mailboxes to request a narrower scope set.
- **`.gitignore` covers**: `node_modules/`, `.env` / `.env.*`, `*.pem`, `*.key`, `*.cert`, `*.token.json`, `.outlook-mcp-tokens.json`
## Known Issues
1. **`authenticate` `force` parameter is a no-op** — The `force` parameter is declared in the tool schema but never read by the handler. Calling `authenticate(force=false)` will still start a fresh device code flow. Use `check-auth-status` to check auth state without side effects.
## License
MIT
Reference in a new issue View git blame Copy permalink