Claude Hotmail Connector

A local 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. If you turn it on, Claude can also send email, but only after you confirm each one in your browser.

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

Status: v1.0, stable. The connector ships as a Claude Desktop extension (.mcpb) for Windows, macOS and Linux (only Windows is tested and supported by the maintainer; see Platforms). What changed is in the changelog, the requirements are in spec v2, and further work is tracked in the open issues.

How it works — local stdio

The connector is a local stdio MCP server (spec v2 §4). Claude Desktop (as an extension) or Claude Code / VS 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 no Claude ↔ server OAuth. The only sign-in is to Microsoft: a native public-client OAuth 2.0 authorization-code + PKCE flow with a loopback redirect, opened in your browser the first time a tool needs it. No client secret is involved.

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

Because it runs locally, it works in Claude Desktop and Claude Code / VS Code on the same PC. It does not work in claude.ai on the web or mobile; that would need a remote mode, which isn't planned (#58, deferred).

Related MCP server: Outlook MCP Server

Tools

Mail is read-only unless you turn sending on (Sending email), and then every email is shown to you in your browser and sent only when you click Send there. Calendar writes never add attendees or send invitations. There is no hard-delete. cancel_event moves an event to Outlook's Deleted Items, and only after three checks:

• you've confirmed it and the event's exact title matches;

• the event has no attendees, since deleting a meeting could email cancellations;

• it isn't recurring.

update_event likewise refuses events with attendees, because changing a meeting emails its attendees.

A few behaviours worth knowing:

• Junk and Deleted are left out. Across all folders, list_messages leaves out Junk Email and Deleted Items, and the folders beneath them, unless you ask for them. Mail in Junk is flagged as such, so phishing can't pass for a real booking.

• Attachments: get_attachment reads text, HTML, calendar (.ics) and PDF attachments. For a PDF it reads the text of the first 30 pages, in an isolated worker with time and memory limits. Password-protected and scanned PDFs (no text layer) can't be read, nor can images or other binary files. Size limits: 5 MB for PDFs, 1 MB for other files. Open anything refused from the message in Outlook.

• Times use your time zone. find_free_time and the other calendar tools work in your computer's time zone unless you name another, with daylight saving applied. All-day events count as whole days in that zone.

Full tool contracts are in spec v2 §7.

Sending email (optional)

Off by default. When it's on, Claude can send new emails, and replies to the person who sent you a message, but only after you confirm each one:

1. Claude prepares the email, and the connector opens a page in your browser showing exactly what will be sent: To, Cc, Subject and the whole text. Anyone who has never emailed you is flagged.

2. Nothing is sent until you click Send on that page. Don't send cancels it, and the page stops working after 5 minutes. Claude never sees the page's link, so it can't confirm for you.

3. Claude is told whether you sent or cancelled it.

To turn it on, tick Allow sending email under Settings → Extensions → Hotmail Connector, or set ALLOW_SEND_MAIL=true when running from source. Then:

• Fully restart Claude Desktop (Quit from the tray icon, then reopen it). Claude Desktop keeps using its earlier list of tools in chats until it restarts, so Claude won't see the send tools yet.

• The first time you send, Claude will say your sign-in doesn't include permission to send. Ask it to sign out (sign_out) and try again: Microsoft will ask you to allow sending.

Plain text only, to at most 10 people. Forwarding, reply-all, attachments and BCC aren't supported, since they're the easiest ways to leak mail. Replies go to the message's Reply-To address if it has one, else its sender, and don't quote the original.

Step 1: register your own Microsoft Entra application

Every user needs their own registration; the connector doesn't ship a shared one, so each user owns their own Microsoft access. Registering is free, but it needs a Microsoft Entra tenant, and a personal account doesn't come with one. If you don't have a tenant, create a free one first (typically by signing up for a free Azure account).

Shortcut: from a source checkout, pwsh ./scripts/register-app.ps1 does all of the steps below and prints the client ID. It needs the Azure CLI. On Windows, install it with winget install -e --id Microsoft.AzureCLI, open a new terminal, and sign in with az login --allow-no-subscriptions. The flag is needed because a free tenant usually has no Azure subscription; add --tenant <your-tenant> if you belong to several. Use the script from v0.2.1 or later: the earlier one created the registration without its API permissions listed.

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 "Personal Microsoft accounts only". That's what the connector is for (hotmail.com / outlook.com / live.com), and it matches the default MICROSOFT_TENANT=consumers. Work/school accounts are served by Claude's official Microsoft 365 connector. To allow them anyway, pick the multitenant + personal option instead and set MICROSOFT_TENANT=common.

