microsoft365-mcp-server

A Model Context Protocol (MCP) server for Microsoft 365 — manage email, calendar, contacts, files, Teams chats, channels, Planner, OneNote, To Do, users, and groups via Microsoft Graph API.

Which server? This is the delegated (per-user OAuth) server — the full interactive M365 assistant. Its sibling in this monorepo, microsoft-mcp-server, is the app-only (client_credentials) server for headless, tenant-wide document-RAG. Both sit on the shared @sapientsai/ms-graph-core. Use this one when a user is present to sign in; use microsoft-mcp-server when there's no user to consent (a service/tenant credential).

Features

• 73 Tools across 12 Microsoft 365 domains + generic Graph API escape hatch
• 5 Auth Modes: Interactive, certificate, client secret, client-provided token, OAuth proxy
• Draft Workflow: Create drafts for user review in Outlook, then send when approved
• Tool Filtering: Presets, regex patterns, read-only mode, and org-mode gating
• Auto-Pagination: fetch_all_pages parameter on all list tools (max 50 pages)
• Multi-Account: Register and switch between multiple authenticated accounts
• Functional Programming: functype patterns — Either, Option, Try, Brand types
• Type-Safe: Branded IDs, Zod parameter schemas, strict TypeScript
• Modern Build System: ts-builds + tsdown
• Dual Transport: stdio (default) and HTTP stream
• Persistent OAuth Sessions: DiskStore-backed token persistence survives server restarts
• SharePoint Sites: Browse, search, and access files across SharePoint sites the user has permissions on

Quick Start

# Install globally
npm install -g microsoft365-mcp-server

# Or run directly
npx microsoft365-mcp-server

Claude Desktop / VS Code Configuration

Add to your claude_desktop_config.json or MCP settings:

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

Authentication

Interactive (Browser/Device Code)

Simplest setup — opens a browser or displays a device code for headless environments.

MS365_AUTH_MODE=interactive
MS365_CLIENT_ID=your-client-id
MS365_TENANT_ID=common          # "common" for multi-tenant

Client Secret

For service accounts and automation.

MS365_AUTH_MODE=client-secret
MS365_TENANT_ID=your-tenant-id
MS365_CLIENT_ID=your-client-id
MS365_CLIENT_SECRET=your-secret

Certificate

For production service principals with certificate-based auth.

MS365_AUTH_MODE=certificate
MS365_TENANT_ID=your-tenant-id
MS365_CLIENT_ID=your-client-id
MS365_CERT_PATH=/path/to/cert.pem
MS365_CERT_PASSWORD=optional-password

Client-Provided Token

For external token management — the MCP client supplies tokens.

MS365_AUTH_MODE=client-token
MS365_ACCESS_TOKEN=optional-initial-token

Use the set_access_token tool to update tokens at runtime.

OAuth Proxy

Full OAuth 2.0 authorization server mode using FastMCP's built-in AzureProvider. Handles PKCE, consent screens, JWT issuance, and token refresh automatically. Requires HTTP transport.

MS365_AUTH_MODE=oauth-proxy
MS365_TENANT_ID=your-tenant-id
MS365_CLIENT_ID=your-client-id
MS365_CLIENT_SECRET=your-client-secret
MS365_OAUTH_BASE_URL=http://localhost:3000
PORT=3000

Endpoints provided automatically:

• GET /.well-known/oauth-authorization-server — OAuth metadata
• GET /authorize — Redirect to Microsoft auth
• POST /token — Token exchange
• GET/POST /mcp — MCP protocol (with bearer auth)
• GET /ping — Pre-auth health check (for Docker/Kubernetes liveness probes)

OAuth tokens are persisted to disk via FastMCP's DiskStore, so users stay authenticated across server restarts. Refresh tokens last ~90 days. Set TOKEN_STORAGE_PATH to customize the storage directory (default: /tmp/ms365-tokens). For persistence across container recreations, mount a Docker volume at that path.

Azure AD App Registration

You need an Azure AD (Entra ID) app registration:

1. Go to Azure Portal > App registrations > New registration
2. Set supported account types based on your needs (single tenant, multi-tenant, or personal)
3. Add redirect URIs:
   • Mobile/Desktop platform: http://localhost (for interactive mode — allows any port)
   • Web platform: http://localhost:3000/oauth/callback (for OAuth proxy mode)
4. Add Microsoft Graph delegated permissions:

