Exchange EWS MCP

English | 简体中文

A local, draft-first Model Context Protocol (MCP) server for on-premises Microsoft Exchange. It connects through EWS and NTLM, keeps credentials in Windows Credential Manager, and exposes focused mail and calendar tools to MCP clients over stdio.

Why this project

• Local by design — the MCP server runs on the user's Windows machine; no relay service is required.

• Draft-first safety — mail-writing tools create drafts and never send automatically.

• Explicit meeting sends — invitations require an explicit confirmation path.

• Focused tool surface — 18 production tools cover identity, mail, templates, availability, and calendar workflows.

• Opaque local references — Agents work with message_ref, draft_ref, and template_ref instead of raw Exchange identifiers.

• Conversation-aware templates — EWS UniqueBody is preferred so quoted history is excluded before a reusable format is stored.

• Server-side template rendering — complete templates stay local; the Agent provides only new content when using template_ref.

Related MCP server: outlook-mcp

Safety model

Exchange EWS MCP intentionally places several boundaries between an Agent and Exchange:

These controls reduce risk, but they do not replace Exchange permissions, server policy, MCP client controls, or user review.

Architecture

flowchart LR
    A["MCP client / Agent"] -->|stdio| S["Exchange EWS MCP"]
    S --> W["Mail and calendar workflows"]
    W --> E["EWS client + NTLM"]
    E --> X["On-premises Exchange"]
    W --> R["Local opaque-reference store"]
    S --> C["Windows Credential Manager"]

The production server exposes semantic workflows. A separate debug server adds six lower-level EWS write primitives for protocol troubleshooting.

Requirements

• Windows 10/11 or Windows Server

• Python 3.10 or newer

• An on-premises Microsoft Exchange EWS endpoint reachable from the machine

• An Exchange account allowed to use EWS with NTLM

• An MCP client that supports local stdio servers

Quick start

1. Clone and install

git clone https://github.com/ShermanGu/exchange-ews-mcp.git
cd exchange-ews-mcp
.\install.cmd

The installer creates .venv, installs the package and dependencies, and verifies the installed package version.

2. Configure Exchange

.\.venv\Scripts\exchange-ews-mcp.exe configure
.\.venv\Scripts\exchange-ews-mcp.exe set-current-user `
  --email "you@company.example" `
  --display-name "Your Name"
.\.venv\Scripts\exchange-ews-mcp.exe status
.\.venv\Scripts\exchange-ews-mcp.exe test

configure prompts for the EWS URL, username, and password. The password is written to Windows Credential Manager.

3. Generate MCP configuration

.\.venv\Scripts\exchange-ews-mcp.exe mcp-config

Equivalent configuration:

{
  "mcpServers": {
    "exchange-ews": {
      "command": "D:\\tools\\exchange-ews-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "exchange_ews_mcp.server"]
    }
  }
}

Restart the MCP client after changing its server configuration. Use the production server for normal operation; reserve exchange_ews_mcp.debug_server for troubleshooting.

4. Verify the local installation

.\.venv\Scripts\exchange-ews-mcp.exe version
.\.venv\Scripts\exchange-ews-mcp.exe tool-list

Production tools

See AGENT-TOOLS.md for routing guidance and AGENT-CONNECTION.md for MCP client setup.

Template workflow

Template extraction is read-only and independent from writing a new message or replying:

extract_email_template
        ↓ template_ref + compact preview
Agent generates only the new content fragment
        ↓
compose_email or reply_to_email
        ↓
server renders against the complete local template

The single body-parameter contract is:

• Without template_ref, body_html is the complete HTML body.

• With template_ref, body_html is only the new content fragment.

• For replies, message_ref selects the conversation and recipients; template_ref independently selects formatting resources.

Example calls:

extract_email_template(...) -> template_ref
compose_email(..., template_ref=template_ref, body_html="<p>New content</p>")
reply_to_email(message_ref=target, template_ref=template_ref, body_html="<p>New reply</p>")

Normal template attachments are not copied unless explicitly requested. Referenced inline cid: resources are copied after preflight validation.

Command-line examples

Extract a template from Sent Items:

.\.venv\Scripts\exchange-ews-mcp.exe extract-email-template `
  --folders "Sent Items" `
  --subject-contains "weekly report"

Create a templated draft:

.\.venv\Scripts\exchange-ews-mcp.exe compose-email `
  --to "recipient@company.example" `
  --subject "Weekly project report" `
  --html-file ".\new-content.html" `
  --template-ref "tmpl_xxx"

Development

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m pytest -W error::ResourceWarning

The current regression suite contains 185 tests. GitHub Actions runs the strict suite on supported Python versions.

Documentation

Limitations

• The primary runtime target is Windows because credentials use Windows Credential Manager and authentication uses NTLM.

• EWS behavior and availability depend on Exchange version, server configuration, and administrator policy.

• This project does not bypass mailbox permissions or organizational controls.

• Exchange Online tenants should generally prefer Microsoft Graph and modern authentication.

Contributing and security

Contributions are welcome. Start with CONTRIBUTING.md or its Simplified Chinese translation.

Please do not report vulnerabilities in public issues. Follow SECURITY.md or SECURITY.zh-CN.md.

License

Released under the MIT License.