4. Redirect URI: select platform "Public client/native (mobile & desktop)" and enter http://localhost. Microsoft allows any loopback port for native clients, so you don't need a specific port.

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. If you'll turn sending on, add Mail.Send too. A personal account doesn't need admin consent; you consent at sign-in.

Step 2a: install in Claude Desktop (extension)

1. Download hotmail-connector.mcpb from the latest release. You can verify it against SHA256SUMS.txt, or check where it was built, with the GitHub CLI: gh attestation verify hotmail-connector.mcpb --repo TGoodhew/Claude-Hotmail-Connector.

2. In Claude Desktop, open Settings → Extensions → Advanced settings → Install Extension…, choose the downloaded file, then Install. (Double-clicking it, or dragging it onto the Extensions page, may also work in some versions; dropping it on a chat only attaches it to the chat.)

3. Enter your Application (client) ID from step 1. You can change it later under Settings → Extensions → Hotmail Connector. Make sure the extension is switched on there. If you also run the connector from source (step 2b), use the same client ID. On Windows each keeps its own saved sign-in, because Claude Desktop is an MSIX app (see Security).

4. Ask Claude something that needs your mailbox or calendar. The first time, a Microsoft sign-in opens in your browser. Finish it within about 45 seconds and that request carries on; otherwise ask again once you've signed in.

Updating to a newer release: install the new .mcpb the same way, over the old one. If Claude Desktop asks for your client ID again, enter the same one. What changed is in the changelog. Claude Desktop only replaces an installed extension with a newer version number: a different build with the same version (e.g. one you built yourself) is treated as already installed, so uninstall first, or give the build a new version.

Upgrading from the v0.1.0 Windows installer:

1. Uninstall Claude Hotmail Connector from Windows Settings → Apps. That removes its Claude Desktop entry; keeping both would show every tool twice.

2. Install the extension with your own client ID, then sign in again. v0.1.0's shared registration has been deleted, so v0.1.0 can no longer sign in (#68).

More detail, including how the bundle is built, is in docs/packaging.md.

Step 2b: run from source (Claude Code / VS Code)

Prerequisites: Node.js 22.12 or later; Node.js 24 LTS is recommended, and CI builds and releases on it. CI also tests on 22.12, the minimum. Node 20 is no longer supported: it reached end-of-life in April 2026 (#148).

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

Then point your client at dist/index.js and pass your client ID in the server's environment.

Claude Code:

claude mcp add --scope user --env MICROSOFT_CLIENT_ID=<your-client-id> --transport stdio \
  hotmail-connector -- node /path/to/Claude-Hotmail-Connector/dist/index.js

Keep --transport stdio where it is, between the --env value and the server name. --env accepts several KEY=value pairs, so without something in between, the name is read as another pair.

VS Code: use Command Palette → "MCP: Add Server…" → Command (stdio), or copy .vscode/mcp.json.example to .vscode/mcp.json and edit the path and client ID:

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

(Claude Desktop can also run a source checkout through claude_desktop_config.json, see examples/claude_desktop_config.example.json. The extension is simpler.)

You don't need to sign in first: the first tool call opens the Microsoft sign-in in your browser. From a source checkout you can also sign in, check or reset explicitly (with MICROSOFT_CLIENT_ID set, e.g. in a .env in the checkout root, see .env.example. It's only ever read from there, never from the folder you launch from):

node dist/index.js login     # browser sign-in, caches the token
node dist/index.js whoami    # prints your name and account, e.g. Jane Doe <jane@outlook.com>
node dist/index.js logout    # removes the saved sign-in (token cache and key)

On Windows, Claude Desktop (a Microsoft Store/MSIX app) keeps the extension's sign-in separate from the checkout's (see Security), so logout doesn't sign it out there.

