Content
# Outlook Agent Tool
**Let your AI assistant read and write your email and calendar — just by asking.**
Once this is set up, you can say things to your AI assistant like *"what's on my
calendar tomorrow?"*, *"summarize my unread email,"* or *"draft a reply to the
last message from the bank"* — and it actually does it, in your real mailbox.
It works on Windows, takes about 5–10 minutes to set up once, and everything
stays on your own computer.
---
## Why this is handy
**It works out of the box — no logins to fight with.**
Most tools that connect to work email make you go through a corporate sign-in
screen, ask your IT department for approval, or generate special "app
passwords." This one skips all of that. It quietly works through the **Outlook
app you already have open and signed in** — so there's nothing extra to log into.
**It works across all your accounts — work and personal.**
Because it rides on top of Outlook, it works with every account you've added
there — a **work Exchange** mailbox, a personal **Outlook.com** account, a
**Gmail** account you've added to Outlook, and so on. The AI assistant talks to
Outlook; Outlook deals with each email provider. You don't set up anything
provider-specific.
> Just ask the assistant *"what are my Outlook accounts?"* and then point it at
> one — *"check my **personal** inbox"* or *"what's in my **work** calendar?"*
> If you don't name an account, it uses your default Outlook account.
**Nothing leaves your computer, and it asks before doing anything risky.**
There are no passwords or tokens stored anywhere. Reading your mail and calendar
happens locally. And before the assistant ever **sends, replies, moves, or
deletes** anything, it shows you what it's about to do and waits for your OK.
---
## A few words you'll see (in plain terms)
- **AI assistant / "agent"** — the app you chat with that can take actions for
you (Codex, Claude, Antigravity). This pack plugs your email + calendar into it.
- **"Connecting a tool"** — giving your assistant a new ability. Here, the new
ability is "use my Outlook."
- **MCP** — just the standard plug that lets an assistant use an outside tool.
You don't need to understand it; the setup wires it up for you.
- **Outlook Classic** — the traditional Outlook **desktop program** for Windows
(not the website, and not the newer "new Outlook" app). This tool needs that
one, open and signed in.
---
## What you need
- A **Windows** computer.
- The **Outlook Classic desktop app**, installed and signed in (just open it
once and make sure your mail and calendar show up).
- One of the AI assistants below.
That's it — no other software to install.
---
## Set it up — pick your assistant
Download this folder, open the sub-folder for your assistant, and **double-click
`setup.bat`**. It walks you through the rest. (If Windows shows a blue "Windows
protected your PC" box, click **More info → Run anyway** — that just appears
because the file came from the internet.)
| Your assistant | Open this folder | Email + Calendar it adds |
|---|---|---|
| **Codex** | [`clients/codex`](clients/codex) | Outlook **+ Gmail + Google Calendar** |
| **Claude Code** | [`clients/claude-code`](clients/claude-code) | Outlook |
| **Claude Desktop** | [`clients/claude-desktop`](clients/claude-desktop) | Outlook |
| **Antigravity** | [`clients/antigravity`](clients/antigravity) | Outlook |
Each sub-folder has its own short README with step-by-step instructions. Gmail
and Google Calendar are an extra bonus on **Codex** only (it has built-in
connectors for them); on the others, this pack focuses on Outlook.
You can run the setup again any time — it's safe and won't break anything.
---
## Good to know
- The setup makes a **backup** of any settings file it changes (saved right next
to the original), so nothing is lost.
- If Outlook says *"not connected,"* just open the Outlook desktop app, sign in,
and try again. It needs Outlook running.
- It only sets things up on **your** computer, with **your** accounts.
---
<details>
<summary><b>Technical details</b> (for the curious or for setting this up manually)</summary>
### How it works
The Outlook piece is a small **MCP server** written in PowerShell that drives the
**Outlook Classic desktop app via COM automation**. It acts in the security
context of the Outlook profile you're already signed in to — so:
- **No OAuth, app registration, client secret, or tokens.**
- **No admin-consent / conditional-access wall** that a Microsoft Graph
connector hits on locked-down work tenants.
- Provider-agnostic and **multi-account**: it can target any store in the MAPI
profile (Exchange, Outlook.com, an IMAP/Gmail account added to Outlook, …) via
an optional `account` argument; it falls back to the default store, or a
configured `defaults.defaultAccount`.
- Fast and offline-capable (local, no network hop). Windows + Outlook Classic
only — not webmail or "new Outlook."
### Safety model
Reads run freely; mutating actions are gated. On **Codex** the installer sets
`approval_mode = "approve"` on every write tool (`outlook_mail_send/reply/
forward/move`, `outlook_calendar_create/update/delete_event`). On **Claude Code
/ Desktop / Antigravity**, the client itself prompts for permission before each
tool call. The server also supports a draft-first mode
(`OUTLOOK_MCP_REQUIRE_DRAFT=1`) that blocks one-shot send/create entirely.
### Outlook MCP tools
Mail: `outlook_mail_list_folders`, `outlook_mail_list_messages`,
`outlook_mail_count_messages`, `outlook_mail_read_message`, `outlook_mail_send`,
`outlook_mail_reply` / `outlook_mail_draft_reply`, `outlook_mail_forward` /
`outlook_mail_draft_forward`, `outlook_mail_draft_send` /
`outlook_mail_send_draft`, `outlook_mail_move`, `outlook_mail_mark`.
Calendar: `outlook_calendar_list`, `outlook_calendar_list_events`,
`outlook_calendar_get_event`, `outlook_calendar_create_event` /
`outlook_calendar_draft_event` + `outlook_calendar_send_event`,
`outlook_calendar_update_event`, `outlook_calendar_delete_event`,
`outlook_calendar_free_busy`, `outlook_calendar_find_slots`,
`outlook_calendar_schedule_batch`.
Accounts/people/status: `outlook_accounts_list` (lists every account with name,
SMTP, and default flag), `outlook_resolve_people`, `outlook_status`. The mail/
calendar read tools accept an optional `account` argument (name or SMTP) to
target a specific account. See
[`skills/outlook-cli/references/cli-contract.md`](skills/outlook-cli/references/cli-contract.md).
### Manual setup (any MCP client)
The tool is a stdio MCP server launched by PowerShell. Point any client at
`outlook-cli\outlook-cli.ps1 mcp serve` (replace the path with where you put the
`outlook-cli` folder). JSON clients (Claude Code/Desktop, Antigravity):
```json
{
"mcpServers": {
"outlook": {
"command": "powershell",
"args": ["-ExecutionPolicy", "Bypass", "-NoProfile", "-File", "C:\\Users\\<you>\\dev\\outlook-cli\\outlook-cli.ps1", "mcp", "serve"]
}
}
}
```
Codex (`~/.codex/config.toml`):
```toml
[mcp_servers.outlook]
command = "powershell"
args = ["-ExecutionPolicy", "Bypass", "-NoProfile", "-File", "C:\\Users\\<you>\\dev\\outlook-cli\\outlook-cli.ps1", "mcp", "serve"]
```
### Repository layout
```
outlook-agent-pack/
├── README.md # this file
├── LICENSE # MIT
├── outlook-cli/ # the shared Outlook MCP tool (PowerShell, COM)
├── skills/outlook-cli/ # the shared agent skill (SKILL.md + scripts)
├── lib/common.ps1 # shared installer helpers
└── clients/
├── codex/ # setup.bat + setup.ps1 + ONBOARDING.md + README
├── claude-code/ # setup.bat + setup.ps1 + README
├── claude-desktop/ # setup.bat + setup.ps1 + README
└── antigravity/ # setup.bat + setup.ps1 + README
```
Installers copy the tool to `%USERPROFILE%\dev\outlook-cli`, set the default
time zone, export `OUTLOOK_CLI_REPO`, install the skill where supported, and are
idempotent + config-preserving (every touched config is backed up first).
</details>
---
## License
MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Otto Becker. Free to use,
modify, and share.
