OutlookGPT
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OutlookGPT search my inbox for emails from Sarah about the Q3 budget"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OutlookGPT
Local Microsoft Outlook MCP server for Windows. OutlookGPT connects Claude Desktop, Cursor, Hermes Agent, and any Model Context Protocol 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.
Contents
Related MCP server: outlook-desktop-mcp
What you can do
Task | Tool | Default |
Search recent Outlook mail by subject, sender, or body |
| Allowed |
Read one message, including a truncated body |
| Allowed |
List mail stores and folders |
| Allowed |
Save a reply in Drafts without sending it |
| Blocked until you turn read-only off and pass |
Send a new email from the Outlook profile |
| Blocked until read-only is off, |
List calendar events from now |
| Allowed |
Create a calendar appointment |
| Blocked until you turn read-only off and pass |
List Outlook 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 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:
.\scripts\install.ps1
uv run pytestinstall.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:
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:
.\scripts\run.ps1scripts/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.
{
"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.
{
"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.
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.
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:
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.
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 |
| read | Version, transport, read-only flag, and whether sending is armed |
| read | Reports that the Outlook module is enabled |
| read | Status of a background job |
| read | Recent log lines for a background job |
| read | Mail stores and folders, up to two levels deep |
| read | Recent mail in one folder. An empty query returns the newest messages |
| read | One message by the |
| write | Saves a reply in Drafts. Does not send it |
| destructive | Sends a new email. Subject max 200 characters. Body max 100,000 characters |
| read | Events from now, up to 31 days ahead |
| write | Creates an appointment. Times are ISO-8601, local if they have no offset |
| 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 |
|
destructive |
|
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.
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: 8000Key | Meaning |
| Default |
|
|
| Used only for HTTP. Host must be loopback. Default port |
| JSONL audit path, relative to the checkout unless absolute |
| Maximum recent items scanned by one mail search |
| Preview length in search results |
| Body length returned by |
Environment variables override a running process. Prefix is OUTLOOKGPT_.
Variable | Effect |
|
|
|
|
|
|
| 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
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"]The MCP client launches
scripts/run.ps1.FastMCP exposes the tools over stdio.
Safety middleware checks the tier,
confirm, read-only mode, and the destructive flag.The first Outlook tool call starts a dedicated single-threaded apartment (STA) thread.
That thread attaches to a running classic Outlook process, or launches
OUTLOOK.EXEif Outlook is not already running.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_mailandoutlook_draft_replycan raise Outlook's programmatic-access prompt. That prompt is an Outlook Trust Center setting. This server cannot bypass it. See 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
uv run pytestTests 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. 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 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. Copyright (c) 2026 Busbar.
Available Tools
12 toolsjob_logsJob LogsCRead-only
Recent log lines for a background job.
Inputs: job_id (required), tail. Returns: object
job_statusJob StatusCRead-only
Status of a background job.
Inputs: job_id (required). Returns: object
mcp_healthMcp HealthARead-only
Report version, transport, read-only mode, and whether destructive tools are armed.
Inputs: no named parameters. Returns: object
mcp_list_modulesMcp List ModulesARead-only
List which modules are enabled. This server only mounts Outlook.
Inputs: no named parameters. Returns: object
outlook_create_eventOutlook Create EventB
Create a calendar appointment. Times are ISO-8601, local if they have no offset.
Inputs: end_iso (required), subject (required), start_iso (required), body, +2 more. Returns: object
outlook_draft_replyOutlook Draft ReplyA
Save a reply in Drafts. Does not send it.
Inputs: body (required), entry_id (required), confirm. Returns: object
outlook_list_calendarOutlook List CalendarBRead-only
List calendar events starting from now, up to 31 days ahead.
Inputs: days. Returns: object
outlook_list_foldersOutlook List FoldersARead-only
List mail stores and folders up to two levels deep.
Inputs: no named parameters. Returns: object
outlook_list_tasksOutlook List TasksBRead-only
List Outlook tasks. Completed tasks are omitted unless include_completed is true.
Inputs: include_completed. Returns: object
outlook_read_mailOutlook Read MailARead-only
Read one message by the entry_id returned from search_mail.
Inputs: entry_id (required). Returns: object
outlook_search_mailOutlook Search MailBRead-only
Search recent mail by subject, sender, or body. An empty query returns the newest messages.
Inputs: limit, query, folder. Returns: object
outlook_send_mailOutlook Send MailBDestructive
Send a new email through the running Outlook profile. This cannot be undone.
Inputs: to (required), body (required), subject (required), cc, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides LLMs with access to Microsoft Outlook email functionality, allowing them to read, search, compose, and manage emails through a standardized MCP interface on Windows.-
- AlicenseNot gradedqualityBmaintenanceTurns your running Outlook Desktop into an MCP server, enabling email, calendar, tasks, and attachment management through your existing Outlook session without any cloud APIs.AGPL 3.0
- AlicenseAqualityDmaintenanceA local MCP server that connects Claude Desktop to a personal Hotmail/Outlook.com mailbox via Microsoft Graph API, enabling email management, rule handling, and composing messages.25MIT
- AlicenseAqualityCmaintenanceA local MCP server that gives Claude read/write access to a personal Hotmail/Outlook.com mailbox via the Microsoft Graph API, exposing tools for listing, searching, sending, and drafting emails.68 npmMIT