Configuration

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 uses list_messages / get_message to read the confirmations and confirms the details with you. It then calls create_event for each booking (and the travel blocks) at the correct local times, with no duplicates if it retries.

More things to ask:

• "Read the calendar invite attached to my hotel booking email." The connector uses get_attachment to read the .ics file's events.

• "What's the booking reference in the PDF attached to my flight confirmation?" get_attachment reads the PDF's text.

• "Find me a free hour on Thursday between 9 and 5 Berlin time." This uses find_free_time in Europe/Berlin, with your events converted across time zones and daylight saving.

• "What's in my Junk folder from this week?" This is list_messages with folder: junkemail; Claude is told those messages were judged spam.

Security

• Least privilege: Mail.Read (read-only) + Calendars.ReadWrite. Mail.Send only if you turn sending on; never Mail.ReadWrite, no hard delete, no attendees/invitations.

• No client secret: a 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; elsewhere $XDG_STATE_HOME/claude-hotmail-connector if that's set, else ~/.claude-hotmail-connector). Claude for Windows is a Microsoft Store (MSIX) app, so Windows keeps the extension's copy in a private folder for Claude: %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Local\claude-hotmail-connector. The extension and a source checkout therefore sign in separately, and logout doesn't sign Claude Desktop out; ask Claude to sign out (sign_out) for that (#176). On Windows the encryption key is protected with DPAPI, so only your Windows account on this PC can unlock it; copying the folder elsewhere isn't enough. On macOS/Linux the key is an owner-only file in the same folder: Keychain/libsecret support isn't planned, but a PR adding it is welcome (#83). Tokens are never committed, logged or returned to the client.

• Logging: structured logs go to stderr (stdout is reserved for MCP JSON-RPC) and are scrubbed of tokens, Authorization headers, OAuth codes, secrets, your account name and any email address. They never include what's in your emails or events. With Write a log file on (LOG_FILE), they also go to connector.log (see Troubleshooting).

