Outlook Classic MCP
by jli-software
README.md
<div align="center">
<img src="logo.svg" width="120" alt="Outlook Classic MCP logo" />
<h1>Outlook Classic MCP</h1>
<p><b>An MCP server for Microsoft Outlook — the classic desktop app for Windows.</b><br/>
Let Claude, Codex and other AI assistants read, search and organize your mailbox and calendar,<br/>
look up colleagues and write drafts for you — through the Outlook that is already signed in on your PC.</p>
[](https://github.com/jli-software/outlook-classic-mcp/releases/latest)
-89b4fa?style=flat-square)
</div>
---
```
Claude / Codex ──MCP──▶ outlook-classic-mcp.exe ──COM──▶ Outlook (classic) ──▶ your mailbox
```
## Why
- **No Azure app, no Graph API, no tokens.** It talks to your running Outlook via COM and
uses the session you are already signed in with. Nothing to register, no admin consent.
- **Works where Microsoft Graph is blocked** — e.g. by Conditional Access or token
protection policies. If Outlook works on your PC, this works.
- **Local only.** Your mail never leaves your machine except to the AI client you use.
- **Sends only if you allow it.** Out of the box everything outgoing becomes a draft you
review and send yourself — meeting invitations and replies to invitations included.
Sending is an explicit opt-in (`--allow-send`), and even then only drafts go out.
- **Audit log.** Every change the assistant makes — drafts, sends, moves, deletes,
calendar — is logged locally as one JSON line, without the message text.
- **Files stay fenced in.** Attachments can only be added from — and saved to — your user
profile and `%TEMP%`, so a crafted email can't talk the assistant into attaching
arbitrary files.
- **One small EXE.** No Python, no PowerShell, no runtime, no background service.
## Requirements
- Windows with **classic Outlook** (Outlook for Microsoft 365 / 2016 / 2019 / 2021 desktop,
the Win32 app) set up with your mailbox.
The **new Outlook** (“Outlook for Windows”, olk.exe) has no COM interface —
see [Using the new Outlook?](#using-the-new-outlook) below.
- An MCP client: Claude Desktop, Claude Code, Codex, Cursor, VS Code, …
- Run it as your normal user, **not elevated** (an admin process cannot attach to your Outlook).
## Install
In PowerShell:
```powershell
irm https://raw.githubusercontent.com/jli-software/outlook-classic-mcp/main/install.ps1 | iex
```
This downloads the latest release to `%LOCALAPPDATA%\Programs\outlook-classic-mcp`,
checks its SHA-256 and registers it as server `outlook` in **Claude Desktop**,
**Claude Code** and **Codex**. Restart your clients — done.
**Claude Desktop only:** download `outlook-classic-mcp.mcpb` from the
[latest release](https://github.com/jli-software/outlook-classic-mcp/releases/latest)
and open it — Claude Desktop installs it as an extension.
<details>
<summary>Manual install</summary>
1. Download `outlook-classic-mcp-windows-x64.exe` from the
[latest release](https://github.com/jli-software/outlook-classic-mcp/releases/latest)
and save it as `outlook-classic-mcp.exe` wherever you like.
2. Register it:
```powershell
.\outlook-classic-mcp.exe install # Claude Desktop, Claude Code, Codex
.\outlook-classic-mcp.exe install --allow-send # same, with sending enabled
.\outlook-classic-mcp.exe install --print # dry run: only show the config files
.\outlook-classic-mcp.exe install codex # only one target (desktop | code | codex)
```
Existing configs are kept; a `.outlook-classic-mcp.bak` backup is written first.
Windows SmartScreen may warn about the unsigned EXE — “More info → Run anyway”.
</details>
<details>
<summary>Other MCP clients (Cursor, VS Code, Windsurf, …)</summary>
Add a stdio server to your client's MCP config:
```json
{
"mcpServers": {
"outlook": {
"command": "C:\\Users\\you\\AppData\\Local\\Programs\\outlook-classic-mcp\\outlook-classic-mcp.exe",
"args": ["serve"]
}
}
}
```
</details>
## What you can ask
> “Summarize my unread mail from today.”
> “Find the invoice from Contoso in all folders and save the PDF.”
> “Draft a reply to Anna's last mail: Thursday works, 10am.”
> “Move all newsletters from this week to Archive and mark them read.”
> “What's Anna Smith's email and department? Draft her an invite for Friday.”
> “What's on my calendar this week? When are Anna and Beat both free on Tuesday?”
> “Move my 2pm dentist appointment to Thursday and set a reminder 1 hour before.”
## Tools
| Tool | What it does |
|---|---|
| `mail_list` | Newest emails of a folder (Inbox, Sent Items, Drafts, … or any folder) |
| `mail_search` | Search subject, sender and body — one folder or `folder: "all"` |
| `mail_read` | Full emails with body and attachment names (several at once) |
| `mail_create_draft` | New draft with To / CC / BCC |
| `mail_reply` | Reply draft with thread and quote, optionally with attachments |
| `mail_forward` | Forward draft with your text above the original (attachments included) |
| `mail_send_draft` | Send a draft — **only with `--allow-send`**, see [Sending](#sending) |
| `mail_update_draft` | Change a draft; in replies only your text is replaced, quote and signature stay |
| `mail_attachments` | List attachments |
| `mail_save_attachment` | Save attachments to disk so the assistant can read them |
| `mail_folders` | Complete folder tree with IDs and counts |
| `mail_create_folder` | Create a folder |
| `mail_move` | Move emails to a folder |
| `mail_mark_read` | Mark read / unread |
| `mail_categorize` | Set Outlook categories (color tags) |
| `mail_delete` | Move to Deleted Items (never deletes permanently) |
| `mail_sync` | Trigger Send/Receive to refresh the local cache |
| `contacts_search` | Find people in your contacts and the company directory (Global Address List) |
| `contacts_resolve` | Name → email address; lists the candidates instead of guessing when ambiguous |
| `contacts_get` | All details of a contact or directory entry (phones, department, manager, …) |
| `contacts_list` | Your own contacts |
| `outlook_whoami` | Signed-in mailbox, Outlook version, connection state and this server's settings |
| `calendar_list` | Appointments in a time range (default: the next 7 days), recurring occurrences included |
| `calendar_get` | Details: description, attendees with their responses, Teams link, reminder |
| `calendar_create` | New appointment; with attendees a meeting that is saved but **not sent** |
| `calendar_update` | Change time, subject, location, … — one occurrence or the whole series |
| `calendar_delete` | Delete appointments or single occurrences; refuses sent meetings you organize |
| `calendar_respond` | Accept / tentative / decline an invitation — the response is saved as a **draft** |
| `calendar_free_busy` | When colleagues are busy on a given day (30-minute blocks) |
Without `--allow-send` there is **no send tool** at all. In the calendar this means: a
new meeting stays unsent until you click Send in Outlook, a response to an invitation
lands in Drafts, and changing or deleting a meeting does not notify anyone — deleting a
meeting you organize whose invitations were already sent is refused, so attendees aren't
left with a ghost meeting (cancel it in Outlook instead).
Times go in and out as ISO 8601 in your local time (`2026-10-29T14:00`); a date alone
(`2026-10-29`) makes an all-day event. An offset (`+01:00`, `Z`) is converted to local time.
Email addresses always come back as SMTP addresses (`anna.smith@contoso.com`), also for
Exchange senders and directory entries — never as `/O=…/CN=…`.
### Sending
Sending is off by default. To allow it, register the server with
`install --allow-send` (or add `"--allow-send"` after `"serve"` in your client's `args`)
and restart the client. Running `install` without the flag turns it off again.
With sending on, the assistant still writes a draft first; `mail_send_draft` then sends it,
and the tool tells the assistant to do so only after you have confirmed that exact draft.
It refuses anything that is not an email or a meeting response in your **Drafts** folder,
and it sends nothing if a recipient can't be resolved. Meetings are never sent by the
server — invitations, updates and cancellations stay with you in Outlook.
Sent mail first goes to the Outbox; classic Outlook delivers it on its next sync (with
Outlook running, within seconds).
**Outlook security prompt:** Outlook may show a warning that “a program is trying to send
an email on your behalf” (the Object Model Guard). On PCs with an up-to-date, recognized
antivirus this normally doesn't appear; where it does, sending waits for your click and
times out after 90 s. Admins can control it with the Outlook policy *Programmatic Access
Security*.
### Audit log
Every action that changes something is appended as one JSON line to
`%LOCALAPPDATA%\outlook-classic-mcp\audit.log`:
```json
{"time":"2026-10-29T10:32:33+01:00","tool":"mail_send_draft","id":"00000000…","ok":true,"subject":"Offer","to":["anna.smith@contoso.com"]}
```
It records time, tool, IDs, recipients, subject and the result — never the message text.
The file rotates at 5 MB (`audit.log.1`). Set `OUTLOOK_MCP_AUDIT_LOG` in the server's
environment to another path, or to `off`. `outlook_whoami` shows where it is written.
### Attachment folders
`mail_reply` (`attachments`) and `mail_save_attachment` (`dir`) only accept paths under
your user profile (`%USERPROFILE%`) or `%TEMP%`; anything else is refused. To lift this,
set `OUTLOOK_MCP_ALLOW_ANY_PATH=1` in the server's environment, e.g.
```json
"outlook": { "command": "…\\outlook-classic-mcp.exe", "args": ["serve"],
"env": { "OUTLOOK_MCP_ALLOW_ANY_PATH": "1" } }
```
## Using the new Outlook?
You can keep working in the new Outlook. The classic Outlook only has to be installed
and should run now and then, because this server reads its local cache:
- **Best:** start classic Outlook minimized with Windows. You won't notice it, and the
cache stays fresh. Turn off its desktop notifications so you don't get every mail twice
(*File → Options → Mail → Display a Desktop Alert*).
```powershell
$s = New-Object -ComObject WScript.Shell
$sc = $s.CreateShortcut("$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\Outlook (classic).lnk")
$sc.TargetPath = (Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\OUTLOOK.EXE').'(default)'
$sc.WindowStyle = 7 # minimized
$sc.Save()
```
- **On demand:** ask the assistant to run `mail_sync` first.
If classic Outlook is closed, the server starts it invisibly and releases it again
after 5 minutes without a call.
## Troubleshooting
| Problem | Fix |
|---|---|
| `0x80080005` / “server execution failed” | Your MCP client runs elevated, or Outlook is starting. Run the client as normal user; keep Outlook open. |
| Drafts don't show up in the new Outlook | Classic Outlook hasn't synced yet — run `mail_sync` or keep classic Outlook running. |
| `folder not found` | Use `mail_folders` and pass the folder's ID or full path. Unknown folders are an error on purpose, never a silent fallback to the Inbox. |
| First `contacts_search` takes a few seconds | Outlook can't filter the company directory, so the first search reads all names (~2 ms per entry) and keeps them for 30 minutes. Later searches are instant. |
| Search over all folders takes seconds | It scans the text of every message (~5–10 s for a few thousand). Search one folder when you can. |
| A dialog in Outlook blocks | Calls time out after 90 s; close the dialog and try again. |
| `mail_send_draft` is missing | Sending is off — register with `install --allow-send` and restart the client. |
| Sent mail stays in the Outbox | Classic Outlook is offline or not running; open it or run `mail_sync`. |
## Build from source
```powershell
git clone https://github.com/jli-software/outlook-classic-mcp
cd outlook-classic-mcp
go build -o outlook-classic-mcp.exe .
go test .
```
Pure Go (no CGO), using [go-ole](https://github.com/go-ole/go-ole) for COM and
[mcp-go](https://github.com/mark3labs/mcp-go) for MCP.
## Disclaimer
This is an independent open-source project. It is not affiliated with, endorsed by or
sponsored by Microsoft. “Microsoft” and “Outlook” are trademarks of the Microsoft group
of companies.
## License
[MIT](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues