Microsoft365 MCP Server

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.

Features

• 58 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:

1. Grant admin consent (for org tenants)
2. 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 user@example.com --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

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:

MS365_PRESETS=personal                    # just personal tools
MS365_PRESETS=personal,collaboration      # personal + team tools

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, groups, planner, list_users)

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

Available Tools

Mail (7 tools)

Calendar (5 tools)

Contacts (4 tools)

Files / OneDrive (7 tools)

SharePoint Sites (5 tools, org mode)

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)

Teams (4 tools, org mode)

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

Planner (5 tools, org mode)

OneNote (4 tools)

To Do (4 tools)

Auth & Utility (5 tools)

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

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