outlook-ews-mcp

English · Русский

outlook-ews-mcp is an MCP server for on-prem Microsoft Exchange via EWS (exchangelib). It gives MCP-compatible clients (Claude Desktop, Claude Code, and any other MCP client) access to email, calendar, contacts, folders, attachments, and availability data through a single, testable Python service — no direct mailbox scripting required.

Renamed from outlook-mcp. That name was already taken on PyPI by an unrelated project, so the distribution and CLI name are now outlook-ews-mcp. The Python import path is unchanged. Until the first tagged PyPI release, install from this repository as shown below.

Contents

• Highlights
• Tool catalog
• Typical use cases
• Security notes
• Quick start
• Configuration
• Reply drafts, Outlook mentions, and send confirmation
• Request queue
• Claude Desktop / Claude Code example
• Smoke check
• Docker
• CI/CD
• Development
• Project notes
• Contributing
• License

Highlights

• Email — list, search (substring or Advanced Query Syntax), read, send, reply, forward, move, copy, delete, mark, categorize, bulk actions, raw MIME export, attachment add/delete
• System — Inbox Rules, Out-of-Office (automatic replies), read-only delegate listing
• Calendar — list, create, update, delete, respond to invites, find free slots, view a shared/delegate mailbox’s calendar, Room Finder, bulk actions
• Contacts — search, read, create, update, delete
• Folders & attachments — folder CRUD and attachment download
• Auth — NTLM and Basic against on-prem Exchange
• Transport — stdio, Streamable HTTP and (deprecated) SSE; HTTP requires a bearer token
• Architecture — centralized error mapping through a single ExchangeClient abstraction (see Project notes)
• Safety — a privacy-safer smoke check by default (see Smoke check)
• Ops — Docker image plus GitHub and GitLab CI/CD pipelines included

Tool catalog

Every tool below is registered in tool_specs.py, the single source of truth for its name, description, and schema. Read-only marks tools that never modify the mailbox — they get more concurrency (see Request queue) and are safe to call speculatively.

System

⚠️ create_inbox_rule / update_inbox_rule / delete_inbox_rule manage rules over EWS, which removes the client-side rule blob desktop Outlook keeps — this can wipe rules a user created in Outlook itself. This is documented EWS behavior, not a bug here.

Email

Calendar

Contacts

Typical use cases

• Connect Claude Desktop or another MCP client to on-prem Exchange
• Search inbox messages and fetch full email content
• Send or draft emails from AI workflows
• Inspect calendars and create meetings
• Check free/busy windows for scheduling
• Search personal contacts or the Global Address List
• Expose Exchange operations through a controlled MCP boundary instead of direct mailbox scripting

Security notes

What the current code does:

What you should still be careful with:

• EXCHANGE_VERIFY_SSL=false disables TLS certificate verification — trusted internal/self-signed environments only. Prefer EXCHANGE_CA_BUNDLE, which keeps verification on.
• EXCHANGE_AUTH_TYPE=Basic sends credentials in the clear, so the server refuses to start against an http:// EXCHANGE_SERVER; only override with EXCHANGE_ALLOW_INSECURE_BASIC_AUTH=true for a local/test server you control.
• get_attachment writes files to disk, and send_email/reply_email/forward_email/ create_draft read local files (via attachments) and attach their contents to outgoing mail. Combined with untrusted email content, this is a plausible path for prompt-injected exfiltration of any file readable by the process. Local file access is refused by default and only works once EXCHANGE_ATTACHMENT_ROOT is set to an absolute directory, which then confines both attachments paths and get_attachment’s save_path to that directory tree (an unset save_path still falls back to the system temp directory).
• outlook-ews-mcp-smoke is privacy-safe by default and prints only masked mailbox info plus counts; set OUTLOOK_MCP_SMOKE_INCLUDE_DATA=true only if you explicitly want real inbox/event data in stdout.
• If you enable file logging with LOG_FILE, protect that file with OS permissions.
• If you publish Docker images from CI, protect GitLab/GitHub project access and registry permissions.

Quick start

