ews-mcp-orf

MCP server for an on-premises Microsoft Exchange mailbox via EWS — a lean, safety-gated tool surface for LLM assistants: capability tiers, send kill-switch, two-phase content-bound send confirmation, recipient guard, and a hash-chained audit log.

This is the internally packaged distribution of azizmazrou/ews-mcp (MIT). It carries local hardening patches (attachment size cap, recipient canonicalization, audit fail-closed, persistent confirm tokens, system-trust TLS). Full architecture and development docs live in the source repository.

Install & run (stdio — the default)

Requires uv (a single EXE; it manages its own Python) — no Docker, no venv, no checkout:

uvx --from ews-mcp-orf ewsmcp

Pin a version for pilot deployments:

uvx --from ews-mcp-orf==4.5.0a1.post1 ewsmcp

Claude Code (one command, then restart the session):

claude mcp add exchange \
  -e EWS_SERVER_URL="https://mail.example.com/EWS/Exchange.asmx" \
  -e EWS_EMAIL="user@example.com" \
  -e EWS_USERNAME="DOMAIN\\user" \
  -e EWS_PASSWORD="…" \
  -e EWS_CAPABILITY_TIER="read" \
  -e SEND_ENABLED="false" \
  -e EWS_TZ="Europe/Vienna" \
  -- uvx --from ews-mcp-orf ewsmcp

On Windows, Integrated Authentication is available as an explicit opt-in:

EWS_AUTH_MODE=process \
EWS_SERVER_URL="https://mail.example.com/EWS/Exchange.asmx" \
EWS_EMAIL="user@example.com" \
uvx --from ews-mcp-orf ewsmcp

This uses the current Windows logon token through SSPI and does not use EWS_USERNAME or EWS_PASSWORD. The default EWS_AUTH_MODE=credentials remains portable across Windows, Linux and macOS.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "exchange": {
      "command": "uvx",
      "args": ["--from", "ews-mcp-orf", "ewsmcp"],
      "env": {
        "EWS_SERVER_URL": "https://mail.example.com/EWS/Exchange.asmx",
        "EWS_EMAIL": "user@example.com",
        "EWS_USERNAME": "DOMAIN\\user",
        "EWS_PASSWORD": "…"
      }
    }
  }
}

Any MCP client works the same way: command = uvx --from ews-mcp-orf ewsmcp, credentials in env. The server speaks stdio — your client starts it as a child process; nothing listens on the network, and it reaches Exchange through whatever network your machine has (including corporate VPN).

What you get

• 28 tools across mail, calendar, tasks, contacts, and people lookup — short stable aliases (m12, e3) instead of 150-char raw EWS ids.
• Token-lean responses: cleaned bodies, alias-only ids, ~60-token cards.
• Cache-first reads: a background delta-sync mirrors folders into a local SQLite store; warm reads answer in milliseconds with provenance ({"source": "cache", "as_of": …}) and fall back to live EWS. Arabic search matches across orthographic variants.
• TLS from the system trust store (truststore): officially signed Exchange certificates work out of the box — no SSL_CERT_FILE needed.

Safety architecture (defaults are safe)

For least privilege, run pilot users with:

EWS_CAPABILITY_TIER=read SEND_ENABLED=false

Key configuration (env)

The server never exits on boot: transports bind before any Exchange contact, the connection manager retries with backoff, and health state is observable via get_server_status (works over stdio and while cold).

Provenance & license

This package is built from a pinned upstream commit with local security patches (MIT). Version scheme: <upstream>.post<n>. See the packaging repository's PROVENANCE.md for the exact commit and upgrade process. Upstream project and full docs: github.com/azizmazrou/ews-mcp.