OutlookGPT
# OutlookGPT
**Local Microsoft Outlook MCP server for Windows.** OutlookGPT connects [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.com), [Hermes Agent](https://hermes-agent.nousresearch.com/), and any [Model Context Protocol](https://modelcontextprotocol.io) client to classic Outlook on the same PC.
An agent can search Outlook mail, read a message, save a reply in Drafts, send email, list calendar events, create appointments, and list tasks. The server talks to the Outlook profile already signed in on this machine. It does not upload the mailbox to a third-party API.
OutlookGPT is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Microsoft or OpenAI.
[](https://www.python.org/downloads/)
[](#requirements)
[](https://modelcontextprotocol.io)
[](LICENSE)
## Contents
- [What you can do](#what-you-can-do)
- [Requirements](#requirements)
- [Install](#install)
- [Connect Claude Desktop](#connect-claude-desktop)
- [Connect Cursor](#connect-cursor)
- [Connect Hermes Agent](#connect-hermes-agent)
- [Outlook MCP tools](#outlook-mcp-tools)
- [Safety model](#safety-model)
- [Configuration](#configuration)
- [How OutlookGPT works](#how-outlookgpt-works)
- [Limits](#limits)
- [Development](#development)
- [FAQ](#faq)
- [Security](#security)
- [License](#license)
## What you can do
| Task | Tool | Default |
| --- | --- | --- |
| Search recent Outlook mail by subject, sender, or body | `outlook_search_mail` | Allowed |
| Read one message, including a truncated body | `outlook_read_mail` | Allowed |
| List mail stores and folders | `outlook_list_folders` | Allowed |
| Save a reply in Drafts without sending it | `outlook_draft_reply` | Blocked until you turn read-only off and pass `confirm=true` |
| Send a new email from the Outlook profile | `outlook_send_mail` | Blocked until read-only is off, `confirm=true` is set, and `OUTLOOKGPT_ALLOW_DESTRUCTIVE=1` |
| List calendar events from now | `outlook_list_calendar` | Allowed |
| Create a calendar appointment | `outlook_create_event` | Blocked until you turn read-only off and pass `confirm=true` |
| List Outlook tasks | `outlook_list_tasks` | Allowed |
The server starts **read-only**. Search, read, calendar listing, and task listing work immediately. Drafts, new appointments, and sent mail stay off until you opt in.
## Requirements
- Windows with classic Outlook (`OUTLOOK.EXE`) installed and signed in to the mailbox you want the agent to use.
- [uv](https://docs.astral.sh/uv/) on `PATH`. The install script fetches Python 3.12.
- An MCP client that can launch a local process over stdio.
New Outlook (`olk.exe`) has no COM interface. OutlookGPT cannot attach to it. Outlook on the web, Mac, and Linux are outside this server.
## Install
From the repository root:
```powershell
.\scripts\install.ps1
uv run pytest
```
`install.ps1` creates `.venv` and, if you do not already have one, copies `config/config.example.yaml` to `config/config.yaml`. The real config and `.env` stay on your machine. They are gitignored.
Check that the server builds:
```powershell
uv run python -c "from outlookgpt.server import build_server; from outlookgpt.core.config import load_runtime; print(build_server(load_runtime().config))"
```
Launch it yourself with:
```powershell
.\scripts\run.ps1
```
`scripts/run.ps1` is what MCP clients should start. It runs the checkout's virtualenv interpreter. Avoid `uv run outlookgpt` for a long-lived server: on Windows, `uv run` rewrites `.venv\Scripts\outlookgpt.exe`, and that fails with error 32 while another process has the file open.
## Connect Claude Desktop
Edit `%APPDATA%\Claude\claude_desktop_config.json` and restart Claude Desktop. Replace the path with your checkout.
```json
{
"mcpServers": {
"outlookgpt": {
"command": "powershell",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"C:\\path\\to\\OutlookGPT\\scripts\\run.ps1"
]
}
}
}
```
Ask Claude to call `mcp_health`. A fresh install reports `read_only: true` and `allow_destructive: false`.
## Connect Cursor
Add the same stdio server to `.cursor/mcp.json` in a project, or to your user MCP config. Replace the path with your checkout.
```json
{
"mcpServers": {
"outlookgpt": {
"command": "powershell",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"C:\\path\\to\\OutlookGPT\\scripts\\run.ps1"
]
}
}
}
```
Reload MCP servers in Cursor, then ask the agent to list Outlook folders or search the inbox. Cursor sees the Outlook tools only while this Windows process is running.
## Connect Hermes Agent
Hermes reads `~\.hermes\config.yaml`. The server key below is the short name. Hermes calls each tool as `mcp__outlookgpt__<tool>`, so `outlook_search_mail` is `mcp__outlookgpt__outlook_search_mail`. `hermes mcp test` prints the short server name. That short name is not what the chat model calls.
```yaml
mcp_servers:
outlookgpt:
command: powershell
args:
- -NoProfile
- -ExecutionPolicy
- Bypass
- -File
- C:/path/to/OutlookGPT/scripts/run.ps1
timeout: 180
env: {}
tools:
include: []
exclude: []
```
`include: []` is treated as unset by most clients. Omit the key, or list real tool names, when you want a whitelist. `exclude` drops tools by exact name or glob, for example `outlook_send_mail`.
Restart Hermes after editing the file. A server that is already running keeps the environment it was started with. Saving `.env` or `config.yaml` does not change a live process.
More Windows notes, including the Outlook Trust Center prompt, are in [docs/hermes-setup.md](docs/hermes-setup.md).
### Arm drafts and sent mail
Keep the default read-only until search and read look right. To let an agent save drafts and create events, set `server.read_only: false` in `config/config.yaml` or pass this environment variable on the MCP process:
```yaml
env:
OUTLOOKGPT_READ_ONLY: "false"
```
Sending mail also needs the destructive flag on that same process. The flag is environment-only. Putting it in YAML does nothing.
```yaml
env:
OUTLOOKGPT_READ_ONLY: "false"
OUTLOOKGPT_ALLOW_DESTRUCTIVE: "1"
```
`outlook_send_mail` still requires `confirm=true` on that call. A confirmed send goes out through Outlook and cannot be undone by this server.
## Outlook MCP tools
Mounted Outlook tools are prefixed with `outlook_`. Health and job tools stay on the root server.
| Tool | Tier | What it does |
| --- | --- | --- |
| `mcp_health` | read | Version, transport, read-only flag, and whether sending is armed |
| `mcp_list_modules` | read | Reports that the Outlook module is enabled |
| `job_status` | read | Status of a background job |
| `job_logs` | read | Recent log lines for a background job |
| `outlook_list_folders` | read | Mail stores and folders, up to two levels deep |
| `outlook_search_mail` | read | Recent mail in one folder. An empty query returns the newest messages |
| `outlook_read_mail` | read | One message by the `entry_id` from search |
| `outlook_draft_reply` | write | Saves a reply in Drafts. Does not send it |
| `outlook_send_mail` | destructive | Sends a new email. Subject max 200 characters. Body max 100,000 characters |
| `outlook_list_calendar` | read | Events from now, up to 31 days ahead |
| `outlook_create_event` | write | Creates an appointment. Times are ISO-8601, local if they have no offset |
| `outlook_list_tasks` | read | Outlook tasks. Completed tasks are omitted unless requested |
`outlook_search_mail` scans at most `outlook.max_scan` recent items in one folder (default 200). It is a bounded folder scan, not a full-mailbox index. `outlook_read_mail` uses the `entry_id` from that search. Entry IDs are valid for the store that produced them.
## Safety model
Three tiers run before a tool handler:
| Tier | Gate |
| --- | --- |
| read | Always allowed |
| write | `confirm=true`, and read-only mode off |
| destructive | `confirm=true`, read-only mode off, and `OUTLOOKGPT_ALLOW_DESTRUCTIVE=1` |
`confirm` must be the boolean `true`. The string `"true"` is refused.
Every tool call is appended to `logs/audit.jsonl`. Argument names containing password, secret, token, passphrase, authorization, api key, or credential are redacted. Secret values loaded from the environment or Windows Credential Manager are redacted too.
Optional Streamable HTTP is loopback only. Set `server.transport: http` or `OUTLOOKGPT_TRANSPORT=http`. The process refuses any host other than `127.0.0.1`, `localhost`, or `::1`. That port has no authentication. Do not publish it.
## Configuration
`config/config.yaml` is created from the example on install. Unknown keys are rejected.
```yaml
server:
name: outlookgpt
transport: stdio
host: 127.0.0.1
port: 8766
read_only: true
audit_log: logs/audit.jsonl
outlook:
enabled: true
max_scan: 200
preview_chars: 240
body_chars: 8000
```
| Key | Meaning |
| --- | --- |
| `server.read_only` | Default `true`. Write and send tools are refused while this is true |
| `server.transport` | `stdio` (default) or `http` |
| `server.host` / `server.port` | Used only for HTTP. Host must be loopback. Default port `8766` |
| `server.audit_log` | JSONL audit path, relative to the checkout unless absolute |
| `outlook.max_scan` | Maximum recent items scanned by one mail search |
| `outlook.preview_chars` | Preview length in search results |
| `outlook.body_chars` | Body length returned by `outlook_read_mail` |
Environment variables override a running process. Prefix is `OUTLOOKGPT_`.
| Variable | Effect |
| --- | --- |
| `OUTLOOKGPT_READ_ONLY` | `true` or `false`. Overrides `server.read_only` for this process |
| `OUTLOOKGPT_TRANSPORT` | `stdio` or `http` |
| `OUTLOOKGPT_ALLOW_DESTRUCTIVE` | `1` arms `outlook_send_mail`. Ignored if placed in YAML |
| `OUTLOOKGPT_CONFIG` | Absolute path to a config file |
Copy `.env.example` to `.env` in the repository root for local overrides. The file is read from the checkout, not from the MCP client's working directory, and only when the process starts.
Do not put mailbox passwords or API tokens in `config.yaml`. OutlookGPT uses the classic Outlook profile. Values whose environment names contain `PASSWORD`, `TOKEN`, `SECRET`, `PASSPHRASE`, or `KEY` are registered for audit redaction. A named secret can also be read from Windows Credential Manager under the `outlookgpt` service.
## How OutlookGPT works
```mermaid
flowchart LR
client["MCP client<br/>Claude, Cursor, Hermes"] --> server["OutlookGPT<br/>stdio"]
server --> gates["Safety tiers and audit log"]
gates --> com["Classic Outlook COM<br/>STA thread"]
com --> mailbox["Mail, calendar, tasks"]
```
1. The MCP client launches `scripts/run.ps1`.
2. FastMCP exposes the tools over stdio.
3. Safety middleware checks the tier, `confirm`, read-only mode, and the destructive flag.
4. The first Outlook tool call starts a dedicated single-threaded apartment (STA) thread.
5. That thread attaches to a running classic Outlook process, or launches `OUTLOOK.EXE` if Outlook is not already running.
6. Allowed calls are appended to the local audit log. Refusals are recorded too.
Mail stays in Outlook. OutlookGPT does not proxy the mailbox through Microsoft Graph, and it does not ship message contents to its own service. Your MCP client's own model provider still receives whatever the client puts in the prompt.
## Limits
- Windows and classic Outlook only. New Outlook, Outlook for Mac, and Outlook on the web are not supported.
- Search covers recent items in one folder, up to `max_scan`, not every message in the mailbox.
- Message bodies returned to the client are truncated to `body_chars` (default 8000).
- `outlook_send_mail` and `outlook_draft_reply` can raise Outlook's programmatic-access prompt. That prompt is an Outlook Trust Center setting. This server cannot bypass it. See [docs/hermes-setup.md](docs/hermes-setup.md).
- HTTP mode has no authentication. Keep it on loopback.
- Calendar create and mail send act on the Outlook profile of the Windows user running the process.
## Development
```powershell
uv run pytest
```
Tests use an in-memory Outlook fake. They do not launch Outlook and they do not send mail.
Python 3.12 is pinned in `.python-version`. The package name is `outlookgpt`. The console script is `outlookgpt`.
## FAQ
### What is an Outlook MCP server?
An Outlook MCP server is a local program that speaks the [Model Context Protocol](https://modelcontextprotocol.io). OutlookGPT is that program for classic Microsoft Outlook. Claude, Cursor, Hermes, and other MCP clients call tools such as `outlook_search_mail` instead of scraping the Outlook window.
### Does OutlookGPT work with New Outlook?
No. New Outlook (`olk.exe`) does not expose the Outlook COM object model. Install and run classic Outlook (`OUTLOOK.EXE`) for the mailbox you want to use.
### Can Claude or Cursor send email by itself?
Not on a default install. The server is read-only. Sending also requires `OUTLOOKGPT_ALLOW_DESTRUCTIVE=1` and `confirm=true` on the `outlook_send_mail` call. You can exclude `outlook_send_mail` in the client config if you want search and drafts only.
### Does this server store my mailbox in the cloud?
No. OutlookGPT runs on your PC and uses the local Outlook profile through COM. The audit log is a JSONL file in the checkout. Message text can still reach the model provider your MCP client uses, because that client includes tool results in the model request.
### Is OutlookGPT the official Microsoft or OpenAI Outlook integration?
No. OutlookGPT is an independent MIT-licensed project. Microsoft Outlook and OpenAI are trademarks of their owners.
### Which Python version does it need?
Python 3.12 or newer. `scripts/install.ps1` installs 3.12 with uv.
## Security
OutlookGPT can read your mailbox and, once you arm it, send mail as you. Run it only on a machine and Windows account you trust. Review [docs/hermes-setup.md](docs/hermes-setup.md) before setting `OUTLOOKGPT_ALLOW_DESTRUCTIVE=1`.
Report a vulnerability through a private GitHub security advisory on this repository. Do not file a public issue that includes mailbox contents, tokens, or audit logs.
## License
[MIT](LICENSE). Copyright (c) 2026 Busbar.
TDQS
Scored across 12 tools
Most tools target a distinct resource+action: search_mail vs read_mail vs draft_reply vs send_mail are cleanly separated, and calendar/task/job tools don't overlap. The only mild fuzziness is between mcp_health and mcp_list_modules (both server-metadata) and job_status vs job_logs, but descriptions make the boundaries clear.
Predictable prefix scheme: mcp_* for server introspection, job_* for background jobs, and a consistent outlook_verb_noun pattern (list_folders, search_mail, read_mail, draft_reply, send_mail, list_calendar, create_event, list_tasks). Minor deviations where metadata tools use noun-only names (mcp_health, job_status, job_logs) instead of verb_noun, but overall readable and consistent.
12 tools is well within the ideal 3-15 range and each tool maps to a concrete operation across mail, calendar, and tasks, plus lightweight infra tools. No obvious filler or redundancy.
Mail covers search/read/reply-draft/send, and calendar covers list/create, but there are notable gaps: no calendar update/delete, no task creation or completion (tasks are only listable), and no mail management like delete, move, or forward. Reply drafting exists but general draft composition does not, leaving several dead ends.