mcp-outlook

A self-hostable MCP server for on-prem Microsoft Exchange over EWS (Exchange Web Services). Built for air-gapped / no-cloud environments — it talks directly to your internal Exchange server and never touches Microsoft Graph, Azure AD, or a desktop Outlook client.

• Backend: exchangelib (EWS client)

• Framework: FastMCP

• Transport: streamable-http (a standalone HTTP server other internal hosts connect to)

• Auth to Exchange: basic or NTLM (selectable via config)

Two modes

How jwt mode bridges identity. Exchange can't consume your company JWTs (Outlook is PKINIT/Kerberos-based). So the MCP does two separate authentications that never mix:

User --(JWT)--> MCP validates the token, reads the user's email
                MCP --(service account, NTLM)--> Exchange
                MCP --(impersonation header = user's email)--> acts on the user's mailbox

The user's JWT is never sent to Exchange, and no user password/smart-card ever touches the MCP — only the single service credential does. See TODO.md for what admins must set up for jwt mode.

Related MCP server: OWA Exchange MCP Server

Tools

list_emails and search_emails also take unread_only=true to return only unread messages.

Setup

Requires Python 3.11+ and uv.

uv sync                 # create venv + install deps
cp .env.example .env    # then edit .env with your Exchange details
uv run python -m mcp_outlook

The server binds to MCP_HOST:MCP_PORT (default 127.0.0.1:8000) and serves the streamable-http MCP endpoint at /mcp.

Local beta testing (no admin setup needed)

Run against your own mailbox with your own username/password — no JWT, no impersonation, no service account, no smart card:

# in .env:
OUTLOOK_AUTH_MODE=static          # the default
OUTLOOK_EWS_ENDPOINT=https://mail.corp.local/EWS/Exchange.asmx
OUTLOOK_USERNAME=CORP\you
OUTLOOK_PASSWORD=...
uv run python -m mcp_outlook

Configuration

All settings come from environment variables (or a .env file). See .env.example for the full list. The essentials:

Finding your EWS endpoint

The EWS URL is not the OWA (webmail) URL. On the Exchange server:

Get-WebServicesVirtualDirectory | fl Name,InternalUrl,ExternalUrl

In an air-gapped setup you almost always want the InternalUrl.

Testing

Unit tests need no Exchange server (config parsing + serialization only):

uv run pytest

Live smoke test (with a real .env): start the server, connect an MCP client or the MCP Inspector, then call list_folders → list_emails → send_email (to yourself) and confirm receipt. Flip OUTLOOK_AUTH_TYPE between ntlm and basic to confirm whichever your Exchange admin has enabled.

Compose UI (MCP Apps)

draft_email opens an interactive MCP Apps widget — a React composer built into a single self-contained HTML file (src/mcp_outlook/widgets/compose.html). Any MCP Apps-capable host renders it inline in the chat thread.

Widget capabilities:

• To field with inline contact search — type after the last comma to search contacts; pick a result to replace the query with a chip; valid addresses render as labelled chips.

• Send / Discard — Send fires send_email directly from the widget (app-only — the model cannot call it); Discard collapses the card.

• Supersession — opening a new draft greys out any older open draft widget.

• Signature — every draft is pre-seeded with "Written with Airchat" (editable).

Air-gap guarantee: the built HTML (React + bridge JS inlined) ships with the Python package. No external asset requests are made at runtime; Node.js is only needed to rebuild the widget.

Rebuild the widget (dev only)

cd frontend
npm ci
npm run build     # tsc + vite build + artifact copy → src/mcp_outlook/widgets/compose.html

The build script validates no external URLs ended up in the HTML before copying.

Try it visually (standalone dev preview)

cd frontend && npm run dev
# Opens http://localhost:5173 with a mock host — no Exchange needed.
# Type in To, see chips form, contact results appear, Send/Discard collapse the card.

Gotchas

• Basic auth is often disabled on modern Exchange — NTLM is the safer default.

• Internal/self-signed certs require OUTLOOK_CA_BUNDLE, or the connection fails on TLS verification.

• Multi-user (jwt) mode needs one Exchange grant — the service account must hold the ApplicationImpersonation RBAC role. See TODO.md. static mode needs no such grant.

• .env holds a plaintext password. It is git-ignored; also lock down file permissions (chmod 600 .env) on the host.