exchange-mcp-server

A Model Context Protocol server that lets Claude (or any MCP client) work with a Microsoft Exchange mailbox over EWS: read and search mail, file and clean up messages, read and edit the calendar, check people's free/busy, find and book meeting rooms, and send email with attachments, signatures and delayed delivery.

繁體中文說明 → README.zh-TW.md

Features

Design points:

• Dry run by default. Every tool that sends, deletes or edits takes dry_run (default true) and returns a preview first. The model has to call again with dry_run=false, which gives you a confirmation step.

• Recoverable deletes. Messages, events and meeting requests are moved to Deleted Items, never hard-deleted.

• Free/busy without delegation. Availability and room search use GetUserAvailability, so you do not need delegate access to colleagues' or rooms' calendars.

• Rooms that Exchange does not describe. A local catalog adds capacity, floor and equipment, and supports organisations whose meeting rooms are ordinary user mailboxes (invite_as: "attendee").

• Attachment sandbox. Local files can only be attached from folders listed in EXCHANGE_ATTACHMENT_DIRS, so a prompt-injected email cannot make the model mail out arbitrary files.

• Read-only and no-send modes for cautious deployments.

• Works with mcp 1.x and 2.x, Python 3.10+.

Related MCP server: OWA Exchange MCP Server

Install

pip install "exchange-mcp-server @ git+https://github.com/Rirychh/exchange-mcp-server"
# with Exchange Online delegated sign-in support:
pip install "exchange-mcp-server[oauth] @ git+https://github.com/Rirychh/exchange-mcp-server"

Or run without installing, using uv:

uvx --from git+https://github.com/Rirychh/exchange-mcp-server exchange-mcp-server check

Configure

Copy .env.example to one of these locations (first match wins) and fill it in:

1. the path in EXCHANGE_MCP_ENV_FILE

2. ./.env

3. ~/.config/exchange-mcp/.env

4. ~/exchange_mcp.env (legacy)

Real environment variables always override the file. Then test it:

exchange-mcp-server check

Settings

Authentication modes

On-premises Exchange (ntlm / basic) — set EXCHANGE_SERVER, EXCHANGE_EMAIL, EXCHANGE_PASSWORD and usually EXCHANGE_DOMAIN.

Exchange Online, signed-in user (oauth_delegated)

1. In Entra ID, register an app; under Authentication enable Allow public client flows.

2. Add the delegated API permission Office 365 Exchange Online → EWS.AccessAsUser.All and grant consent.

3. Set EXCHANGE_AUTH=oauth_delegated, EXCHANGE_CLIENT_ID, EXCHANGE_TENANT_ID, EXCHANGE_EMAIL.

4. Run exchange-mcp-server login once and follow the device-code prompt. Tokens refresh silently afterwards.

Exchange Online, app-only (oauth_app) — app registration with the application permission full_access_as_app and a client secret; the server impersonates EXCHANGE_EMAIL. Scope it with an application access policy.

Use with Claude Desktop

Add to claude_desktop_config.json (see examples/):

{
  "mcpServers": {
    "exchange": {
      "command": "exchange-mcp-server",
      "env": { "EXCHANGE_MCP_ENV_FILE": "C:\\Users\\you\\.config\\exchange-mcp\\.env" }
    }
  }
}

With uv: "command": "uvx", "args": ["--from", "git+https://github.com/Rirychh/exchange-mcp-server", "exchange-mcp-server"].

Claude Code: claude mcp add exchange -- exchange-mcp-server.

Room catalog

EWS has no room capacity, and some companies create rooms as normal user accounts so they never appear in room lists. Describe them in rooms.json (example):

{
  "rooms": [
    { "email": "room-3a@example.com", "name": "Room 3A", "capacity": 8, "floor": "3F",
      "equipment": ["TV", "webcam"] },
    { "email": "boardroom@example.com", "name": "Boardroom", "capacity": 20, "invite_as": "attendee" }
  ]
}

• invite_as: "resource" (default) books the room as a resource; "attendee" invites it as a required attendee.

• Rooms without capacity are never filtered out by min_capacity; they are listed under capacity_unknown.

• The file is re-read automatically after you edit it.

Example prompts

• "Which of my unread emails from this week need a reply?"

• "Find a room for 8 people tomorrow 14:00–15:30 and check whether Ana and Ben are free."

• "File every newsletter in my inbox into Inbox/Newsletters (preview first)."

• "Put an all-day 'Design review' on 3 Nov in my Project X calendar, no invitations."

• "Reply to the latest mail from facilities and attach report.pdf from my Reports folder."

Security notes

• Keep the env file private (chmod 600); it holds your password or client secret.

• Mail content is untrusted input to the model. Keep dry_run previews, EXCHANGE_ATTACHMENT_DIRS and, if in doubt, EXCHANGE_ALLOW_SEND=false or EXCHANGE_READ_ONLY=true.

• The server talks only to your Exchange endpoint (and Microsoft login for OAuth).

Development

pip install -e ".[dev]"
pytest
ruff check .

Tests use mocks and need no Exchange server. Exchange access lives in backend.py (EwsBackend); tool definitions in server.py only call backend methods, so another backend (e.g. Graph) can implement the same interface.

License

MIT