• Email (and others' invites) are untrusted input: they're written by strangers and may try to steer the model. Unless you turn sending on, the connector can't send mail; when it's on, every email waits for your click on the connector's own page, which the model can't reach. There are no attendees, and no changing or deleting meetings with attendees. Writes and deletes are marked destructive so Claude asks before running them, but only if your client's tool permissions ask. Don't auto-approve the calendar write tools. Claude Desktop 3.1623.4 doesn't show these approval prompts for extension tools at all (#138, reported to Anthropic), so read what Claude says it will change before it does it. The full threat model is in spec v2 §9.2. Review what Claude proposes before approving calendar changes.

• Timezone-correct writes: events are sent as local wall-clock time + an IANA time zone (never a UTC Z with a named zone), so they land at the intended local time.

Known security issues are tracked under the area:security label. To report a vulnerability, use private reporting as described in SECURITY.md; please don't open a public issue.

Troubleshooting

• Seeing what the connector did: Claude Desktop doesn't keep the extension's logs, so turn on Write a log file under Settings → Extensions → Hotmail Connector, then restart Claude Desktop fully (Quit from the tray icon). The log is connector.log in %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Local\claude-hotmail-connector (the folder Windows gives Claude Desktop, #176), or in %LOCALAPPDATA%\claude-hotmail-connector from a source checkout with LOG_FILE=true. Each line starts with the time (UTC) and the process id. It never grows past 2 MB: when it would, the older half is dropped. Signing out leaves it in place; delete it by hand if you like. Set LOG_LEVEL=debug in a source checkout for more detail.

• AADSTS50020 / "account does not exist in tenant" / personal account rejected: the app registration doesn't accept personal accounts. Set its account type to Personal Microsoft accounts only (or multitenant + personal) per step 1.3.

• AADSTS9002331 / "configured for use by Microsoft Account users only": a personal-only registration is being used with MICROSOFT_TENANT=common. Use the default, consumers.

• A work/school account can't sign in: expected with the default consumers tenant. See step 1.3 for the multitenant option.

• 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 a 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.

• "No Microsoft app registration is configured": no client ID is set. Enter it in Claude Desktop → Settings → Extensions → Hotmail Connector, or set MICROSOFT_CLIENT_ID in your client's server config (step 2b).

• A tool says to finish signing in, or "sign-in is required": finish the Microsoft sign-in in the browser window that opened, then ask Claude to retry. If no window appeared, check that a default web browser is set; from a source checkout you can also run node dist/index.js login. After a cancelled sign-in, the connector waits 30 seconds before opening another window.

• "Microsoft refused the saved sign-in": the saved sign-in expired or was revoked, or it was made with a different client ID. Outside Windows, a common cause is giving Claude Desktop and a source checkout different client IDs while they share one saved sign-in, so use the same ID in both. Then sign in again: ask Claude, or run node dist/index.js login.

• "Sending email is turned on, but your Microsoft sign-in doesn't include permission to send": ask Claude to sign out (sign_out), then try again. Microsoft will ask you to allow sending.

• No confirmation page appears when sending: check that a default web browser is set. Nothing is sent without the page.

• v0.1.0 can't sign in any more: its shared registration was deleted. Upgrade as described in step 2a, with your own client ID.

• Claude changes or deletes calendar events without asking: Claude Desktop 3.1623.4 doesn't show approval prompts for extension tools (#138). The connector's own guards still apply (see Tools).

• find_free_time shows part of an all-day busy day as free: fixed in v0.2.1 (#158); update the extension.

• Every tool appears twice: you have both the extension and an older installer/manual config entry. Uninstall the v0.1.0 installer, or remove the hotmail-connector entry from claude_desktop_config.json.

• npm install times out or 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   (format:check in CI)
npm run check:text      # reject raw control characters in tracked files (CI)
npm test                # vitest (unit + in-memory + built-subprocess smoke)
npm run test:coverage   # the same, failing below the coverage thresholds (CI)
npm run test:live       # opt-in: real Graph, your account (after `node dist/index.js login`)
npm run build:mcpb      # Claude Desktop extension -> build/hotmail-connector.mcpb

Layout (tests are colocated as src/**/*.test.ts):

• src/index.ts: CLI and stdio entry (login, logout, whoami; default = server), with src/cli.ts (argument parsing). src/mcp.ts: server assembly. src/pdf-worker.ts: the isolated PDF text extractor.

• src/auth: Microsoft OAuth (PKCE + loopback, on-demand sign-in) and the encrypted token cache (DPAPI-protected key on Windows).

• src/graph: Graph client (auth, retries, paging) plus the mail, attachments, calendar, free/busy and user modules.

• src/tools: zod schemas and thin tool handlers.

• src/send: the browser confirmation page that every email waits on when sending is on.

• src/util: time zones, HTML-to-text, iCalendar parsing, file retries, logging and the log file, errors.

• scripts/: build-mcpb.mjs (extension), check-text.mjs, test-live.mjs, register-app.ps1.

• assets/: the extension icon (SVG source and the PNG the bundle uses).

Requirements, design & roadmap

• docs/personal-outlook-mcp-connector-requirements.md: the build spec, v2 (tools, Graph, auth, security, timezone, packaging, decision log). Requirements not yet implemented link to their tracking issues.

• docs/packaging.md: the Claude Desktop extension (.mcpb): install, upgrade, build.

• docs/local-hosting-investigation-and-requirements.md: the original local-hosting investigation (superseded by spec v2; kept for the record).

• CHANGELOG.md: what changed in each release.

• Roadmap: everything planned is done as of v1.0. The Spec v2 epic (#66) and the follow-up list (#150) are closed, and a remote mode for claude.ai is deferred (#58). Anything new is in the open issues.

Platforms

The maintainer uses and tests the connector on Windows only. The extension also builds for macOS and Linux, and CI runs the tests on Linux, but nothing on those platforms has been tested by hand, and no macOS/Linux-specific work is planned. Known gaps there: the saved sign-in's key isn't protected by the OS keychain (#83), a rare lock-recovery race on macOS (#131), and setup notes for those platforms (#56). If you use macOS or Linux, PRs are very welcome.

Support & contributing

This is a personal, open-source tool, community-supported on a best-effort basis with no SLA and no hosted service. You run your own copy with your own Microsoft app registration. See SUPPORT.md for how to get help, CONTRIBUTING.md before opening a PR, and SECURITY.md for private vulnerability reporting.

License

MIT © 2026 Tony Goodhew