git clone https://github.com/viartemev/outlook-ews-mcp
cd outlook-ews-mcp
uv venv
source .venv/bin/activate
uv pip install -e '.[dev]'
cp .env.example .env
outlook-ews-mcp

By default the server runs in stdio mode. Set MCP_TRANSPORT=streamable-http (or the deprecated sse, for clients that don’t support Streamable HTTP yet) to start an HTTP server instead; the endpoint is /mcp (/sse for SSE). HTTP mode requires MCP_HTTP_AUTH_TOKEN, which clients send as Authorization: Bearer — every request without it gets 401. The token is a static shared secret, not per-user auth: anyone holding it gets full access to the mailbox (read, send, delete), so keep TLS termination (and ideally an IP allowlist) in front of the server when it leaves loopback.

Configuration

Minimal .env to get started — everything else below has a working default:

EXCHANGE_SERVER=https://mail.company.com/EWS/Exchange.asmx
EXCHANGE_USERNAME=DOMAIN\username
EXCHANGE_PASSWORD=secret
[email protected]
EXCHANGE_AUTH_TYPE=NTLM

A fully commented copy of every variable lives in .env.example.

Behavior notes that aren’t tied to a single variable:

• list_events and find_free_slots accept a bounded limit (default 200, maximum 1000); event ranges are capped at 366 days and free-slot ranges at 31 days, so broad queries can’t produce unbounded EWS or MCP responses.
• Listings stay lean by design: email summaries carry the sender but not recipient lists (get_email has them), list_events returns events without bodies (get_event has them), and get_email returns RFC-822 headers only with include_headers: true.
• Direct sends report submitted, not recipient delivery. send_draft looks up the sent copy and returns its new ID when confirmed; it never echoes the invalidated draft ID.
• Attachment metadata includes downloadable; embedded Exchange item attachments have downloadable: false and can’t be saved by get_attachment.

Reply drafts, Outlook mentions, and send confirmation

Use create_reply_draft to prepare an actual EWS reply for review. It defaults to reply_all: true, keeps the source conversation and reply references, and accepts additional_to, additional_cc and attachments. Call send_draft only after review. reply_email still sends immediately; it also accepts HTML and mentions.

For send_email, create_draft, reply_email, create_reply_draft and update_draft, use explicit mention tokens and metadata:

{
  "id": "",
  "reply_all": true,
  "body": "{{mention:owner}}, please prepare the equipment for collection.",
  "mentions": [
    {"key": "owner", "email": "[email protected]", "display_name": "Equipment owner"}
  ],
  "additional_cc": ["[email protected]"],
  "attachments": ["/configured-attachment-root/collection.xlsx"]
}

Mention tokens must appear in body text, not HTML attributes, links, scripts or styles. The server escapes plain text and display names, generates unique OWAAM... HTML anchors, and writes the X-Mentions Internet header through an EWS extended property. Both the anchor and header are required for Outlook’s mention indicator; a literal @name or a mailto link alone is insufficient. Mentioned addresses absent from To/CC are added to To; existing CC recipients stay in CC. Bodies with mentions use HTML and the configured HTML signature. This is an Outlook client convention, verified with Exchange 2016 and Legacy Outlook for Mac; other client/server combinations require their own validation.

For partial updates, omitted fields remain unchanged, explicit null clears nullable fields, and attachments: [] removes attachments. Supplying mentions requires a replacement body. Replacing the body without mentions clears old mention notification metadata. The MCP adapter preserves omission before request validation, including for contacts and calendar updates.

send_draft stamps a unique submission_id, calls SendItem exactly once with the copy destination explicitly set to this account’s Sent Items, then polls for the saved copy. confirmation_timeout_seconds defaults to 10, accepts 0–30, and 0 skips polling. The budget limits polling; a final network request can still take up to the configured Exchange request timeout.

• sent_confirmed: the non-draft copy was found; id is its new Exchange ID.
• submitted: Exchange accepted SendItem; confirmation was disabled.
• submitted_unconfirmed: Exchange accepted SendItem, but the read failed or the copy was not visible before the polling budget expired. Do not resend.
• send_outcome_unknown error: SendItem failed or its response was lost. Do not automatically retry; inspect Sent Items before another attempt.

