softeria/ms-365-mcp-server

Microsoft 365 MCP Server
A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Microsoft Office services through the Graph
API.
Supported Clouds
This server supports multiple Microsoft cloud environments:
| Cloud | Description | Auth Endpoint | Graph API Endpoint |
| -------------------- | ---------------------------------- | ------------------------- | ------------------------------- |
| **Global** (default) | International Microsoft 365 | login.microsoftonline.com | graph.microsoft.com |
| **China** (21Vianet) | Microsoft 365 operated by 21Vianet | login.chinacloudapi.cn | microsoftgraph.chinacloudapi.cn |
To route Graph traffic through a proxy of your own (one that terminates the client's plain HTTP and originates TLS to Microsoft), set MS365_MCP_GRAPH_BASE_URL to its base URL; see the environment variable list under CLI Options, including what still bypasses it.
Prerequisites
- Node.js >= 20 (recommended)
- Node.js 14+ may work with dependency warnings
Features
- Authentication via Microsoft Authentication Library (MSAL)
- Comprehensive Microsoft 365 service integration
- Read-only mode support for safe operations
- Tool filtering for granular access control
- Tool presets and dynamic discovery to shrink the tool surface and token usage
Output Format: JSON vs TOON
The server supports two output formats that can be configured globally:
JSON Format (Default)
Standard JSON output with pretty-printing:
(experimental) TOON Format
Token-Oriented Object Notation for efficient LLM token usage:
**Benefits:**
- 30-60% fewer tokens vs JSON
- Best for uniform array data (lists of emails, calendar events, files, etc.)
- Ideal for cost-sensitive applications at scale
**Usage:**
(experimental) Enable TOON format globally:
Via CLI flag:
Via Claude Desktop configuration:
Via environment variable:
Supported Services & Tools
The server provides 300+ tools covering most of the Microsoft Graph API surface. Each tool maps 1-to-1 to a Graph API endpoint and is defined declaratively in src/endpoints.json.
Personal Account Tools (Available by default)
Email (Outlook), Calendar, OneDrive Files, Excel, OneNote, To Do Tasks, Planner, Contacts, User Profile, Search
Organization Account Tools (Requires --org-mode flag)
Teams & Chats, Online Meetings, Transcripts & Recordings, Attendance Reports, SharePoint Sites & Lists, Shared Mailboxes & Calendars, User Management, Presence, Virtual Events
Custom Teams emojis are available in organization mode through list-custom-emojis
and create-custom-emoji (teams and work presets). These use the Microsoft Graph
beta API and request the delegated permissions TeamworkCustomEmoji.Read and
TeamworkCustomEmoji.Create, respectively. Read-only mode exposes only the list tool.
Existing deployments may need consent for these new scopes and reauthentication;
adding tool support does not upgrade an already-issued token.
Listing can return contentBytes: null by default. To request base64 PNG/GIF images,
pass select: "displayName,contentBytes" or select: ["displayName", "contentBytes"].
Use a small top to keep image responses manageable.
To create an emoji, pass body: { displayName, contentBytes }
with the exact approved name and base64 PNG/GIF file bytes. See Microsoft's
list
and create
contracts. These tools do not post messages or reactions.
Required Graph API Permissions
Permissions are requested dynamically based on which tools are enabled. Use --list-permissions to see the exact permissions for your configuration:
This is useful for enterprise environments where Graph API permissions must be pre-approved and admin-consented before deploying a new version.
The --list-permissions JSON includes:
- toolPermissions: permissions implied by the tool surface before --allowed-scopes filtering
- effectivePermissions: permissions implied by the tools that remain enabled after --allowed-scopes
- permissions: legacy alias for effectivePermissions, kept for compatibility with existing scripts
- allowedScopes: the configured scope allowlist, when provided
- disabledTools: tools hidden because their required Graph scopes are not covered by allowedScopes
- missingAllowedScopesForTools: unique missing scopes across disabled tools
- extraAllowedScopesNotUsedByTools: allowed scopes that are not used by the current tool surface
Allowed Scopes
By default, MSAL requests the scopes implied by the enabled tools, and the tool surface is controlled by --enabled-tools, --preset, --org-mode, and --read-only.
Enterprise and headless deployments can add a scope boundary with --allowed-scopes or MS365_MCP_ALLOWED_SCOPES. When configured, the server first computes the normal tool surface, then hides Graph tools whose required scopes are not covered by the allowlist. OAuth metadata and login flows request only the effective permissions for the tools that remain enabled.