outlook-evidence-mcp

A read-only Model Context Protocol server that lets an MCP client (Claude Code, Claude Desktop, etc.) search a Microsoft 365 / Outlook mailbox and export messages + attachments to a local folder, recording a chain-of-custody manifest (SHA-256 per file) so the collection is defensible as evidence.

Built for the case where you need to pull a specific set of email threads and their attachments out of Outlook — for litigation, compliance, or analysis — without granting broad, writeable, or tenant-wide access.

Design principles

• Read-only. Requests only the delegated User.Read + Mail.Read Graph scopes. There are no send / delete / modify tools — none exist in the code.

• Your mailbox only. Delegated auth (device-code flow) acts as the signed-in user. No application (app-only) permissions, so it can never read other people's mailboxes.

• No secrets in the repo. You supply your own Entra app IDs via env. Device-code flow means there's no client secret at all. The OAuth token cache and the exported evidence are git-ignored.

• Auditable collection. Every export appends a manifest.jsonl record: message id, internet message id, sender, subject, received time, and the SHA-256 + size of each saved file, plus the retrieval timestamp.

Related MCP server: Microsoft Graph MCP Server

Tools

Messages are exported as .eml (full MIME via Graph /$value) to preserve headers and fidelity.

Prerequisites

• Node.js 18+

• A Microsoft 365 business tenant (personal @outlook.com accounts are not supported by Graph delegated mail here)

• Rights to register an app and grant admin consent in your tenant (or an admin who will)

Setup

1. Register an Entra application (~5 min, one-time)

In portal.azure.com → Microsoft Entra ID → App registrations → New registration:

1. Name: e.g. outlook-evidence-mcp. Supported account types: Accounts in this organizational directory only (single tenant).

2. API permissions → Add a permission → Microsoft Graph → Delegated permissions → add User.Read and Mail.Read → Grant admin consent.

3. Authentication → Advanced settings → Allow public client flows → Yes (enables device-code auth — no client secret, no redirect URI needed).

4. Copy the Application (client) ID and Directory (tenant) ID from the app's Overview.

Conditional Access note: some tenants block the device-code flow via a CA policy. If sign-in is blocked, scope a CA exception for this app registration (an auth-code + localhost redirect variant isn't bundled yet — open an issue if you need it).

2. Install & build

npm install
npm run build      # compiles to dist/

3. Configure

Copy .env.example to .env and fill in your IDs (or pass the same vars via your MCP client config):

AZURE_CLIENT_ID=<application-client-id>
AZURE_TENANT_ID=<directory-tenant-id>
OUTPUT_DIR=./evidence
TOKEN_CACHE_PATH=./.token-cache.json

4. Register with your MCP client

Claude Code:

claude mcp add outlook-evidence \
  -e AZURE_CLIENT_ID=<client-id> \
  -e AZURE_TENANT_ID=<tenant-id> \
  -e OUTPUT_DIR=/absolute/path/to/evidence \
  -- node /absolute/path/to/outlook-evidence-mcp/dist/index.js

Or add it to your client's MCP config JSON:

{
  "mcpServers": {
    "outlook-evidence": {
      "command": "node",
      "args": ["/absolute/path/to/outlook-evidence-mcp/dist/index.js"],
      "env": {
        "AZURE_CLIENT_ID": "<client-id>",
        "AZURE_TENANT_ID": "<tenant-id>",
        "OUTPUT_DIR": "/absolute/path/to/evidence"
      }
    }
  }
}

5. Authenticate (one-time, interactive)

In an interactive session, call the outlook_authenticate tool. It returns something like:

To sign in, use a web browser to open https://microsoft.com/devicelogin and enter the code ABCD-EFGH.

Complete that in your browser. The refreshable token is cached locally; subsequent (including headless) runs won't prompt again until it expires.

Usage

Once authenticated, ask your MCP client to, e.g.:

• "Search Outlook for mail from planet.com about the ISO 8583 spec." → outlook_search

• "Save that whole thread and its attachments to the evidence folder." → outlook_save_thread

Everything lands in OUTPUT_DIR as .eml files + attachments, with an appended manifest.jsonl.

Security & privacy

• Read-only, delegated, single-user. The Entra app registration is the hard boundary — even if you don't trust this code, you consent only to Mail.Read on your own mailbox.

• The token cache (TOKEN_CACHE_PATH) holds live tokens — it is git-ignored and written 0600. Treat it like a credential.

• The evidence folder is git-ignored. Do not commit collected mail.

• The only network egress is https://graph.microsoft.com. No telemetry.

Development

npm run dev        # run from source (tsx)
npm run typecheck  # tsc --noEmit
npm test           # vitest (offline; Graph is mocked — no live calls)

License

MIT — see LICENSE.