Outlook MCP Server

A Model Context Protocol server bridging Claude to Microsoft Outlook + Teams (email, calendar, contacts, tasks, files, Teams meeting recordings + transcripts), deployed on Cloudflare Workers.

Fork this repo, deploy to your own Cloudflare account, register a Microsoft Azure AD app, point Claude.ai at your worker, and Claude can read and write your Microsoft 365 data through natural language.

Built on @bashco/mcp-toolkit — OAuth, per-client bearer tokens, rate limiting, structured logging, typed tool dispatch are all handled by the shared library.

What Claude gets — 39 tools across 7 domains

• Mail: list emails, read email, search, reply, forward, delete, send, move between folders, create draft, update draft, send draft, schedule send
• Calendar: list events, list event occurrences, create, update, delete, cancel event, respond to event
• Contacts: list, create contact, update contact
• Tasks: list task lists, list tasks, create task
• Files: list files, share file
• Teams meetings: list recent recordings (the discovery starting point — finds meetings that have content in the past N days, no inputs needed), find online meeting, list meeting recordings, list meeting transcripts, get transcript content. Each per-meeting tool accepts any of meeting_id, calendar_event_id, or join_url — so scheduled meetings (resolved via event), ad-hoc / Meet-now calls (resolved via join URL pasted from the Teams chat), and direct id lookups all work.
• Conversation: get conversation (full thread)
• Settings: get mailbox settings, set out-of-office

Full live catalogue at the tools/list MCP endpoint after deploy.

How auth works

Two layers:

1. Claude.ai ↔ your worker — standard MCP OAuth 2.0 + PKCE flow. Each Claude client gets a unique bearer token; your MCP_APPROVAL_CODE is what you paste at /authorize once to mint that bearer.
2. Your worker ↔ Microsoft Graph — proxied OAuth. You authorise Microsoft once by visiting /oauth/start on your deployed worker; refresh tokens are stored encrypted at rest in Cloudflare KV. Refresh happens automatically.

Setup — deploy your own copy

Prerequisites

• A Cloudflare account (free plan works)
• Wrangler CLI installed and logged in (wrangler login)
• Node.js 22+
• A Microsoft account (personal, work, or school) with access to register Azure AD apps at entra.microsoft.com

1. Fork and clone

git clone https://github.com/<your-username>/outlook-mcp
cd outlook-mcp
npm install

2. Create the KV namespace

wrangler kv:namespace create OAUTH_KV

Wrangler prints something like:

🌀 Creating namespace with title "outlook-mcp-OAUTH_KV"
✨ Success! Add the following to your configuration file:
[[kv_namespaces]]
binding = "OAUTH_KV"
id = "abc123def456..."

Edit wrangler.jsonc and replace the existing id under kv_namespaces with what wrangler just printed.

wrangler.jsonc is committed by design — Wrangler and the CI deploy both need it, and it holds no secrets (only your KV namespace id, public Azure client id, and worker URL). wrangler.jsonc.example carries the same structure with placeholders if you'd rather start from a clean copy. Real secrets go through wrangler secret put and never appear in this file.

3. Register a Microsoft Azure AD app

1. Go to entra.microsoft.com → Identity → Applications → App registrations → New registration

2. Name: anything (e.g. "Claude Outlook MCP")

3. Supported account types:

   • "Accounts in this organizational directory only" if you want to restrict to one tenant
   • "Accounts in any organizational directory and personal Microsoft accounts" for the broadest support

4. Redirect URI: leave blank for now — you'll come back after Step 6

5. Click Register

6. From the app's Overview page, record:

   • Application (client) ID → this is your MICROSOFT_CLIENT_ID
   • Directory (tenant) ID → this is your MICROSOFT_TENANT_ID (or use the string common for multi-tenant + personal account support)

7. API permissions → Add the following Microsoft Graph delegated permissions:

   • Mail.ReadWrite, Mail.Send
   • Calendars.ReadWrite
   • Contacts.ReadWrite
   • Tasks.ReadWrite
   • Files.Read.All (or Files.ReadWrite.All if you want write-capable file tools)
   • User.Read
   • offline_access (required for refresh tokens)
   • MailboxSettings.ReadWrite
   • Sites.Read.All
   • OnlineMeetings.Read
   • OnlineMeetingRecording.Read.All — admin consent required
   • OnlineMeetingTranscript.Read.All — admin consent required

   After adding the two .Read.All permissions, click "Grant admin consent for [tenant name]" on the API permissions page. Without admin consent, the meeting recording / transcript tools will 403.