| Permission | Domain | | ---------------------------------------------- | ---------------------------------------------- | | User.Read | User profile | | Mail.Read, Mail.Send | Email | | Calendars.ReadWrite | Calendar | | Calendars.Read.Shared | Calendar free/busy (find_meeting_availability) | | Contacts.Read | Contacts | | Files.ReadWrite | OneDrive | | Sites.Read.All, Sites.ReadWrite.All | SharePoint sites | | Chat.ReadWrite | Teams chats | | ChatMessage.Read, ChatMessage.Send | Chat messages | | Team.ReadBasic.All | Teams | | Channel.ReadBasic.All, ChannelMessage.Send | Channels | | Tasks.ReadWrite | Planner & To Do | | Notes.ReadWrite | OneNote |

5. Grant admin consent (for org tenants)
6. Create a client secret (for client-secret and OAuth proxy modes)

Restricting Access to Specific Users

By default, any user in your tenant can authenticate. To restrict to specific users:

# Enable user assignment requirement
az ad sp update --id <app-id> --set appRoleAssignmentRequired=true

# Assign a user
SP_ID=$(az ad sp show --id <app-id> --query id -o tsv)
USER_ID=$(az ad user show --id [email protected] --query id -o tsv)
az rest --method POST \
  --url "https://graph.microsoft.com/v1.0/servicePrincipals/${SP_ID}/appRoleAssignments" \
  --body "{\"principalId\":\"${USER_ID}\",\"resourceId\":\"${SP_ID}\",\"appRoleId\":\"00000000-0000-0000-0000-000000000000\"}"

Or in Azure Portal: Enterprise Applications > your app > Users and groups > Add user.

Safety Layers

| Layer | Protection | Default | | ------------------------ | -------------------------------------------------------- | ------------------ | | User assignment | Only assigned users can authenticate | Off (enable above) | | Platform governance | Per-tool allow/confirm/deny in Claude Desktop Enterprise | Platform-level | | Tool filtering | Presets, read-only, org-mode gating | All tools | | Tenant restriction | MS365_TENANT_ID locks to one org | common | | M365 native recovery | Recycle bins, version history | Built-in |

Recovery by domain:

• Mail, Calendar, OneDrive, SharePoint: Deleted Items / Recycle Bin (30-93 days), version history
• Teams messages: Immutable (can't be deleted via API)
• Contacts, Planner tasks, To Do tasks: No native recovery — use MS365_READ_ONLY=true or platform governance to restrict writes

Tool Filtering

Presets

Named bundles of tool domains:

| Preset | Domains | | --------------- | ---------------------------------------------- | | personal | mail, calendar, contacts, todo, files, onenote | | collaboration | chats, teams, meetings, planner, groups | | productivity | mail, calendar, todo | | all | everything |

MS365_PRESETS=personal                    # just personal tools
MS365_PRESETS=personal,collaboration      # personal + team tools
MS365_PRESETS=rag                         # read_document + files + graph_query

If not set, all tools are registered.

Other Filters

MS365_ENABLED_TOOLS="mail|calendar"   # regex pattern — only matching tools registered
MS365_READ_ONLY=true                  # hide all write tools (send, create, update, delete)
MS365_ORG_MODE=true                   # enable org-only tools (teams, chats, meetings, groups, planner, list_users)
MS365_REQUIRE_DRAFT=true              # hide all send_* mail tools; force the create_*_draft + send_draft flow

Org mode is required for Teams, Chats, Meetings, Groups, Planner, and user listing. Without it, these tools are hidden to prevent 403 errors on personal accounts.

Available Tools

Mail (16 tools)

| Tool | Description | | ------------------------ | ------------------------------------------------------------------------ | | list_messages | List inbox messages with optional filtering | | get_message | Get a specific message with full body | | search_messages | Search messages by query | | send_message | Send a new email | | send_reply | Reply to the sender and send now (threaded, original quoted) | | send_reply_all | Reply to all recipients and send now (threaded, original quoted) | | send_forward | Forward a message to new recipients and send now (original quoted) | | create_draft | Create a new email draft in the Drafts folder | | create_reply_draft | Create a reply draft — threaded, with the original quoted underneath | | create_reply_all_draft | Create a reply-all draft — threaded, with the original quoted underneath | | create_forward_draft | Create a forward draft — original quoted, recipients you specify | | send_draft | Send an existing email draft | | list_attachments | List a message's attachments, with a read_document path for file ones | | list_mail_folders | List top-level mail folders with item, unread and subfolder counts | | move_message | Move a message to a well-known folder, a folder name, or a folder ID | | batch_move_messages | Move up to 50 messages to one folder in a single call |

The create_*_draft tools produce a properly threaded draft (same conversation, full quoted history) for review, then send via send_draft. They remain available under MS365_REQUIRE_DRAFT=true; the send_* tools are hidden in that mode.

Calendar (7 tools)

| Tool | Description | | --------------------------- | --------------------------------------------------------------- | | list_events | List calendar events | | list_calendar_view | List event instances in a date range (expands recurring series) | | find_meeting_availability | Suggest meeting times where all participants are free | | get_event | Get event details | | create_event | Create a new event | | update_event | Update an existing event | | delete_event | Delete an event |

Contacts (4 tools)

| Tool | Description | | ----------------- | -------------------- | | list_contacts | List contacts | | get_contact | Get contact details | | create_contact | Create a new contact | | search_contacts | Search contacts |

Files / OneDrive (7 tools)

| Tool | Description | | ------------------ | ----------------------------------------------------------------------------- | | list_drive_items | List files and folders (supports folder_id or folder_path for navigation) | | get_drive_item | Get file/folder metadata | | search_files | Search OneDrive/SharePoint | | download_file | Download a file — returns content inline for text files under 100KB | | create_folder | Create a new folder | | upload_file | Upload a file to OneDrive (text or base64-encoded binary, max ~4MB) |

SharePoint Sites (5 tools, org mode)

| Tool | Description | | ------------------- | ----------------------------------------------------------------------- | | list_sites | List followed sites, or search all sites by query | | get_site | Get SharePoint site details | | list_site_drives | List document libraries (drives) in a site | | list_site_items | List files/folders in a site drive (supports folder_id/folder_path) | | search_site_files | Search files within a SharePoint site |

SharePoint tools use delegated permissions — users see only the sites and files they have access to. Private channel sites are properly isolated; access requires channel membership.

Chats (3 tools, org mode)

| Tool | Description | | -------------------- | ------------------------------------------------------ | | list_chats | List Teams chats (1:1, group, meeting) | | list_chat_messages | List messages in a chat | | send_chat_message | Send a message in a chat. Use 48:notes for self-chat |

Teams (4 tools, org mode)

| Tool | Description | | ----------------------- | ---------------------------- | | list_teams | List joined teams | | list_channels | List channels in a team | | list_channel_messages | List recent channel messages | | send_channel_message | Send a message to a channel |

Meeting Transcripts (2 tools, org mode)

Requires opt-in scopes that are not requested by default — see Meeting transcripts.

| Tool | Description | | -------------------------- | ------------------------------------------------ | | list_meeting_transcripts | List a Teams meeting's transcripts and their IDs | | get_meeting_transcript | Get one transcript's text |

Users & Groups (6 tools, org mode except get_me)

| Tool | Description | | -------------------- | -------------------------------- | | get_me | Get authenticated user's profile | | list_users | List organization users | | get_user | Get a specific user's profile | | list_groups | List organization groups | | get_group | Get group details | | list_group_members | List group members |

Planner (5 tools, org mode)

| Tool | Description | | --------------------- | -------------------- | | list_plans | List Planner plans | | list_planner_tasks | List tasks in a plan | | get_planner_task | Get task details | | create_planner_task | Create a new task | | update_planner_task | Update a task |

OneNote (10 tools)

| Tool | Description | | ----------------------------- | -------------------------------------------------------- | | list_onenote_notebooks | List notebooks | | list_onenote_sections | List sections in a notebook | | list_onenote_pages | List pages in a section | | get_onenote_page_content | Get page content as HTML | | create_onenote_page | Create a page from HTML (title + body) | | update_onenote_page_content | Append to / modify a page's content without rewriting it | | create_onenote_section | Create a section in a notebook | | create_onenote_notebook | Create a notebook | | copy_onenote_page | Copy a page to another section (async) | | delete_onenote_page | Delete a page (destructive) |

create_onenote_page and update_onenote_page_content take HTML. OneNote supports a constrained HTML subset and silently drops unsupported CSS/tags, so a page can post successfully yet render differently than the source.

To Do (4 tools)

| Tool | Description | | ------------------ | -------------------- | | list_todo_lists | List task lists | | list_todo_tasks | List tasks in a list | | create_todo_task | Create a new task | | update_todo_task | Update a task |

Auth & Utility (5 tools)

| Tool | Description | | ------------------ | -------------------------------------- | | get_auth_status | Check authentication status and scopes | | set_access_token | Update token (client-token mode) | | list_accounts | List registered accounts | | switch_account | Switch default account | | graph_query | Execute arbitrary Graph API queries |

Auto-Pagination

All list tools support fetch_all_pages: true to automatically follow @odata.nextLink pagination (max 50 pages):

{ "name": "list_messages", "arguments": { "fetch_all_pages": true } }

Environment Variables

| Variable | Description | Default | | ------------------------- | --------------------------------------------------------------------------------------- | ------------------- | | MS365_AUTH_MODE | Auth mode: interactive, certificate, client-secret, client-token, oauth-proxy | interactive | | MS365_TENANT_ID | Azure AD tenant ID | common | | MS365_CLIENT_ID | Azure AD application (client) ID | -- | | MS365_CLIENT_SECRET | Client secret (for client-secret and oauth-proxy modes) | -- | | MS365_CERT_PATH | Certificate path (for certificate mode) | -- | | MS365_CERT_PASSWORD | Certificate password (optional) | -- | | MS365_ACCESS_TOKEN | Initial access token (for client-token mode) | -- | | MS365_OAUTH_BASE_URL | Base URL for OAuth proxy mode | -- | | MS365_GRAPH_VERSION | Graph API version: v1.0 or beta | v1.0 | | TRANSPORT_TYPE | Transport: stdio or httpStream | stdio | | PORT | HTTP server port | 3000 | | HOST | HTTP server host | 127.0.0.1 | | MS365_PRESETS | Comma-separated presets: personal, collaboration, productivity, rag, all | -- (all tools) | | MS365_EXTRA_SCOPES | Comma-separated Graph scopes added to the requested set (OAuth proxy mode) | -- | | MS365_MAX_EXTRACT_BYTES | Ceiling over read_document's per-format input caps, in bytes. Never raises them. | -- (per-format) | | MS365_ENABLED_TOOLS | Regex pattern to filter tools | -- | | MS365_READ_ONLY | Hide write tools | false | | MS365_ORG_MODE | Enable org-only tools (teams, chats, groups, planner) | false | | MS365_REQUIRE_DRAFT | Hide all send_* mail tools; force the create_*_draft + send_draft flow | false | | TOKEN_STORAGE_PATH | Directory for persistent OAuth token storage | /tmp/ms365-tokens | | FASTMCP_HOST | Bind address for HTTP server (set 0.0.0.0 in containers) | localhost |

Claude Desktop (Local Installation)

Option A: Desktop Extension (.mcpb)

1. Download the latest .mcpb file from Releases
2. In Claude Desktop: Settings → Extensions → Install Extension
3. Select the .mcpb file
4. Enter your Azure App Client ID and Tenant ID when prompted
5. Authenticate in browser when first tool is used

Option B: Manual Configuration

Add to your claude_desktop_config.json:

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

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Docker / Remote Deployment

Deploy as a remote MCP server with per-user OAuth authentication:

docker compose up -d

Connect from Claude Desktop or any MCP client:

{
  "mcpServers": {
    "microsoft365": {
      "url": "https://your-domain.example.com/mcp"
    }
  }
}

The Dockerfile sets FASTMCP_HOST=0.0.0.0 (binds to all interfaces) and uses /ping for health checks (pre-auth endpoint). The /health endpoint provided by FastMCP is currently unreachable when auth is enabled due to a known issue in mcp-proxy's auth middleware ordering.

See DEPLOYMENT.md for the full guide — Docker, Azure AD app setup, Dokploy, reverse proxy, and security configuration.

Development

pnpm install
pnpm validate        # format + lint + typecheck + test + build
pnpm dev             # development build with watch mode
pnpm inspect         # build and open MCP Inspector

Architecture

• FastMCP — MCP server framework with Zod schema validation and built-in OAuth (AzureProvider)
• functype — Functional programming: Either for error handling, Option for nullable fields, Brand for type-safe IDs
• ts-builds — Standardized TypeScript build toolchain
• @azure/identity — Azure AD authentication
• Raw fetch with Either-based error handling (no Microsoft Graph SDK dependency)
• Data-driven tool registration with domain metadata, filtering, and MCP annotations
• AsyncLocalStorage for per-request token injection in OAuth proxy mode

License

MIT

Sponsored by SapientsAI — Building agentic AI for businesses

Reading documents

read_document returns the readable text of a SharePoint or OneDrive file — PDF, DOCX, XLSX, or anything text-based. Pair it with search_site_files (SharePoint, takes a site_id) or search_files (your own OneDrive) to get an item ID, then pass /drives/{driveId}/items/{itemId}/content or /me/drive/items/{id}/content.

Known limits:

1. No OCR. Extraction reads embedded text only, so a scanned PDF yields nothing. Fall back to download_file.
2. Per-format input caps, checked against the file's metadata before any download: 100 MB PDF, 50 MB DOCX, 25 MB XLSX, 25 MB text. These are not uniform because memory cost is not uniform — a spreadsheet expands into a full workbook object model at roughly 10–20x its file size, which is why XLSX is the tightest rather than PDF. MS365_MAX_EXTRACT_BYTES tightens all four at once in a memory-constrained container; it is a ceiling and cannot raise a format above its default. Over the cap, use download_file for a download URL instead.
3. Output is bounded separately by max_chars (50,000 default, 200,000 max), with an explicit truncation marker. This is unrelated to the input caps above — do not tune them as one number.
4. Discovery is split. search_files is rooted at your own OneDrive and search_site_files takes a site_id. Neither is a tenant-wide search.

Meeting transcripts

list_meeting_transcripts and get_meeting_transcript read the transcript of a Teams meeting, so "turn this meeting into action items" works against a recorded review.

These are the only tools here that need a permission the server does not request by default, because that permission needs a tenant administrator.

1. Grant the permission

The delegated permissions are:

| Scope | Needed for | Consent | | ---------------------------------- | -------------------------------------------------------------------------------- | ------- | | OnlineMeetingTranscript.Read.All | listing transcripts and reading their content | Admin | | OnlineMeetings.Read | resolving a meeting from a join_web_url (skip if you always pass meeting_id) | Admin |

Both are admin-consent scopes on the Graph service principal. A non-admin user cannot consent past them, which is why they are excluded from the default scope set — adding them there would break sign-in for every deployment whose tenant has not granted them.

Grant them on the app registration under API permissions → Microsoft Graph → Delegated permissions, then Grant admin consent.

If tenant-wide consent is more than you want, a per-user grant works too: create the OAuth2 permission grant with consentType: "Principal" and a principalId, and only that user's tokens carry the scope. This is the narrower option when one team needs transcripts and the rest of the tenant does not.

The delegated path needs no Teams application access policy. (App-only access does — it additionally requires New-CsApplicationAccessPolicy / Grant-CsApplicationAccessPolicy and reaches every meeting in the tenant. This server uses the delegated path, which stays bounded by what the signed-in user can already see.)

2. Ask the server to request it

MS365_EXTRA_SCOPES="OnlineMeetingTranscript.Read.All,OnlineMeetings.Read"

Scopes listed here are appended to the default set, so a granted permission reaches the issued access token without a code change or a release. Users must sign in again afterwards — an already-issued token does not gain a scope retroactively.

This applies to OAuth proxy mode. The credential-based modes request https://graph.microsoft.com/.default, meaning "everything this app registration has been consented to", so there the app registration alone decides and MS365_EXTRA_SCOPES is not consulted.

Using the tools

list_meeting_transcripts(meeting_id: "MSo1N2Y5...")            # transcript IDs
get_meeting_transcript(meeting_id: "MSo1N2Y5...", transcript_id: "MSMjMCMj...")

join_web_url works in place of meeting_id — take it from a calendar event's onlineMeeting.joinUrl — at the cost of one extra lookup and the OnlineMeetings.Read grant.

Worth knowing:

1. Attendees, not just organizers. Anyone on the meeting's calendar invite can read the transcript with their own token.
2. The meeting needs a calendar event. Meetings created through the create-onlineMeeting API without one are unsupported, and live events are excluded entirely. Expired meetings drop off the API too.
3. Speaker attribution degrades rather than fails. A tenant setting can disable speaker-attributed transcripts; asking for the attributed format then returns 403 SpeakerAttributionNotAllowed. The tool retries automatically for the unattributed format and notes in its output that the names are missing. Pass include_speaker_names: false to skip the attributed attempt entirely.
4. A separate tenant setting can block transcripts outright. GraphAccessToTranscriptsDisabled has no request-side workaround — a Teams admin has to re-enable Graph API access to transcripts (Set-CsTeamsMeetingConfiguration). The tool says so rather than retrying.
5. Output is bounded by max_chars (50,000 default) with a truncation marker, like read_document.
6. No metering. These Teams APIs stopped being metered on August 25, 2025; no billing configuration is required.