Slim EWS MCP Server

A minimal local MCP server (stdio transport) that gives Claude Desktop / Claude Code a controlled set of tools for working with a mailbox on Microsoft Exchange via EWS — built on exchangelib.

Designed for on-prem Exchange servers where IMAP is closed but https://…/EWS/Exchange.asmx is reachable. Works with any EWS-enabled server; every connection detail is driven by configuration, nothing is hardcoded.

Scope: mail only — list, read, reply, forward, move, soft-delete, mark read/unread. No calendars, no contacts, no tasks. Safety and token economy are prioritized over feature completeness.

Safety model

• Capability modes. EWS_MODE bounds what the server can do at all: full (default), draft (reply/forward save to Drafts — the server cannot send anything), read (read-only; mutating tools are not even registered, so the model never sees them). See Restricting what the server can do.

• Two-step confirmation, enforced in code. reply_email, forward_email, move_message and delete_message do nothing when called with confirm=false (the default) — they return a preview (recipients, subject, exact text / what moves where). The actual send/move/delete code is unreachable without an explicit second call with confirm=true. This is an invariant, not a setting.

• Soft delete only. delete_message moves the message to Deleted Items; permanent deletion is not implemented at all.

• Read-only by default elsewhere. The only unconfirmed mutating action is mark_read.

• Token-lean responses. Listings return metadata + a ~200-char snippet, never bodies; bodies are converted HTML→Markdown with quoted history trimmed by default; attachments are listed by name/size and never downloaded.

• No secrets in code or logs. Credentials come only from environment variables / .env. Logs (stderr) contain operation metadata only — never bodies, subjects, passwords or auth headers.

• TLS verification stays on unless you explicitly opt out (see TLS).

Related MCP server: calendar-tasks-mcp

Tools

Folders are addressed by language-independent alias (inbox, sent, drafts, trash, junk, outbox), by display-name path (Inbox/Projects/2026), or by folder id from list_folders.

Requirements

• Python 3.10+

• Network access to the EWS endpoint of your Exchange server

• An account with password-based auth (Basic / NTLM / Digest / Kerberos). OAuth (Exchange Online) is not supported in this version.

Installation

git clone https://github.com/Pal9yni4bi/slim-ews-mcp.git
cd slim-ews-mcp
python -m venv .venv

# Windows (Git Bash):        source .venv/Scripts/activate
# Windows (PowerShell):      .venv\Scripts\Activate.ps1
# Linux / macOS:             source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env   # then edit .env

Configuration

Copy .env.example to .env and fill it in. .env is git-ignored; real environment variables take precedence over the file.

* not required when EWS_AUTODISCOVER=true.

Restricting what the server can do

There are two independent layers, and they defend against different things.

1. Client-side: EWS_MODE. This bounds the server and the model driving it — useful when you want Claude to draft replies for you but never to put mail on the wire.

In draft mode the send call is replaced by save() into the Drafts folder, and the tool descriptions tell the model to report a saved draft rather than a sent message. You review the draft in Outlook/OWA and press Send yourself. read mode goes further: the mutating tools are never registered, so they do not exist as far as the model is concerned (and a direct call is rejected too).

2. Server-side: Exchange permissions. EWS_MODE is enforced by this process. It does not restrict the credentials — anything holding them can still send by other means. EWS has no per-operation ACL: a mailbox owner authenticating as themselves can always send as themselves, and no EWS or Set-CASMailbox setting changes that (EWSEnabled / EWSAllowList control which applications may use EWS, not which operations they may perform).

To make "cannot send" a boundary the process cannot cross, connect as a separate service account that has been granted access to the mailbox but not the right to send as it. On on-prem Exchange:

# read + create drafts in the target mailbox
Add-MailboxPermission -Identity user@example.com -User svc-claude `
  -AccessRights FullAccess -InheritanceType All

# deliberately NOT granted:
#   Add-ADPermission ... -ExtendedRights "Send As"
#   Set-Mailbox user@example.com -GrantSendOnBehalfTo svc-claude

Then point the server at the mailbox while authenticating as the service account:

EWS_EMAIL=user@example.com
EWS_USERNAME=CORP\svc-claude
EWS_PASSWORD=...
EWS_ACCESS_TYPE=delegate
EWS_MODE=draft

FullAccess does not imply SendAs — reading and saving drafts work, while any send attempt is refused by Exchange itself (ErrorSendAsDenied / access denied), regardless of what the client asks for. For a stricter, folder-level variant use Add-MailboxFolderPermission (e.g. Reviewer on :\Inbox, Editor on :\Drafts) instead of FullAccess.

Note that EWS_ACCESS_TYPE=delegate by itself grants nothing and restricts nothing — it only tells Exchange how to interpret the connection. The actual permissions come from the cmdlets above.

TLS and internal CAs

If your Exchange server uses a certificate issued by an internal corporate CA, do not disable verification — point Python's requests at your CA bundle instead:

1. Export the root CA certificate as a PEM/CRT file (from your IT department, or from the browser's certificate viewer on the OWA page).

2. Set the standard environment variable (in .env or system-wide):

   REQUESTS_CA_BUNDLE=C:\certs\corp-root-ca.pem

EWS_INSECURE_TLS=true exists as a last resort only. It disables certificate verification entirely, which makes the connection vulnerable to man-in-the-middle attacks — anyone on the network path can read your password and your mail. The server logs a warning on every start while it is enabled. Never use it outside a trusted network segment, and prefer fixing the CA bundle instead.

Hooking up to Claude

Claude Desktop (classic versions)

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ews-mail": {
      "command": "C:\\path\\to\\slim-ews-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\slim-ews-mcp\\src\\main.py"],
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

On Linux/macOS use .venv/bin/python as the command. Credentials are read from .env in the project root, so they don't need to appear in the Claude config. Restart Claude Desktop after editing.

Claude Desktop (new unified app, 2025+)

The unified Claude Desktop ignores mcpServers in claude_desktop_config.json (it strips the key on restart). Local stdio servers are installed as MCPB extension bundles instead. A bundle is just a zip containing one manifest.json:

{
  "dxt_version": "0.2",
  "name": "ews-mail",
  "display_name": "EWS Mail",
  "version": "0.1.0",
  "description": "Safe EWS mail tools for Claude.",
  "author": { "name": "you" },
  "server": {
    "type": "binary",
    "entry_point": "run",
    "mcp_config": {
      "command": "C:\\path\\to\\slim-ews-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\slim-ews-mcp\\src\\main.py"],
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

Zip the manifest.json (it must sit at the zip root), rename the archive to ews-mail.mcpb, then in Claude Desktop open Settings → Extensions and install the file (button or drag-and-drop). The absolute paths make the bundle machine-specific — rebuild it per machine.

Claude Code

Windows (Git Bash):

claude mcp add ews-mail -- /c/path/to/slim-ews-mcp/.venv/Scripts/python.exe /c/path/to/slim-ews-mcp/src/main.py

Linux / macOS:

claude mcp add ews-mail -- /path/to/slim-ews-mcp/.venv/bin/python /path/to/slim-ews-mcp/src/main.py

Verifying the setup

1. Config check: from the project root run .venv\Scripts\python.exe src\main.py (Windows) or .venv/bin/python src/main.py (Linux/macOS) — the system python won't do, the dependencies live in the venv. With a bad/missing .env it exits immediately with a readable message; with a good one it starts silently and waits on stdin (Ctrl+C to stop).

2. Reading works: in Claude, ask "list my 5 latest unread emails" — you should get metadata and snippets from list_messages.

3. Dry-run really blocks sending: ask Claude to reply to some message. The first reply_email call must come back with "status": "preview" and nothing must appear in your Sent Items until you approve and Claude repeats the call with confirm=true.

Troubleshooting

• 401 / authentication failed — check EWS_USERNAME / EWS_PASSWORD; for NTLM the username usually needs the DOMAIN\user form (in .env, write the backslash as-is: CORP\jdoe). Try EWS_AUTH_TYPE=ntlm explicitly if autodetection picks the wrong scheme.

• TLS certificate verification failed — see TLS and internal CAs.

• "Message not found" after moving/deleting — EWS item ids change when a message changes folders; re-run list_messages and use the fresh id.

• Cannot reach the EWS endpoint — verify the URL opens in a browser (it should ask for credentials or show a WSDL), check VPN/firewall.

Project layout

src/
  main.py         entry point (stdio MCP server)
  config.py       env/.env loading and validation
  ews_client.py   exchangelib Account, folder resolution, error mapping
  tools.py        the 8 MCP tools + confirmation invariant
  html_to_md.py   HTML→Markdown conversion, quoted-history trimming

License

MIT