8. Certificates & secrets → New client secret → record the value (in 1Password). This is your MICROSOFT_CLIENT_SECRET. You can only see it once — copy immediately.

4. Update wrangler.jsonc

Edit wrangler.jsonc and replace both:

• vars.MICROSOFT_CLIENT_ID — with the Application ID from Step 3.6
• vars.MICROSOFT_TENANT_ID — with the Directory ID from Step 3.6 (or common)

5. Set secrets

Generate a fresh approval code:

openssl rand -base64 32

Store it in a password manager, then push to Cloudflare:

wrangler secret put MCP_APPROVAL_CODE          # paste the value from above
wrangler secret put MICROSOFT_CLIENT_SECRET    # from Step 3.8

Secret	Purpose
MCP_APPROVAL_CODE	One-time code you paste at /authorize to mint a Claude bearer. Also used as the encryption secret for upstream Microsoft tokens at rest — rotating it invalidates stored tokens and forces clean Microsoft re-auth.
MICROSOFT_CLIENT_SECRET	Your Azure AD app's client secret.
SIGNATURE_HTML	Optional. Email signature block appended server-side — see Email signature.
SIGNATURE_LOGO_URL	Optional. Publicly reachable HTTPS URL of the signature logo.

6. First deploy (to learn worker URL)

npm run deploy

Wrangler prints your worker URL — something like https://outlook-mcp.<your-account>.workers.dev. Save it.

7. Update WORKER_URL and the Microsoft redirect URI

Two updates needed:

a) Edit wrangler.jsonc — under vars, replace WORKER_URL with the URL from Step 6.

b) In the Azure AD app (entra.microsoft.com → your app → Authentication → Add a platform → Web), set the redirect URI to <your-worker-url>/oauth/callback. Without this, Microsoft will reject the OAuth flow.

Then redeploy:

npm run deploy

8. Connect Microsoft (one time)

In your browser, visit <your-worker-url>/oauth/start. Paste your MCP_APPROVAL_CODE. You'll be redirected to Microsoft to sign in and grant the scopes from Step 3.7. After consenting, your encrypted upstream tokens land in OAUTH_KV. Refresh happens automatically thereafter.

You can confirm the connection by visiting <your-worker-url>/oauth/status — should say connected: true.

9. Connect Claude.ai

1. In Claude.ai, go to Settings → Integrations → Add MCP server
2. Server URL: <your-worker-url>/mcp
3. Claude.ai redirects you to your worker's /authorize page
4. Paste your MCP_APPROVAL_CODE and confirm
5. You're connected — Claude now has the 38 Outlook + Teams tools available

Email signature

Optional. When configured, the Worker appends your signature at send time so the calling agent never has to reproduce it — it can't be paraphrased, truncated, or forgotten.

Pass include_signature: true to any of send_email, schedule_send, reply_to_email, forward_email, create_draft, update_draft, create_reply_draft, create_reply_all_draft, or create_forward_draft. It defaults to false, so existing callers are unaffected.

For drafts, the signature is injected at draft-creation time, not at send time — send_draft only takes an id and never touches the body. This means the signed body is what you review before sending. On update_draft the flag only applies when you also pass a new body (otherwise there is nothing to sign, and it would replace the draft with a signature-only body); that case is reported in the response notes rather than silently wiping the draft.

Calendar invites

create_calendar_event and update_calendar_event accept the same include_signature flag, appending the signature to the event description. It reuses the same SIGNATURE_HTML block as email — including its marketing call-to-action buttons — so it suits a client-facing invite more than an internal meeting; that is why it is opt-in per event. update_calendar_event follows the same guard as update_draft: the flag only applies when you also pass a new description.

Setup

cp signature-block.example.html signature-block.html   # then edit it
wrangler secret put SIGNATURE_HTML < signature-block.html
wrangler secret put SIGNATURE_LOGO_URL                 # paste your HTTPS logo URL

signature-block.html is gitignored on purpose. The signature is deployment config, not source: a fork that inherited a committed signature would send mail carrying someone else's name, phone number, and booking links. Only the placeholder signature-block.example.html is committed.

