Metadata-Version: 2.4
Name: outlook-desktop-mcp
Version: 0.1.0
Summary: Run this on Windows and get Outlook Desktop as an MCP server. No Graph API, no Entra app registration — just your local Outlook.
Project-URL: Homepage, https://github.com/aaanerud/outlook-desktop-mcp
Project-URL: Repository, https://github.com/aaanerud/outlook-desktop-mcp
Project-URL: Issues, https://github.com/aaanerud/outlook-desktop-mcp/issues
Author-email: Andreas Martin Aanerud <aaanerud@microsoft.com>
Keywords: automation,claude,com,email,mcp,microsoft,outlook,windows
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Office/Business :: Office Suites
Requires-Python: >=3.12
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: pywin32>=310
Description-Content-Type: text/markdown

# outlook-desktop-mcp

Run this on Windows and get **Outlook Desktop as an MCP server**. No Microsoft Graph API, no Entra app registration, no OAuth tokens — just your local Outlook.

Uses COM automation to talk directly to your running Outlook Desktop (Classic) instance, inheriting whatever authentication you already have.

```
MCP Client (Claude Code, etc.)
    |
    | stdio (JSON-RPC)
    v
outlook-desktop-mcp (Python)
    |
    | COM automation (MSOUTL.OLB)
    v
Outlook Desktop (Classic) — OUTLOOK.EXE
    |
    | Your existing auth session
    v
Exchange Online / Microsoft 365
```

## Requirements

- **Windows** (COM automation is Windows-only)
- **Outlook Desktop (Classic)** — `OUTLOOK.EXE`, not the new `olk.exe`
- **Python 3.12+**
- Outlook must be **running** when the MCP server starts

## Install

```bash
pip install outlook-desktop-mcp
```

Or from source:

```bash
git clone https://github.com/aaanerud/outlook-desktop-mcp.git
cd outlook-desktop-mcp
python -m venv .venv
.venv\Scripts\activate
pip install pywin32 "mcp[cli]" -e .
python .venv\Scripts\pywin32_postinstall.py -install
```

## Register with Claude Code

```bash
claude mcp add outlook-desktop -- outlook-desktop-mcp
```

Or if installed from source:

```bash
claude mcp add outlook-desktop -- powershell.exe -Command "& 'C:\path\to\outlook-desktop-mcp.cmd' mcp"
```

Then in any Claude Code session, the 9 email tools are available automatically.

## Available Tools

| Tool | What it does |
|------|-------------|
| `send_email` | Send email via your default Outlook profile |
| `list_emails` | List recent emails from any folder |
| `read_email` | Read full email by ID or subject search |
| `mark_as_read` | Mark an email as read |
| `mark_as_unread` | Mark an email as unread |
| `move_email` | Move email to archive or any folder |
| `reply_email` | Reply or reply-all, preserving thread |
| `list_folders` | List folder hierarchy with item counts |
| `search_emails` | Full-text search on subject and body |

## How it works

The server runs a dedicated COM thread (STA apartment) that holds the `Outlook.Application` object. The async MCP event loop dispatches tool calls to this thread via a queue, so COM threading rules are respected and the MCP protocol never blocks.

All tool descriptions are written for LLM consumption — when Claude Code discovers the tools, it knows exactly how to use each one (what arguments to pass, what formats to expect, edge cases to watch for).

## Extending

The architecture supports adding more Outlook modules. Planned:

- **Calendar** — events, meetings, scheduling
- **Contacts** — address book lookups
- **Tasks** — to-do items

Add new `@mcp.tool()` functions in `server.py` using the same `bridge.call()` pattern.

## Why not Microsoft Graph?

Graph API requires an Entra (Azure AD) app registration, admin consent for mail permissions, OAuth token management, and tenant configuration. For a local developer tool that just wants to send and read email, that's massive overhead.

COM automation requires: Outlook is open. That's it.
