m365-mcp

A Model Context Protocol server that gives Claude Code (or any MCP client) controlled access to Microsoft 365 through the Microsoft Graph API: mail, calendar, contacts, files, notes, tasks, Teams, SharePoint, and the full tenant-admin surface.

It runs locally as a stdio subprocess. There is no hosted component, no client secret, and no inbound network exposure. Authentication is a local public-client browser flow, and every token stays on your machine.

Status: 441 tools, multi-account (personal and work identities mixed in one server), public-client auth with per-account token caches. License: MIT.

┌──────────────────────────────────────────────────────────────────┐
│  441 tools total                                                   │
│                                                                    │
│  173  available to PERSONAL  Microsoft accounts (167 + 6 mgmt)     │
│  441  available to WORK / school accounts (everything)             │
│                                                                    │
│  Same tool names for both. Work-only tools are blocked, with a     │
│  clear error, when called against a personal account.              │
└──────────────────────────────────────────────────────────────────┘

The capability story has three tiers, and the rest of this document follows that order: what a personal account gets, what a business (work/school) account adds, and what a tenant administrator unlocks on top.

Tier 1: Personal Microsoft accounts

If you sign in with a consumer Microsoft account (@outlook.com, @hotmail.com, @live.com, @msn.com), you get the complete personal productivity surface: 173 tools (167 Graph tools plus 6 account-management tools). Everything in this tier works against a personal mailbox with no tenant, no admin, and no license beyond a normal Microsoft account.

Primary use case

Screen an inbox, draft replies for your approval, triage junk, route newsletters with rules, manage your calendar, and organize OneDrive, all by asking Claude in natural language.

Known personal-account limits

A handful of Graph families are work-only at the platform level and simply do not exist for consumer accounts (Teams chat, SharePoint sites, org directory, Planner, admin reports, and so on). The server tags those tools so they fail fast with a readable message instead of a raw Graph 403. The durable list lives in PERSONAL_ACCOUNT_LIMITS.md. Notable nuances:

• OneNote works on personal accounts but can return transient errors for a minute or two right after first consent. Retry rather than concluding it is unsupported.

• Subscriptions require a publicly reachable HTTPS notificationUrl, so they need an ngrok-style tunnel to be useful from a purely local server. Personal accounts support subscriptions on mail, calendar, drive root, and To Do tasks, but not on contacts.

• Workbook / Excel API is de-scoped on personal accounts in favor of the separate excel-mcp-server.

Related MCP server: Outlook Assistant

Tier 2: Business (work / school) accounts

Sign in with a Microsoft Entra (Azure AD) work or school account and you keep all 173 personal tools, then add 157 collaboration tools that only exist inside an organization. These target Teams, SharePoint, Microsoft 365 Groups, Planner, the org directory, shared mailboxes, Bookings, and the Excel Workbook API.

What this enables

A work account turns the server into a full collaboration assistant: post to a Teams channel, search every chat you are in, manage a SharePoint document library or list, run a Planner board, look up a colleague's manager or free/busy, or draft from a shared support mailbox.

Delegated, not impersonating. Every action runs as you, with your permissions. Shared-mailbox tools require that you already hold Exchange Online FullAccess or folder rights on that mailbox; the Graph scopes alone do not grant the underlying data access.

Tier 3: Tenant administrators

If your work account holds admin roles, the server exposes 111 additional governance, security, and device-management tools. These read and write tenant-wide configuration, so several are flagged as sensitive and should only be invoked with explicit intent.

⚠ sensitive operations. Tools that change tenant-wide security policy, place data on legal hold, or wipe a device are marked with a warning in CLAUDE.md. Confirm intent before invoking. Note that Graph exposes device writes only to app-only auth, so update_device / delete_device cannot run through this delegated public-client flow (device read works fine; Intune wipe/retire use a different, supported path).

The full, per-tool inventory for every tier lives in CLAUDE.md; architecture and design notes are in As_Built_Specification.md.

Setup overview

Setup is three moving parts, done once per identity:

1. Register an Azure app and grant it Graph permissions (this section).

2. Point the server at the app via .env.

3. Generate a token with the add_account tool (the Authentication section).

You register one app per Microsoft identity:

Microsoft only allows one personal account per person, so the personal app uses the un-suffixed .env keys. Each work tenant adds its own suffixed pair.

Prerequisites

• Node.js 18+ (uses native fetch).

• A Microsoft account (personal, or work/school in any Entra tenant).

• For work apps: tenant-admin consent, either yours or your admin's.

• macOS, Windows, or Linux. The first sign-in opens your default browser briefly.

Account setup and permission changes (Azure portal)

Do this in the Microsoft Entra admin center, entra.microsoft.com. Sign in as the identity you want to connect. For a work account, confirm the tenant shown in the top-right is the correct one before you start.

Step 1: Register the app

Applications → App registrations → + New registration.

Click Register.

Use single-tenant for work apps. Register a separate app per work tenant rather than one multitenant app, unless you specifically need cross-tenant sign-in.

Step 2: Copy the identifiers

On the app's Overview page, copy:

Step 3: Add API permissions

API permissions → + Add a permission → Microsoft Graph → Delegated permissions. These are the 14 base (Tier 1) scopes every account needs:

Work and admin accounts add the work-only scope set on top (roughly 90 scopes spanning Teams, SharePoint, Groups, Planner, directory, reports, identity governance, Conditional Access, security, Intune, Print, and Bookings). Rather than transcribe all of them here:

