Claude Hotmail Connector

A locally hosted Model Context Protocol (MCP) server that lets Claude read email and read/write calendar events in a personal Microsoft account (@hotmail.com / @outlook.com / @live.com) via the Microsoft Graph API.

Claude's official Microsoft 365 connector only supports work/school (Microsoft Entra) accounts and rejects personal Microsoft accounts. This project fills that gap for a single user, running entirely on your own machine.

Deployment model — Mode A: local stdio

Per the local-hosting investigation, this connector is built as a local stdio MCP server: Claude Desktop or VS Code / Claude Code launches it as a subprocess and talks to it over stdin/stdout. There is no public URL, no tunnel, and no hosting cost — and the entire downstream OAuth machinery (PRM/DCR/PKCE for the Claude ↔ server hop) drops away. Only the upstream Microsoft sign-in is needed, done via a native public-client OAuth 2.0 authorization-code + PKCE flow with a loopback redirect.

Claude Desktop / VS Code ──stdio──▶ this server ──HTTPS──▶ Microsoft Graph (personal account)
        (MCP client)                (local subprocess)        graph.microsoft.com/v1.0

Tools

Tool	Purpose	Graph permission
whoami	Confirm the connected account	User.Read
list_messages	Search/list mail (find booking confirmations)	Mail.Read
get_message	Read one email as text	Mail.Read
list_events	Read the calendar over a date range	Calendars.Read
create_event	Add a calendar event (timezone-correct, idempotent)	Calendars.ReadWrite
update_event	Edit a calendar event	Calendars.ReadWrite

Mail is read-only (no Mail.Send). There is no hard-delete tool. cancel_event (event deletion) is deliberately deferred as a gated/destructive action pending explicit approval.

Install (recommended)

The easy path — no Node, no Azure, no config files. On Windows, download the latest HotmailConnectorSetup.exe (or the portable hotmail-connector.exe) from Releases and run it. The installer auto-configures Claude Desktop and runs the one-time Microsoft sign-in for you — the build embeds a shared public-client id, so there's nothing to register or configure.

• Windows shows an "unknown publisher" warning (the build is unsigned, by design) — click More info → Run anyway.
• After it finishes, fully quit Claude Desktop from the system tray (closing the window only minimises it) and reopen it.

See docs/installer.md for the details, the SmartScreen note, and how the packages are built. Want to build or run it yourself instead? Use the developer setup below.

Manual / developer setup

Prerequisites

• Node.js 20+ (node --version).
• A personal Microsoft account (@hotmail.com / @outlook.com / @live.com).
• Claude Desktop and/or VS Code (with MCP support) on the same machine.
• A one-time Microsoft Entra app registration (free — see below).

1. Register a Microsoft Entra application (one-time, optional)

You can skip this — the build ships with a bundled shared client id. Only do it to bring your own Entra registration. (Maintainers: scripts/register-app.ps1 automates it; see docs/installer.md.)

The connector signs in as a public/native client — no client secret is ever used or stored.

1. Go to the Entra admin center → App registrations → New registration.
2. Name: e.g. Claude Hotmail Connector.
3. Supported account types: choose “Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).” This is what allows hotmail.com / outlook.com sign-in.
4. Redirect URI: select platform “Public client/native (mobile & desktop)” and enter http://localhost. (Microsoft allows any loopback port for native clients, so a specific port is not required.)
5. Click Register, then copy the Application (client) ID.
6. Under Authentication, confirm the platform is Mobile and desktop applications with http://localhost, and that “Allow public client flows” is Yes. Do not create a client secret.
7. Under API permissions → Add a permission → Microsoft Graph → Delegated permissions, add: openid, profile, email, offline_access, User.Read, Mail.Read, Calendars.ReadWrite. (Admin consent is not required for a personal account — you consent at first sign-in.)

2. Install & build

git clone https://github.com/TGoodhew/Claude-Hotmail-Connector.git
cd Claude-Hotmail-Connector
npm install
npm run build          # produces dist/index.js

3. Configure (optional)

The build ships with a bundled shared client id, so this is optional. To use your own Entra registration (step 1), set it via a local .env:

cp .env.example .env
# edit .env and set MICROSOFT_CLIENT_ID=<the Application (client) ID from step 1>

Configurable environment variables (see .env.example):

Variable	Default	Notes
MICROSOFT_CLIENT_ID	(required)	Entra app registration client id.
MICROSOFT_TENANT	common	common enables personal + work accounts.
DEFAULT_TIMEZONE	Australia/Brisbane	IANA zone for calendar reads/writes.
LOG_LEVEL	info	debug/info/warn/error (logs to stderr).
MICROSOFT_SCOPES	least-privilege set	Space/comma-separated override.
CLAUDE_HOTMAIL_CACHE_DIR	per-OS profile dir	Where the encrypted token cache lives.

4. Sign in once

node dist/index.js login