Results include the actual sent_copy_mailbox, sent_copy_folder and, when available, datetime_sent. A Sent Items copy confirms submission, not recipient delivery or refresh of Outlook’s local cache. Operators can correlate uncertain sends using the named String property OutlookMcpSubmissionId in property set a8b318c0-6eae-4c97-91aa-5ef142043c2b. Unit tests never send real mail.

Request queue

Clients issue several tool calls in parallel. Exchange work is blocking, so the server runs it in worker threads and admits calls through one shared FIFO queue.

• MCP_MAX_CONCURRENCY (default 4) sets how many read-only calls run at once, so an agent asking for an email, the folder list, and the calendar pays the slowest round trip instead of the sum. Mutating calls always run exclusively — one at a time, never overlapping a read — so read/write races on shared account state can’t happen. Callers beyond the limit wait their turn, served in arrival order; a waiting mutation blocks later reads from overtaking it.
• MCP_MAX_QUEUE_SIZE (default 20) caps how many calls can be admitted at once, running or waiting. Once that many are already in, further calls get an immediate server_busy error instead of joining an unbounded queue.
• The transport stays responsive while work is in flight. Tools are awaited rather than run on the event loop thread, so finished responses go out immediately and pings are answered while a long call is still running.
• There is no per-call timeout, deliberately. A thread blocked on a socket read can’t be killed from outside; the runtime can only stop waiting for it, which abandons the thread along with the EWS session it holds. exchangelib’s session pool has a hard maximum and hands out sessions in a loop with no give-up path, so leaked sessions eventually starve it and every later call blocks forever. A slow call is waited out instead, bounded by EXCHANGE_TIMEOUT plus EXCHANGE_MAX_RETRY_WAIT_SECONDS: the account’s retry policy is fail-fast, so every EWS call raises on its first transient error rather than exchangelib retrying it forever internally, and ExchangeClient retries only read-only calls itself, bounded by that wall-clock budget. Writes are never auto-retried. Overruns past the expected budget are logged.

Claude Desktop / Claude Code example

GUI clients don’t see the virtualenv’s bin directory, so use the absolute path to the installed script:

{
  "mcpServers": {
    "outlook": {
      "command": "/path/to/outlook-ews-mcp/.venv/bin/outlook-ews-mcp",
      "env": {
        "EXCHANGE_SERVER": "https://mail.company.com/EWS/Exchange.asmx",
        "EXCHANGE_USERNAME": "DOMAIN\\username",
        "EXCHANGE_PASSWORD": "secret",
        "EXCHANGE_EMAIL_ADDRESS": "[email protected]",
        "EXCHANGE_AUTH_TYPE": "NTLM"
      }
    }
  }
}

Claude Code (credentials are read from the repository’s .env):

claude mcp add outlook -- sh -c 'cd /path/to/outlook-ews-mcp && exec .venv/bin/outlook-ews-mcp'

Smoke check

After filling in .env, run:

outlook-ews-mcp-smoke

Default output is sanitized for safer verification. If you intentionally want sample mailbox/event data in the output:

OUTLOOK_MCP_SMOKE_INCLUDE_DATA=true outlook-ews-mcp-smoke

Docker

docker build -t outlook-ews-mcp .
docker run --rm --env-file .env outlook-ews-mcp

CI/CD

GitHub Actions and GitLab CI both run lint, formatting, type checks, tests, dependency audit, and package builds, using the uv version pinned in pyproject.toml.

Default image tagging behavior:

Development

uv sync --extra dev
uv run ruff check .
uv run pytest -q

Project notes

• The implementation is centered around a single ExchangeClient abstraction so auth, transport, retries, and error mapping stay centralized.
• Errors are returned in a structured JSON form suitable for MCP isError=true handling.

Contributing

Bug reports and PRs are welcome — see CONTRIBUTING.md for how to set up a dev environment and run the test suite without a real Exchange server. For vulnerability reports, see SECURITY.md.

License

MIT — see LICENSE.