Content
# outlook-classic-mcp
A local **MCP (Model Context Protocol) server** that exposes the **classic
Outlook desktop client** — mail, folders, calendar, contacts, tasks, color
categories, mail rules, and Out-of-Office status — to any MCP-aware
agent: Claude Code, Claude Desktop, Cowork, GitHub Copilot / VS Code
agent mode, Cursor, Cline, Continue, Windsurf, and anything else that
speaks MCP.
It talks to Outlook's COM API on Windows via `pywin32`, the same path
macros and Office add-ins use. Authentication piggybacks on whatever
account Outlook is already signed into — **no Azure / Entra app
registration, no Microsoft Graph API, no OAuth tokens.**
---
## Requirements
- Windows 10 or 11
- **Outlook desktop (Classic)** — the `OUTLOOK.EXE` shipped with
Microsoft 365 / Office. The "new Outlook" (`olk.exe`) is **not**
supported (no COM surface).
- Python 3.10+ (the installer fetches Python 3.11 via `uv` if you
don't already have one).
You do **not** need to open Outlook before starting the server — the
server auto-launches Outlook on its first COM call.
---
## Install
Three paths, simplest first.
### Option 1 — Agent plugin (recommended)
The repo doubles as a **plugin marketplace**. Installing the plugin registers the MCP server *and* loads the bundled [`outlook` skill](#agent-skill) (an operational reference that teaches the agent how to drive these tools) in one step. The MCP server itself is fetched on demand by `uvx` directly from PyPI — no `git clone`, no `pip install`, no `.venv` to maintain.
The plugin format started in Claude Code and is now supported by other agents too (Cowork, Copilot, Cursor, and others that adopted the plugin/skill format) — point your agent's plugin install flow at this repo. The commands below are for Claude Code:
Install [`uv`](https://docs.astral.sh/uv/) once if you don't have it:
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Open a fresh terminal so PATH refreshes, then in any Claude Code session:
```text
/plugin marketplace add anasahmed07/Outlook-Classic-MCP
/plugin install outlook@outlook-classic-mcp
```
Restart Claude Code (`/quit`, reopen). First call has a one-time 5–15 s pause while `uvx` resolves the package; subsequent calls are instant. Confirm with `outlook_whoami`.
To update later: `/plugin marketplace update outlook-classic-mcp` then `/plugin update outlook@outlook-classic-mcp`. To pull a fresh PyPI release of the server itself: `uv cache clean outlook-classic-mcp`.
### Option 2 — From PyPI with uv (any MCP client)
Works for any MCP client. The smart client installer auto-registers the server with Claude Desktop, Claude Code, Cursor, Cline, Continue, and Windsurf; for other clients (e.g. VS Code / Copilot agent mode), add the server to their MCP config manually — see below.
```bat
uv pip install --system outlook-classic-mcp
python -m outlook_mcp.scripts.install_to_clients
```
(`uv` is Astral's Python installer — see Option 1 above for the one-line install. `--system` writes to your system Python so `python -m outlook_mcp` resolves anywhere; drop the flag if you'd rather install into an active venv.)
Package: <https://pypi.org/project/outlook-classic-mcp/>.
---
## Smart client installer
`scripts/install_to_clients.py` detects which MCP clients are
installed on your machine and shows a checkbox menu:
```
Select which clients to register outlook-mcp with:
[ ] 1. Claude Desktop C:\Users\you\AppData\Roaming\Claude\claude_desktop_config.json
[ ] 2. Claude Code (via `claude` CLI)
[ ] 3. Cursor C:\Users\you\.cursor\mcp.json
Type a number to toggle, 'a' to select all, 'n' for none,
'enter' to confirm, 'q' to quit without changes.
```
For each toggled client it deep-merges
`mcpServers.outlook = {"command": ".venv/Scripts/python.exe", "args": ["-m", "outlook_mcp"]}`
into the right config (or runs `claude mcp add` for Claude Code).
Existing files are snapshotted to `<file>.bak` first. Re-running is
idempotent — it updates the entry instead of duplicating it.
Supported clients: **Claude Desktop, Claude Code, Cursor, Cline,
Continue, Windsurf.**
### Manual config (any other MCP client)
Any client not covered by the installer just needs the standard stdio
server entry in its MCP config:
```json
{
"mcpServers": {
"outlook": {
"command": "uvx",
"args": ["--from", "outlook-classic-mcp", "outlook-mcp"]
}
}
}
```
(VS Code / Copilot agent mode names the top-level key `servers` in
`mcp.json` instead of `mcpServers`; the entry itself is the same.)
---
## Tools
31 tools across 9 categories, all prefixed `outlook_*`.
| Category | Tools |
| -------------- | ----- |
| Mail | `list_mails`, `search_mails`, `get_mail`, `send_mail`, `reply_mail`, `forward_mail`, `move_mail`, `delete_mail`, `mark_mail`, `save_attachments` |
| Folders | `list_folders`, `create_folder` |
| Calendar | `list_events`, `get_event`, `create_event`, `update_event`, `delete_event`, `respond_event` |
| Contacts | `list_contacts`, `search_contacts` (saved contacts + org directory), `get_contact`, `resolve_name` |
| Tasks | `list_tasks`, `create_task`, `complete_task` |
| Categories | `list_categories`, `set_category` |
| Rules | `list_rules`, `toggle_rule` |
| Out-of-Office | `get_out_of_office` |
| Account | `whoami` — sanity check; shows the bound mailbox |
---
## MCP Apps — interactive UI in the chat
Since v0.3.0 the server implements the [MCP Apps extension](https://modelcontextprotocol.io/extensions/apps/overview)
(SEP-1865): read tools ship a self-contained HTML view that supporting
hosts (Claude, Claude Desktop, VS Code Copilot, Goose, Postman, …)
render in a sandboxed iframe right inside the conversation — instead of
a wall of text you get a real inbox, agenda, or contact list. Hosts
without MCP Apps support are unaffected and keep getting the usual
markdown.
| View | Rendered by | What you can do in it |
| ---- | ----------- | --------------------- |
| Mail list | `list_mails`, `search_mails` | open mails in a reading pane, mark read/unread, flag, delete, filter unread, refresh |
| Mail reader | `get_mail` | full body + attachment list, mark, flag, delete |
| Calendar agenda | `list_events` | day-grouped agenda, expand an event for attendees + body, refresh |
| Contacts | `list_contacts`, `search_contacts` | live search (incl. org directory), copy addresses |
| Tasks | `list_tasks` | complete tasks, quick-add new ones, show completed, refresh |
The views are plain inline HTML/CSS/JS (no build step, no external
CDNs — the sandbox CSP blocks those anyway), follow the host's
light/dark theme, and talk back over the standard `postMessage`
JSON-RPC dialect: buttons in the UI call the same `outlook_*` tools the
model uses, and in-app actions (delete, complete, …) are reported back
into the model's context so the conversation stays in sync.
Technically: each UI tool carries `_meta.ui.resourceUri` pointing at a
`ui://outlook/*.html` resource (mime `text/html;profile=mcp-app`) and
returns markdown for the model **plus** `structuredContent` for the
app. To preview the views without an MCP host:
`python scripts/preview_ui.py`, then open
`.ui-preview/harness.html?view=mail-list` (any view name, optional
`&theme=dark`) in a browser.
---
## Agent skill
The repo also ships an agent **skill** at `skills/outlook/` (standard Agent Skills format — works in Claude Code, Cowork, Copilot, Cursor, and other agents that load skills) — a self-contained operational reference that teaches the agent how to drive the `outlook_*` tools correctly: folder reference syntax, the `EntryID` handle pattern, ISO-8601 date conventions, the `Recurrence` object, which calls have side effects to confirm before, and 19 worked recipes for common workflows (triage, drafting replies, weekly digests, scheduling meetings, recurring events, attachment handling, multi-mailbox setups).
Layout:
```
skills/outlook/
├── SKILL.md # always-loaded operational core
└── references/ # loaded on demand
├── tools.md # full per-tool parameter / return-shape reference
├── recipes.md # worked multi-step workflows
├── gotchas.md # quirks + failure modes (Programmatic Access prompt, EX:/O= addresses, live rule toggling, sandboxed paths, etc.)
└── setup.md # install instructions an agent can walk a user through when the tools aren't connected yet
```
Installing the [plugin](#option-1--agent-plugin-recommended) auto-loads this skill alongside the MCP server. For an agent that supports skills but not plugins, copy the `skills/outlook/` directory into wherever it loads skills from.
---
## Conventions
**Folder references** can be:
- A well-known name: `inbox`, `sent`, `drafts`, `deleted`, `outbox`,
`junk`, `calendar`, `contacts`, `tasks`, `notes`
- A slash path: `Inbox/Projects/Acme`
- A path qualified by store name: `Mailbox - you@example.com/Inbox/Projects/Acme`
Use `outlook_list_folders` to discover paths.
**Dates / times** are ISO-8601 strings. Inputs without a timezone are
treated as local time (what Outlook stores); returned timestamps carry
the user's local UTC offset explicitly (`2026-06-10T16:33:22+05:00`).
**Item IDs** are Outlook `EntryID` strings. Read tools return them
on every item; pass them back to detail / edit / delete tools.
**Response format** — most read tools accept `response_format`:
- `markdown` (default) — pretty rendered output
- `json` — full structured data
**Errors** are raised, so the MCP host marks the response
`isError: true`. Error messages try to suggest a corrective next step.
**Filesystem paths** for `attachments=` and `output_dir=` must be
absolute and under the user profile (default sandbox). Set
`OUTLOOK_MCP_ALLOW_ANY_PATH=1` to disable the sandbox if you legitimately
need to read or write outside `%USERPROFILE%`.
---
## Architecture
```
+-------------------+
stdio <---> | FastMCP server | <-- one per process
+---------+---------+
|
await bridge.call(...)
|
v
+-------------------+
| OutlookBridge | persistent STA thread
| - one Dispatch | single Outlook.Application
| - work queue | handle, reused by every call
+---------+---------+
|
Outlook COM (auto-launches OUTLOOK.EXE if needed)
```
The MCP event loop never blocks on COM, and COM only ever sees the
one STA thread it needs. This is faster than per-call dispatch and
the Outlook process stays warm across calls.
---
## Development
```bat
.venv\Scripts\activate
pip install -e .[dev]
pytest
```
Smoke test the running server with the MCP inspector:
```bat
npx @modelcontextprotocol/inspector .venv\Scripts\python.exe -m outlook_mcp
```
> The inspector mangles backslashes on Windows — use forward-slash
> paths if you hit "ENOENT" errors.
Publish to PyPI:
```bat
publish.bat
```
(`TWINE_USERNAME=__token__`, `TWINE_PASSWORD=<pypi-token>`.)
---
## Notes & caveats
- The first call after a cold start takes a few seconds — Outlook's
COM surface boots up. After that, calls are fast (one Dispatch
handle is reused).
- Closing Outlook while the server is running is fine: the next tool
call detects the dead COM connection, relaunches OUTLOOK.EXE,
reconnects, and retries automatically (expect that one call to take
15–30 s).
- Outlook auto-launch relies on standard COM behavior. On
tightly-locked-down machines (UAC, group policy blocking COM
activation), open Outlook manually and try again.
- Send / reply / forward / delete may trigger Outlook's "Programmatic
Access" security prompts on some corporate machines. If your IT
policy blocks programmatic send entirely, write tools will fail —
read tools still work.
- Some properties (e.g. `SenderEmailAddress` for Exchange addresses)
come back as `EX:/O=...` distinguished names rather than SMTP. Use
`from_address` substring matching instead of exact equality — or
`search_mails(scope='from')`, which also matches the real SMTP
address.
- Toggling mail rules modifies live rules immediately — there is no
staging buffer. Confirm the rule name with `outlook_list_rules`
before calling `outlook_toggle_rule`.
- This server is **local-only**. Do not expose it over a network.
---
## Troubleshooting
**"Outlook COM thread did not become ready"** — Outlook didn't
auto-launch. Open it manually, sign in, then restart the MCP client
so it re-spawns the server.
**Inspector shows ENOENT for the python path** — known Windows
quirk; use forward slashes (`C:/Users/you/...`) instead of
backslashes.
**Send / reply gets blocked silently** — Outlook → File → Options →
Trust Center → Programmatic Access. The setting that works while
you're using the server is "Never warn me about suspicious activity
(not recommended)" — or have IT add the Python interpreter as a
trusted publisher.
---
## License
MIT