This opens your system browser to Microsoft. Sign in with your personal account and consent to the requested permissions. The refresh token is stored encrypted in your user profile (see Security); subsequent runs refresh silently. node dist/index.js logout clears it.

Verify:

node dist/index.js whoami       # should print your name <tony_goodhew@hotmail.com>

5. Wire it into a client

The quickest way is to let the connector configure Claude Desktop for you — the same engine the installer uses:

node dist/index.js setup   # detects Claude Desktop (incl. the Microsoft Store build) and wires it up

Or configure a client manually — the server is launched as a stdio subprocess. Pass MICROSOFT_CLIENT_ID via the client's env only if you're bringing your own registration (otherwise the bundled default is used).

VS Code / Claude Code

Use Command Palette → “MCP: Add Server…” → Command (stdio), pointing node at the built dist/index.js. Or commit-adjacent, copy .vscode/mcp.json.example to .vscode/mcp.json and edit the path/client id:

{
  "servers": {
    "hotmail-connector": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\Users\\Tony\\Source\\Repos\\Claude-Hotmail-Connector\\dist\\index.js"],
      "env": { "MICROSOFT_CLIENT_ID": "<your-entra-app-client-id>" },
    },
  },
}

Claude Desktop

Edit claude_desktop_config.json (see examples/claude_desktop_config.example.json):

{
  "mcpServers": {
    "hotmail-connector": {
      "command": "node",
      "args": ["C:\\Users\\Tony\\Source\\Repos\\Claude-Hotmail-Connector\\dist\\index.js"],
      "env": { "MICROSOFT_CLIENT_ID": "<your-entra-app-client-id>" },
    },
  },
}

Restart the client. The connector's tools should appear. If you have not run login yet, do so once in a terminal first (the server does not pop a browser on its own).

Usage example

“Find my Monsoon Aquatics and Macadamias Australia booking confirmation emails, then add each to my calendar with 15-minute travel-time blocks before and after.”

Claude will use list_messages / get_message to read the confirmations, confirm the details with you, then call create_event for each booking (and the travel blocks) at the correct Australia/Brisbane local times — with no duplicates if it retries.

Security

• Least privilege: Mail.Read (read-only) + Calendars.ReadWrite. No Mail.Send, no hard-delete, cancel_event deferred.
• No client secret: public/native client using PKCE.
• Token storage: the refresh token is encrypted with AES-256-GCM in your user profile (%LOCALAPPDATA%\claude-hotmail-connector on Windows, ~/.claude-hotmail-connector otherwise), with the key in a sibling owner-only file. Never committed, never logged, never returned to the client.
• Logging: structured logs go to stderr only (stdout is reserved for MCP JSON-RPC) and are scrubbed of tokens, Authorization headers, OAuth codes, and secrets.
• Timezone-correct writes: events are sent as local wall-clock + IANA time zone (never a UTC Z with a named zone), so they land at the intended local time.

Troubleshooting

• AADSTS50020 / “account does not exist in tenant” / personal-account rejected: the app registration is not set to multitenant + personal accounts, or you used a tenant other than common. Recreate/adjust per step 1.3 and keep MICROSOFT_TENANT=common.
• AADSTS7000218 / “client_assertion or client_secret required”: the app is registered as a confidential/web client. Register it as a public client with “Allow public client flows” = Yes (step 1.6).
• redirect_uri mismatch: add http://localhost under the Mobile & desktop platform.
• Event lands an hour off: always pass local wall-clock dateTime (e.g. 2026-07-20T10:00:00) with an IANA timeZone; never a Z-suffixed value. The connector rejects Z/offset values for event times.
• “Not signed in” from a tool: run node dist/index.js login once; if it persists, logout then login again to reset the token cache.
• npm install times out / hangs (dead IPv6 route): force IPv4 — NODE_OPTIONS="--dns-result-order=ipv4first --no-network-family-autoselection" npm install.

Development

npm run dev             # rebuild on change (tsup --watch)
npm run typecheck       # tsc --noEmit
npm run lint            # eslint
npm run format          # prettier --write
npm test                # vitest (unit + in-memory + built-subprocess smoke)
npm run build:exe       # Windows: Node SEA single executable (postject via npx)
npm run build:installer # Windows: Inno Setup installer (needs iscc on PATH)

Layout: src/auth (Microsoft OAuth + encrypted token cache), src/graph (Graph client + mail / calendar / user modules), src/tools (zod schemas + thin handlers), src/setup (client auto-config

• the setup/unsetup commands), src/util (time, logging, errors, html), src/mcp.ts + src/index.ts (server assembly + stdio entry).

Requirements & design

The authoritative specifications live in docs/:

• docs/personal-outlook-mcp-connector-requirements.md — the main build spec (tools, Graph, security, timezone).
• docs/local-hosting-investigation-and-requirements.md — why/how to host locally (Mode A stdio, chosen here).
• docs/installer.md — the packaged Windows installer: auto-config engine, one-time register-app, and the SEA/Inno build.

License

MIT © 2026 Tony Goodhew