• Run the list_known_scopes tool to print the exact base + work-only list the add_account flow will request, or

• Read the authoritative source: DEFAULT_SCOPES and WORK_ONLY_SCOPES in src/auth/multi-account-auth.ts.

Add every scope your tier needs, then click Add permissions.

Step 4: Grant admin consent (work accounts only)

On the API permissions page, click "Grant admin consent for <tenant>". The admin-only .All scopes require this. If you are not an admin, send your tenant admin this URL (substitute your client and tenant IDs):

https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<client-id>&redirect_uri=http://localhost:3333/auth/callback

After a one-time approval, users in the tenant sign in without per-user consent prompts on the .All scopes. Personal accounts skip this step; you consent in-browser during add_account.

Step 5: Confirm authentication settings

Authentication:

• Platform configurations = "Mobile and desktop applications" with redirect URI http://localhost:3333/auth/callback.

• Advanced settings → Allow public client flows = Yes. If it is No, switch it and Save.

There is no client secret. This is a public-client / loopback-redirect app by design; adding a secret is unnecessary and unsupported by the flow.

Install and configure

git clone https://github.com/Corvalon/mcp-m365.git
cd mcp-m365
npm install
cp .env.example .env
npm run build

Edit .env. The server auto-loads it from the repo root on startup. Always single-quote every value (Node's env parser treats an unquoted # as a mid-line comment and will silently truncate a value).

# --- Personal account (Path A) ---
AZURE_CLIENT_ID='<personal-app-client-id>'
AZURE_TENANT_ID='consumers'

# --- Work account(s) (Path B/C), one suffixed pair per tenant ---
# The suffix is a short name you choose; it must match the `tenant`
# argument you pass to add_account.
AZURE_CLIENT_ID_CONTOSO='<contoso-app-client-id>'
AZURE_TENANT_ID_CONTOSO='<contoso-tenant-guid>'

A personal pair and any number of work pairs can all live in the same .env.

Wire into Claude Code

Add the server to your MCP config (~/.claude.json, or via the Claude Code IDE settings):

{
  "mcpServers": {
    "m365": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-m365/dist/index.js"]
    }
  }
}

Restart Claude Code. The server logs a startup line confirming 441 tools registered, and the tools become available as mcp__m365__*. The .env is read from the repo root automatically, so no extra env wiring is needed.

Authentication / token generation

Tokens are generated at runtime through the MCP tools, not by a separate script. The first time you connect an identity you run add_account, which opens a browser for OAuth consent and caches the result locally.

Generate your first token

Ask Claude to run add_account, or call it directly:

Personal account:

// mcp__m365__add_account
{ "alias": "personal", "accountType": "personal" }

Work account (the tenant value must match your .env suffix, lowercase):

// mcp__m365__add_account
{ "alias": "contoso", "accountType": "work", "tenant": "contoso" }

What happens:

1. The tool reads the matching client/tenant IDs from .env and builds the consent URL (base scopes for personal, base + work-only for work).

2. Your default browser opens. Sign in and approve. The call blocks for up to 2 minutes waiting for you to finish.

3. A local listener on http://localhost:3333/auth/callback catches the redirect and exchanges the code for tokens.

4. An audience guard verifies you signed in with the expected identity. If you accidentally pick the wrong account in the browser, the account is rejected and not persisted; just re-run add_account.

5. The access + refresh tokens are written to a per-alias cache under .token-cache/, and the account metadata to accounts.json. The first account you add becomes the default.

After this, MSAL refreshes tokens silently. You only return to the browser when a refresh fails or you widen scopes. On failure the server raises a structured REAUTH_REQUIRED <alias> error naming exactly which account to re-add.

Routing calls to an account

Every Graph tool accepts an optional account alias. Omit it to use the default.

{ "account": "contoso", "top": 10 }   // read_inbox against the work account
{ "top": 10 }                          // read_inbox against the default account

Manage accounts

Re-authenticate or widen scopes

• Re-auth one account: remove_account <alias> then add_account again.

• Widen scopes: add the broader scope in the Azure portal, then re-run add_account with the same alias and a wider scopes array (MSAL merges the consent).

• Fully revoke: remove_account deletes the local cache but does not revoke the Microsoft-side grant. To revoke server-side, remove the app at account.microsoft.com/consent/manage (personal) or via the tenant admin (work).

Security model

• No client secret. Public-client, loopback-redirect, delegated auth only.

• Local-only tokens. .env, accounts.json, and .token-cache/ are all gitignored and never leave your machine.

• Delegated permissions. Every action runs as the signed-in user with that user's rights. The server cannot exceed what the account can already do.

• Tier enforcement. Work-only tools carry a compatibility="work" flag and are rejected before the handler runs when targeted at a personal account (and vice versa), for both explicit-alias and default-account calls.

• Redaction. homeAccountId is truncated to its first 8 characters in surfaces an operator might log (list_accounts, get_account_info).

Troubleshooting

Development

npm run build          # tsc -> dist/
npm run dev            # tsx src/index.ts (no build step)
npm test               # Vitest unit suite
npm run test:coverage  # with coverage

Tools are grouped into per-family src/tools/*.register.ts modules and wired up in src/index.ts. Auth lives in src/auth/ (multi-account-auth.ts holds the scope catalog and MSAL layer; graph-client.ts loads .env and exposes the default client). All Graph calls funnel through one account-aware choke point, so tools stay account-agnostic.

Reference docs

License

MIT. See LICENSE.