ews-outlook-mcp

Personal MCP server that lets Claude read and manage an on-prem Outlook/Exchange mailbox via EWS (Exchange Web Services) with NTLM authentication — no dependency on OAuth or Microsoft 365, built for pure on-prem Exchange (no Microsoft 365/Graph).

Exposed tools

• ews_list_inbox — lists the most recent Inbox messages
• ews_search_inbox — searches the Inbox by subject
• ews_get_message — fetches the full body of a message
• ews_reply_message — replies (or reply-all) to an existing message
• ews_send_message — composes and sends a new email
• ews_move_message — moves a message to another folder (archive, etc.)
• ews_list_calendar — calendar events between two dates
• ews_create_event — creates a calendar event/meeting, with optional attendees
• ews_update_event — reschedules/edits the time, subject, or location of an existing event
• ews_add_attendee — adds an attendee to an existing event without touching the rest
• ews_accept_event / ews_decline_event — responds to received meeting invitations
• ews_delete_event — deletes a calendar event (sends a cancellation to attendees by default)
• ews_resolve_contact — looks up a name in the GAL (corporate address book) to get their email before inviting them
• ews_today_summary — unread messages + today's events, at a glance
• ews_forward_message — forwards a message to new recipients with an optional comment
• ews_flag_message — flags/unflags/completes the follow-up flag on a message
• ews_list_folders — lists mailbox folders (including custom ones) with their unread counts

Installation

git clone git@github.com:devsergioherrera/Outlook-Exchange-MCP-Server.git
cd Outlook-Exchange-MCP-Server
npm install
npm run build

Installing for a non-technical user (with Claude Desktop)

To hand this server to another person (not a copy of the same credentials — each user needs their own), the only requirement is having Node.js installed (https://nodejs.org, LTS version — an officially signed installer, which usually clears corporate policies without issue) and Claude Desktop having been opened at least once.

Steps:

1. Copy this whole folder (without node_modules, without .env, without dist) to the target machine — zip, USB, whatever works. node_modules and dist regenerate on their own; .env gets written locally with that person's own credentials.
2. Double-click Instalar.bat.
3. The script (setup.ps1):
   • Verifies Node.js is installed (if not, it warns and stops).
   • Runs npm install and npm run build.
   • Interactively asks for the Exchange URL, username, and password, and saves them to a local .env file (never sent anywhere — it just stays on that machine's disk).
   • Automatically registers the server in %APPDATA%\Claude\claude_desktop_config.json (creates the mcpServers.ews-outlook entry pointing at dist\index.js with the --openssl-legacy-provider flag), with no manual JSON editing required.
4. Claude Desktop needs to be fully quit (including the system tray icon) and reopened afterward.

None of this requires admin rights or running an unsigned .exe — just Node.js (signed, standard installer) and a local PowerShell script, which tends to sail through corporate IT policies that do block loose executables.

Setting up credentials

The .env file needs to be created manually (never paste a password into a chat with an AI assistant):

cp .env.example .env
notepad .env

Fill in EWS_PASSWORD with the account's domain password. The .env file is in .gitignore and must never be pushed to any repository.

Registering the server in Claude Code

Add this to the MCP server config (claude mcp add or the corresponding config file). Requires the --openssl-legacy-provider flag (see "Technical notes" below — without it, NTLMv2 authentication fails on Node 17+ because of the MD4 hash being disabled in OpenSSL 3.x):

{
  "mcpServers": {
    "ews-outlook": {
      "command": "node",
      "args": ["--openssl-legacy-provider", "C:\\path\\to\\Outlook-Exchange-MCP-Server\\dist\\index.js"]
    }
  }
}

Or, from an interactive Claude Code session:

claude mcp add ews-outlook -- node --openssl-legacy-provider C:\path\to\Outlook-Exchange-MCP-Server\dist\index.js

Restart Claude Code so it picks up the new server.

.env credentials format

• EWS_HOST: only the base host of the on-prem Exchange, e.g. https://mail.yourcompany.com — without a trailing /EWS/Exchange.asmx (node-ews builds that path internally; adding it manually makes calls fail with HTTP 400: Bad Request).
• EWS_USERNAME: only the Windows/domain username, e.g. jdoe — no domain prefix (yourcompany.com\jdoe produces an incorrect NTLMv2 hash and Exchange responds with HTTP 401: Unauthorized; the domain is negotiated automatically, coming from the server's own NTLM challenge).
• EWS_PASSWORD: the account's domain password, as-is.

Technical notes (fixes already applied — leave alone unless the reason is clear)

• Patch to ntlm-client (patches/ntlm-client+0.1.1.patch, applied automatically by npm install via postinstall: patch-package): the library (unmaintained) has two compatibility bugs with IIS 10 / modern Exchange:
  1. decodeType2Message received the entire response object instead of the WWW-Authenticate header string, and hasOwnProperty('headers') silently failed on that object → every NTLM auth attempt failed with the generic message "The server didnt respond properly".
  2. The regex extracting the NTLM token required the header to start with NTLM (/^NTLM .../), but IIS returns WWW-Authenticate with several schemes together (NTLM <token>, Negotiate or Negotiate, NTLM <token>), so the anchored rule failed depending on order. The ^ was removed.
• --openssl-legacy-provider: NTLMv2 depends on MD4, which OpenSSL 3.x (shipped with Node 17+) disables by default. Without this flag, the final handshake step (createType3Message) blows up with error:0308010C:digital envelope routines::unsupported.

Security notes

• The EWS endpoint is usually https://<exchange-server>/EWS/Exchange.asmx, over HTTPS/443 — not to be confused with other ports the organization might use for SMTP or other services on the same server.
• If the Exchange certificate is self-signed, the HTTPS connection may fail certificate validation. If that happens, confirmation is needed before disabling TLS verification — it's not a default fix to apply.
• ews_reply_message sends a real email immediately (SendAndSaveCopy). There's no additional confirmation at this server's level — the confirmation happens in the Claude chat before the tool is invoked.