The __LOGO_URL__ token inside SIGNATURE_HTML is substituted with SIGNATURE_LOGO_URL at runtime.

The logo must be publicly reachable over HTTPS. Mail clients fetch it from the recipient's machine — it has no access to your network, your Worker's bindings, or any credential you hold. A private, authenticated, or localhost URL renders as a broken image for everyone. If SIGNATURE_LOGO_URL is unset the <img> is dropped entirely rather than emitting a broken src.

If SIGNATURE_HTML is unset the flag is a silent no-op — the mail sends unsigned. An unconfigured deployment never errors.

Behaviour

• Forces HTML. A signature inside a plain-text body renders as visible raw markup, so body_type is overridden to html whenever the flag is set. When you explicitly passed body_type: "text" the override is reported back in the tool response's notes, never applied silently.
• Plain-text bodies are escaped, then newlines become <br>, so your line breaks survive the forced HTML switch and stray < characters can't become markup.
• Idempotent. If the body already carries the signature — recognised by the Worker's own marker or by the signature's distinctive text — it is not appended twice.
• Replies and forwards place the signature above the quoted original, not at the bottom of the whole thread.
• Empty body sends the signature alone, with no leading blank lines.

Security note

The signature is concatenated after the caller's body has been sanitised. This is deliberate and load-bearing: sanitizeOutboundHtml strips every style= attribute (an attribute-only XSS sink), and the signature is built entirely from inline styles, so routing it through the sanitiser would strip the logo sizing, the divider, and the CTA buttons.

The two strings have different trust levels. The body is agent-supplied and untrusted, so it is still fully sanitised. The signature is operator-supplied deployment config set via wrangler secret put — anyone who can set that secret can already change the Worker outright. See src/signature.ts.

Local development

cp .dev.vars.example .dev.vars   # fill in MCP_APPROVAL_CODE + MICROSOFT_CLIENT_SECRET; .dev.vars is gitignored
npm test                          # 171 tests via vitest with workers pool
npm run typecheck                 # tsc --noEmit
npm run dev                       # wrangler dev — local at http://localhost:8787

Endpoints

• GET /.well-known/oauth-authorization-server — OAuth metadata (public)
• GET /.well-known/oauth-protected-resource — Resource metadata (public)
• GET /authorize — Approval-code paste page (public)
• POST /approve — Approval-code submission (rate-limited)
• POST /token — OAuth token exchange (rate-limited)
• POST /register — Dynamic client registration per RFC 7591 (rate-limited)
• GET /oauth/start — Begin Microsoft OAuth flow (gated by MCP_APPROVAL_CODE)
• GET /oauth/callback — Microsoft OAuth redirect target
• GET /oauth/status — Check connection state (gated by MCP_APPROVAL_CODE)
• POST /mcp — JSON-RPC tool dispatch (bearer-protected, rate-limited)

Stack

• Cloudflare Workers (compatibility_date 2025-04-28, nodejs_compat)
• TypeScript (strict)
• Hono v4
• Zod v4
• Vitest with @cloudflare/vitest-pool-workers (171 tests)
• @bashco/mcp-toolkit — shared OAuth/crypto/rate-limit/dispatch plumbing

Security architecture highlights

• Two-pass HTML sanitiser with entity normalisation on outbound email previews
• SSRF guard with 32-bit-IP normalisation on outbound HTTP
• Microsoft Graph odata error envelope parsing for structured error returns
• Per-domain tool files under src/tools/ (mail, calendar, contacts, tasks, files, meetings, settings) for auditability

Continuous deployment

.github/workflows/deploy.yml runs vitest run on every push to main, then deploys to Cloudflare. To enable on your fork, set two repository secrets:

• CLOUDFLARE_API_TOKEN — create at dash.cloudflare.com/profile/api-tokens (use the "Edit Cloudflare Workers" template)
• CLOUDFLARE_ACCOUNT_ID — find at the bottom-right of your Cloudflare dashboard

Contributing

Issues and PRs welcome at github.com/doublebash/outlook-mcp.

For changes to the underlying OAuth/crypto/rate-limit code, the toolkit lives at github.com/doublebash/mcp-toolkit — file issues there.

Security

Found a vulnerability? Please don't open a public issue. Open a private security advisory on GitHub.

License

MIT — Copyright (c) 2026 Bashar Basheer.