Skip to main content
Glama

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.

Python 3.12+ Windows MCP License: MIT

Contents

Related MCP server: outlook-desktop-mcp

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 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 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:

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.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.

{
  "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

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.

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

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.

  • 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 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. 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 tools
job_logsJob LogsC
Read-only

Recent log lines for a background job.

Inputs: job_id (required), tail. Returns: object

job_statusJob StatusC
Read-only

Status of a background job.

Inputs: job_id (required). Returns: object

mcp_healthMcp HealthA
Read-only

Report version, transport, read-only mode, and whether destructive tools are armed.

Inputs: no named parameters. Returns: object

mcp_list_modulesMcp List ModulesA
Read-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 CalendarB
Read-only

List calendar events starting from now, up to 31 days ahead.

Inputs: days. Returns: object

outlook_list_foldersOutlook List FoldersA
Read-only

List mail stores and folders up to two levels deep.

Inputs: no named parameters. Returns: object

outlook_list_tasksOutlook List TasksB
Read-only

List Outlook tasks. Completed tasks are omitted unless include_completed is true.

Inputs: include_completed. Returns: object

outlook_read_mailOutlook Read MailA
Read-only

Read one message by the entry_id returned from search_mail.

Inputs: entry_id (required). Returns: object

outlook_search_mailOutlook Search MailB
Read-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 MailB
Destructive

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

    B3.2/5.0

    Scored across 12 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides LLMs with access to Microsoft Outlook email functionality, allowing them to read, search, compose, and manage emails through a standardized MCP interface on Windows.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Turns 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
    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      25
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A 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.
      6
      8 npm
      MIT