# outlook-classic-windows-mcp

MVP MCP server for working with a locally configured **classic Outlook for Windows** desktop profile.

This does **not** use Microsoft Graph, Outlook on the web, new Outlook for Windows, or admin-enabled cloud APIs. It uses Windows COM automation against the classic Outlook desktop app/profile available on the machine running the MCP server. This is useful if you don't want to deal with your IT support or ask for your admin's blessing.

> Note: this MCP is idiosyncratic to my own workflow and requirements. It is advised to fork and modify it—or ask your coding agent to do it for you—to mold the MCP to your own Outlook setup and use case.

> Warning: Classic Outlook for Windows for Microsoft 365 users is supported until at least 2029. New Outlook gradually becomes the default or replacement. This MCP will only be viable in the near/medium term. In the long term, use a different MCP that uses admin-backed APIs! See https://learn.microsoft.com/en-us/answers/questions/5554339/when-will-classic-outlook-end

## Requirements

- Windows
- Classic Microsoft Outlook desktop installed and configured
- `uv`

## Install / run

```powershell
cd C:\Users\muhammad.menjeni\git\outlook-classic-windows-mcp
uv sync
uv run outlook-local-mcp
```

The MCP server speaks stdio, so it is intended to be launched by an MCP client.

## Pi MCP config example

Add a local server entry similar to this in your Pi MCP configuration, adjusting the path if needed:

```json
{
  "mcpServers": {
    "outlook-local": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\muhammad.menjeni\\git\\outlook-classic-windows-mcp",
        "run",
        "outlook-local-mcp"
      ]
    }
  }
}
```

## Tools

### `search_email`

Searches Outlook mail by subject and/or body.

Arguments:

- `query` string: case-insensitive substring to find.
- `folder` string: folder to search. Default: `Inbox`. You can use paths like `Inbox/Archive` or `Mailbox Name/Inbox`.
- `search_scope`: `all`, `subject`, or `body`. Default: `all`.
- `max_results`: number of matches to return. Default: `10`.
- `max_items`: newest items to inspect in the folder. Default: `500`.
- `include_body_preview`: include a short body preview. Default: `true`.

### `list_mail_folders`

Lists available Outlook folders to help choose a folder path.

### `create_leave_calendar_blocks`

Creates two unsent Outlook calendar items for leave review:

1. A personal blocker marked **Out of Office** with no attendees.
2. A notification meeting marked **Free** with the supplied attendees.

Nothing is sent. By default both items are saved and opened in Outlook for manual review/sending.

Arguments:

- `start_time` string: start date/time, e.g. `2026-09-01 08:00`.
- `end_time` string: end date/time. For all-day events this is interpreted as an exclusive end, e.g. one day from `2026-09-04 00:00` to `2026-09-05 00:00`.
- `required_attendees` list/string: additional notification recipients. Configurable defaults can also be used.
- `subject` string: default comes from config, initially `Amirul: On-Leave`.
- `body` string: message body.
- `optional_attendees` list/string: optional notification recipients.
- `location` string.
- `display` boolean: open the saved items in Outlook. Default: `true`.
- `confirmed` boolean: must be `true` to actually create Outlook calendar items. Without confirmation, the tool only returns a proposal.

### `get_leave_defaults`

Shows the current leave defaults and config path.

### `set_leave_defaults`

Persists leave defaults such as subject and notification attendees. Requires `confirmed=true` before writing config.

### `infer_leave_recipients`

Read-only scan of recent local Outlook email to infer candidate distribution lists for leave notifications. Returns candidates and evidence; it does not write config or create drafts.

### `resolve_recipients`

Resolves names, emails, or distribution lists using Outlook recipient resolution/address book.

### `search_contacts`

Searches local Outlook contact folders by name, email, company, department, or job title.

## Notes / limitations

- First access may start Outlook if it is not already running.
- Your organization may show Outlook Object Model Guard prompts or block automation by policy.
- This MVP searches by scanning recent folder items, which is simple and reliable but not as fast as indexed Outlook search for very large folders.