# 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

```bash
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):

```bash
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):

```json
{
  "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:

```bash
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.