Repository avatar
AI Tools
v1.5.0
active

microsoft365-mcp-server

io.github.sapientsai/microsoft365-mcp-server

Microsoft 365 via Graph — mail, calendar, contacts, files, Teams, Planner, OneNote, To Do.

Documentation

Microsoft 365 MCP Server

npm version Node.js CI License: MIT

An MCP server that lets an AI assistant work in a user's Microsoft 365: mail, calendar, contacts, OneDrive and SharePoint files, Teams chats and channels, Planner, OneNote and To Do, all through Microsoft Graph.

It signs in as the user (delegated OAuth), so it reaches only what that user can already reach. Run it locally over stdio, or host it as a remote server with per-user sign-in.

Quick start

1. Register an app in Microsoft Entra ID. The server needs an application (client) ID. Create one under App registrations, add the redirect URI http://localhost on the Mobile and desktop platform, and grant the delegated Graph permissions for the domains you want. To keep MS365_TENANT_ID as common, choose an account type that covers every organization, plus personal accounts if you need them. For one organization only, choose single tenant and set MS365_TENANT_ID to its tenant ID. The full checklist lists every permission.

2. Add the server to your MCP client (Claude Desktop, Claude Code, VS Code, Cursor, …):

{
  "mcpServers": {
    "microsoft365": {
      "command": "npx",
      "args": ["-y", "microsoft365-mcp-server"],
      "env": {
        "MS365_CLIENT_ID": "your-app-client-id",
        "MS365_TENANT_ID": "common"
      }
    }
  }
}

3. Start your client. When the client starts the server, a browser opens to sign in. On a headless machine, set MS365_USE_DEVICE_CODE=true instead: the server prints a device code to its log, and the app registration needs Allow public client flows turned on. The sign-in is cached, so it survives restarts.

What it can do

99 tools. 27 of them need a work or school tenant, so they stay hidden until you set MS365_ORG_MODE=true.

AreaToolsWhat the assistant can do
Mail23Read, search, send, reply, forward, move, and draft messages; save attachments
Calendar9List and manage events, find free time, accept or decline invitations
Contacts7List, search, create, update, delete, and export contacts
Files (OneDrive)8Browse, search, download, and upload files; create folders
SharePoint ¹5Browse sites, their drives and items; search a site's files
Documents1Extract readable text from PDF, DOCX, XLSX, and text files (read_document)
OneNote10List notebooks, sections and pages; read, create, update, copy, delete pages
To Do8Manage task lists and tasks, including repeating ones
Teams chats ¹3List chats and messages; send a chat message
Teams channels ¹4List teams, channels and messages; post to a channel
Meeting transcripts ¹2List and read Teams meeting transcripts
Planner ¹8List plans, buckets and tasks; create and update tasks
Users3Your own profile; look up other users ¹
Groups ¹3List groups and their members
Accounts4Check sign-in status, switch between accounts, supply a token
Graph query1Call any Microsoft Graph endpoint the user has access to (graph_query)

¹ Needs MS365_ORG_MODE=true. In the Users row, only the lookup of other users does; your own profile does not.

A few tools exist on only one transport: local file paths work over stdio, and upload links work over HTTP. Every tool carries MCP annotations (read-only, destructive, idempotent), so a client can tell reads from writes. The tool reference lists each one.

Keeping it safe

You decide how much the assistant can touch:

  • MS365_READ_ONLY=true hides every tool that writes.
  • MS365_REQUIRE_DRAFT=true removes direct email sending. The assistant can only write email drafts, which you review in Outlook and send yourself, or approve with send_draft. Teams messages and calendar invites still send.
  • MS365_PRESETS loads only some areas: personal, collaboration, productivity, rag, or all.
  • MS365_ENABLED_TOOLS loads only the tools whose names match a regex.
  • MS365_ALLOWED_MAILBOXES limits which other people's or shared mailboxes it may open.
  • MS365_TENANT_ID locks sign-in to one organization.

See Safety Layers for what Microsoft 365 can recover after a mistake, and what it can't.

Sign-in modes

ModeMS365_AUTH_MODEUse it when
InteractiveinteractiveOne person on their own machine (the default)
OAuth proxyoauth-proxyA hosted server where each user signs in through the MCP client
Client tokenclient-tokenYour app already holds a Graph token and passes it in
Client secretclient-secretAutomation running as an app registration, with no user present
CertificatecertificateThe same, using a certificate instead of a secret

Each mode's settings are in Authentication. The main environment variables are listed in Environment Variables.

Hosting it as a remote server

oauth-proxy mode turns the server into an OAuth 2.1 authorization server in front of Entra ID. Each user signs in from their own MCP client, and each request runs with that user's own Graph token. The repo ships a Dockerfile and docker-compose.yml. Set MS365_CLIENT_ID, MS365_CLIENT_SECRET and MS365_OAUTH_BASE_URL first; the compose file refuses to start without them:

docker compose up -d

Then point the client at https://your-host/mcp. DEPLOYMENT.md covers the app registration, reverse proxy, Dokploy, and hardening.

Also in this repo

This is a pnpm monorepo. The server above is packages/microsoft365, published to npm as microsoft365-mcp-server. Alongside it:

  • packages/graph: an app-only Microsoft Graph server for headless, tenant-wide document search and retrieval, with no user signed in. It ships as the Docker image ghcr.io/sapientsai/microsoft-mcp-server and replaces the archived sapientsai/microsoft-mcp-server.
  • packages/core: Graph plumbing both servers share, such as uploads, paging, errors, and auth types. Internal, not published.
  • packages/extract: turns PDF, DOCX, XLSX, and text files into plain text. Internal, not published.

Pick by who signs in: microsoft365 when a person is there to consent, graph when only a service credential is.

Development

Requires Node.js 24 or later and pnpm.

pnpm install
pnpm validate   # format, lint, test, and build every package
pnpm run ci     # validate's checks without fixing, as CI runs them (type `run`: `pnpm ci` is a clean install)
pnpm --filter microsoft365-mcp-server inspect   # build and open the MCP Inspector

License

MIT. Some shared code is adapted from other MIT projects; see NOTICE.


Sponsored by SapientsAI SapientsAI — Building agentic AI for businesses