Skip to content
Back to search

ms-365-mcp-server

A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Microsoft Office services through the Graph API

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Softeria/ms-365-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Softeria/ms-365-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/softeria--ms-365-mcp-server/badge.svg)](/listings/softeria--ms-365-mcp-server)

HTML

<a href="/listings/softeria--ms-365-mcp-server"><img src="/api/listings/softeria--ms-365-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Create a Key Vault** (if you don't have one):

   az keyvault create --name your-keyvault-name --resource-group your-rg --location eastus

2. **Add secrets to Key Vault**:

   az keyvault secret set --vault-name your-keyvault-name --name ms365-mcp-client-id --value "your-client-id"
   az keyvault secret set --vault-name your-keyvault-name --name ms365-mcp-tenant-id --value "your-tenant-id"
   # Optional: if using confidential client flow
   az keyvault secret set --vault-name your-keyvault-name --name ms365-mcp-client-secret --value "your-secret"

3. **Grant access to Key Vault**:

For Azure Container Apps with managed identity:

   # Get the managed identity principal ID
   PRINCIPAL_ID=$(az containerapp show --name your-app --resource-group your-rg --query identity.principalId -o tsv)

   # Grant access to Key Vault secrets
   az keyvault set-policy --name your-keyvault-name --object-id $PRINCIPAL_ID --secret-permissions get list

For local development with Azure CLI:

   # Your Azure CLI identity already has access if you have appropriate RBAC roles
   az login

4. **Configure the server**:

   MS365_MCP_KEYVAULT_URL=https://your-keyvault-name.vault.azure.net npx @softeria/ms-365-mcp-server

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,441 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ms-365-mcp-server
  2. [![npm version](https://img.shields.io/npm/v/@softeria/ms-365-mcp-server.svg)](https://www.npmjs.com/package/@softeria/ms-365-mcp-server) [![build status](https://github.com/softeria/ms-365-mcp-server/actions/workflows/build.yml/badge.svg)](https://github.com/softeria/ms-365-mcp-server/actions/workflows/build.yml) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/softeria/ms-365-mcp-server/blob/main/LICENSE)
  3. Microsoft 365 MCP Server
  4. A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Microsoft Office services through the Graph
  5. API.
  6. ## Supported Clouds
  7. This server supports multiple Microsoft cloud environments:
  8. | Cloud | Description | Auth Endpoint | Graph API Endpoint |
  9. | -------------------- | ------------------------------------ | ------------------------- | ------------------------------- |
  10. | **Global** (default) | International Microsoft 365 | login.microsoftonline.com | graph.microsoft.com |
  11. | **China** (21Vianet) | Microsoft 365 operated by 21Vianet | login.chinacloudapi.cn | microsoftgraph.chinacloudapi.cn |
  12. | **GCC High** | Microsoft 365 US Government GCC High | login.microsoftonline.us | graph.microsoft.us |
  13. GCC High has no pre-registered client: register an app in your government tenant and set `MS365_MCP_CLIENT_ID` (and `MS365_MCP_TENANT_ID`), then use `--cloud gcc-high`.
  14. 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.
  15. ## Prerequisites
  16. - Node.js >= 20 (recommended)
  17. - Node.js 14+ may work with dependency warnings
  18. ## Features
  19. - Authentication via Microsoft Authentication Library (MSAL)
  20. - Comprehensive Microsoft 365 service integration
  21. - Read-only mode support for safe operations
  22. - Tool filtering for granular access control
  23. - [Tool presets](#tool-presets) and [dynamic discovery](#dynamic-tool-discovery) to shrink the tool surface and token usage
  24. For external document readers, see the [provider-neutral document processing guide](docs/document-processing.md), including continuation and coverage handling.
  25. ## Output Format: JSON vs TOON
  26. The server supports two output formats that can be configured globally:
  27. ### JSON Format (Default)
  28. Standard JSON output with pretty-printing:
  29. ```json
  30. {
  31. "value": [
  32. {
  33. "id": "1",
  34. "displayName": "Alice Johnson",
  35. "mail": "alice@example.com",
  36. "jobTitle": "Software Engineer"
  37. }
  38. ]
  39. }
  40. ```
  41. ### (experimental) TOON Format
  42. [Token-Oriented Object Notation](https://github.com/toon-format/toon) for efficient LLM token usage:
  43. ```
  44. value[1]{id,displayName,mail,jobTitle}:
  45. "1",Alice Johnson,alice@example.com,Software Engineer
  46. ```
  47. **Benefits:**
  48. - 30-60% fewer tokens vs JSON
  49. - Best for uniform array data (lists of emails, calendar events, files, etc.)
  50. - Ideal for cost-sensitive applications at scale
  51. **Usage:**
  52. (experimental) Enable TOON format globally:
  53. Via CLI flag:
  54. ```bash
  55. npx @softeria/ms-365-mcp-server --toon
  56. ```
  57. Via Claude Desktop configuration:
  58. ```json
  59. {
  60. "mcpServers": {
  61. "ms365": {
  62. "command": "npx",
  63. "args": ["-y", "@softeria/ms-365-mcp-server", "--toon"]
  64. }
  65. }
  66. }
  67. ```
  68. Via environment variable:
  69. ```bash
  70. MS365_MCP_OUTPUT_FORMAT=toon npx @softeria/ms-365-mcp-server
  71. ```
  72. ## Supported Services & Tools
  73. 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`](src/endpoints.json).
  74. ### Personal Account Tools (Available by default)
  75. Email (Outlook), Calendar, OneDrive Files, Excel, OneNote, To Do Tasks, Planner, Contacts, User Profile, Search
  76. ### Organization Account Tools (Requires --org-mode flag)
  77. Teams & Chats, Online Meetings, Transcripts & Recordings, Attendance Reports, SharePoint Sites & Lists, Shared Mailboxes & Calendars, User Management, Presence, Virtual Events
  78. Custom Teams emojis are available in organization mode through `list-custom-emojis`
  79. and `create-custom-emoji` (`teams` and `work` presets). These use the Microsoft Graph
  80. beta API and request the delegated permissions `TeamworkCustomEmoji.Read` and
  81. `TeamworkCustomEmoji.Create`, respectively. Read-only mode exposes only the list tool.
  82. Existing deployments may need consent for these new scopes and reauthentication;
  83. adding tool support does not upgrade an already-issued token.
  84. Listing can return `contentBytes: null` by default. To request base64 PNG/GIF images,
  85. pass `select: "displayName,contentBytes"` or `select: ["displayName", "contentBytes"]`.
  86. Use a small `top` to keep image responses manageable.
  87. To create an emoji, pass `body: { displayName, contentBytes }`
  88. with the exact approved name and base64 PNG/GIF file bytes. See Microsoft's
  89. [list](https://learn.microsoft.com/en-us/graph/api/teamworkmessaging-list-customemojis?view=graph-rest-beta)
  90. and [create](https://learn.microsoft.com/en-us/graph/api/teamworkmessaging-post-customemojis?view=graph-rest-beta)
  91. contracts. These tools do not post messages or reactions.
  92. ### Required Graph API Permissions
  93. Permissions are requested dynamically based on which tools are enabled. Use `--list-permissions` to see the exact permissions for your configuration:
  94. ```bash
  95. # Personal mode (default)
  96. npx @softeria/ms-365-mcp-server --list-permissions
  97. # Organization mode (includes Teams, SharePoint, etc.)
  98. npx @softeria/ms-365-mcp-server --org-mode --list-permissions
  99. # Filtered by preset
  100. npx @softeria/ms-365-mcp-server --preset mail --list-permissions
  101. ```
  102. This is useful for enterprise environments where Graph API permissions must be pre-approved and admin-consented before deploying a new version.
  103. The `--list-permissions` JSON includes:
  104. - `toolPermissions`: permissions implied by the tool surface before `--allowed-scopes` filtering
  105. - `effectivePermissions`: permissions implied by the tools that remain enabled after `--allowed-scopes`
  106. - `permissions`: legacy alias for `effectivePermissions`, kept for compatibility with existing scripts
  107. - `allowedScopes`: the configured scope allowlist, when provided
  108. - `disabledTools`: tools hidden because their required Graph scopes are not covered by `allowedScopes`
  109. - `missingAllowedScopesForTools`: unique missing scopes across disabled tools
  110. - `extraAllowedScopesNotUsedByTools`: allowed scopes that are not used by the current tool surface
  111. ### Allowed Scopes
  112. By default, MSAL requests the scopes implied by the enabled tools, and the tool surface is controlled by `--enabled-tools`, `--enabled-tools-file`, `--preset`, `--org-mode`, and `--read-only`.
  113. 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.
  114. ```bash
  115. npx @softeria/ms-365-mcp-server \
  116. --org-mode \
  117. --enabled-tools '^(list-mail-messages|get-mail-message|list-drives|get-drive-item|download-bytes)$' \
  118. --allowed-scopes 'User.Read Mail.Read Files.Read'
  119. ```
  120. For longer filters, put one regex per line in a file and pass `--enabled-tools-file` / `ENABLED_TOOLS_FILE`. Blank lines and whole-line `#` comments are dropped; the rest are joined with `|`, so the file is equivalent to `--enabled-tools=line1|line2|…`:
  121. ```text
  122. # tools.txt
  123. ^list-mail-messages$
  124. ^get-mail-message$
  125. drive|download-bytes
  126. ```
  127. ```bash
  128. npx @softeria/ms-365-mcp-server --org-mode --enabled-tools-file ./tools.txt
  129. ```
  130. CLI value takes precedence over `MS365_MCP_ALLOWED_SCOPES`; if neither is set, the default tool-derived scope behavior is unchanged. Supplying an empty value fails at startup so deployments do not accidentally fall back to a wider tool surface.
  131. Scope coverage is hierarchy-aware: for example, `Mail.ReadWrite` covers tools that require `Mail.Read`, and `Files.ReadWrite.All` covers tools that require `Files.Read`.
  132. SharePoint supports two enterprise permission models:
  133. - Broad tenant scopes such as `Sites.Read.All`, `Sites.ReadWrite.All`, and `Sites.Manage.All`.
  134. - Microsoft Graph `Sites.Selected`, where SharePoint site access is granted to the app on specific site collections and Graph evaluates the signed-in user's own permissions at request time.
  135. The default org-mode behavior continues to request the broad SharePoint scopes used by existing deployments. Enterprises that want selected-site SharePoint access can set an allowlist containing `Sites.Selected` instead of broad `Sites.*.All` scopes. Direct site/list/item tools that target an explicit SharePoint site, and the `/drives/{drive-id}/...` item tools (list, get, upload, folder, move/rename, copy, versions) for drives of a granted site, can run with `Sites.Selected`; tenant-wide SharePoint discovery and search tools still require broad SharePoint scopes.
  136. ```bash
  137. npx @softeria/ms-365-mcp-server \
  138. --org-mode \
  139. --read-only \
  140. --enabled-tools 'sharepoint|site|drive|planner' \
  141. --allowed-scopes 'User.Read Files.Read Notes.Read Tasks.Read Sites.Selected'
  142. ```
  143. In HTTP mode, OAuth discovery advertises the effective filtered permissions so clients request the same consent surface. On-Behalf-Of mode (`--obo`) still advertises `<clientId>/access_as_user` for protected-resource metadata and requests it on `/authorize`; `--allowed-scopes` does not override OBO, it only narrows the tool surface.
  144. ### Restricting user profile fields
  145. Deployments can set a comma-separated field filter for selected user-directory paths with
  146. `--user-fields` or `MS365_MCP_USER_FIELDS`. It narrows the `$select` sent to Microsoft Graph
  147. on `/users` reads and projects responses on the covered paths listed below. This is a
  148. path-specific data filter, **not a complete Graph authorization boundary**: other Graph
  149. routes and resource shapes can expose overlapping profile data.
  150. ```bash
  151. npx @softeria/ms-365-mcp-server \
  152. --org-mode \
  153. --user-fields 'id,displayName,mail,userPrincipalName'
  154. ```
  155. The filter is keyed on known Graph paths rather than tool names. It applies to direct tools,
  156. discovery mode's `execute-tool`, and matching `graph-batch` subrequests. Batch subrequest URLs
  157. are rewritten on covered `/users` reads, and responses are projected on all covered profile
  158. paths. The byte-passthrough tools (`download-bytes`, `download-bytes-to-file`,
  159. `get-download-url`) return responses verbatim and refuse targets matching the covered user
  160. profile paths while the filter is active.
  161. Two levels of enforcement apply, depending on what Graph returns:
  162. | Path | Enforcement |
  163. | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  164. | `/users`, `/users/{id}` | `$select` is narrowed on the request and the response is projected, so excluded fields never leave the tenant |
  165. | `/me/manager`, `/me/directReports`, `/users/{id}/manager`, `/users/{id}/directReports`, `/groups/{id}/members`, `/groups/{id}/owners` | The response is projected. These are typed as `directoryObject`, where Graph requires an OData cast before it will `$select` a user-only property such as `jobTitle`, so narrowing the request would risk breaking calls that work today |
  166. While the filter is active, `$expand` is removed from `/me`, `/groups`, and `/groups/{id}`
  167. requests because those resources can expand to related user profiles. This also applies to
  168. matching batch subrequests. The base `/me` and group responses are otherwise not projected.
  169. This does **not** cover every route that can return a user-shaped object. In particular,
  170. generic Graph access can still reach alternate routes or representations such as
  171. `/directoryObjects/{id}`, `/groups/{id}/transitiveMembers`, or `/users('{id}')`. Those are
  172. not currently normalized to the covered paths. If this setting is a security requirement,
  173. also restrict generic Graph access (for example `graph-batch`) and validate the effective
  174. tool surface for your deployment; do not rely on `--user-fields` alone as a tenant-wide
  175. data-access control.
  176. Resources below a user, such as `/users/{id}/messages` or `/users/{id}/photo/$value`, are
  177. mail, calendar and binary resources rather than profile properties, and are unaffected. The
  178. signed-in user's own `/me` profile is also unaffected, as are the Teams and chat member
  179. lists, which return `conversationMember` rather than user profiles.
  180. #### Known gap: `list-relevant-people`
  181. `list-relevant-people` (`/me/people`) is **not** covered. It returns `person` resources,
  182. a different type whose properties only partly overlap with `user` — it carries `jobTitle`,
  183. `department` and `officeLocation`, but addresses arrive as `scoredEmailAddresses` rather
  184. than `mail`. Applying a user-field allowlist to it would reject valid field names and
  185. narrow the result to something the tool could not use.
  186. Deployments that need the people surface closed as well should drop the tool from the
  187. surface, for example with `--enabled-tools` or by choosing a preset that excludes it:
  188. ```bash
  189. npx @softeria/ms-365-mcp-server \
  190. --org-mode \
  191. --user-fields 'id,displayName,mail' \
  192. --enabled-tools '^(?!list-relevant-people$).*'
  193. ```
  194. CLI values take precedence over the environment variable. A value that names no fields fails
  195. at startup. When neither is configured, existing behavior is unchanged. Configure this in
  196. the LibreChat MCP server environment or command arguments; project-local `.env` files are
  197. intentionally restricted to application credentials and are not used for this setting.
  198. The allowlist is exhaustive for user properties: unlike an ordinary `$select`, `id` is only
  199. returned when it appears in the list, so include it if downstream tools need it to address a
  200. user. Collection annotations such as `@odata.nextLink` are retained so paging keeps working.
  201. If Graph returns none of the allowlisted properties, the response is projected to empty
  202. rather than returned untrimmed.
  203. ### Requesting extra scopes
  204. `--allowed-scopes` only ever _narrows_ the token request. To request a Graph scope that no bundled tool needs — for example to drive an endpoint via `graph-batch` — use `--extra-scopes` (or `MS365_MCP_EXTRA_SCOPES`). These scopes are appended verbatim to the token request, on top of the tool-derived scopes.
  205. ```bash
  206. npx @softeria/ms-365-mcp-server \
  207. --org-mode \
  208. --extra-scopes 'CopilotPackages.ReadWrite.All'
  209. ```
  210. This is for use with your own Azure app registration (`MS365_MCP_CLIENT_ID` / `MS365_MCP_CLIENT_SECRET`): the default Softeria app only declares a lean, fixed permission set, so request additional scopes against an app you control (your tenant admin consents to them there). CLI value takes precedence over the env var; an empty value fails at startup.
  211. ## Organization/Work Mode
  212. To access work/school features (Teams, SharePoint, etc.), enable organization mode using any of these flags:
  213. ```json
  214. {
  215. "mcpServers": {
  216. "ms365": {
  217. "command": "npx",
  218. "args": ["-y", "@softeria/ms-365-mcp-server", "--org-mode"]
  219. }
  220. }
  221. }
  222. ```
  223. Organization mode must be enabled from the start to access work account features. Without this flag, only personal
  224. account features (email, calendar, OneDrive, etc.) are available.
  225. ## Shared Mailbox Access
  226. To access shared mailboxes, you need:
  227. 1. **Organization mode**: Shared mailbox tools require `--org-mode` flag (work/school accounts only)
  228. 2. **Delegated permissions**: `Mail.Read.Shared` to read, `Mail.ReadWrite.Shared` to create, update or move
  229. messages, `Mail.Send.Shared` to send, reply or forward, and `Calendars.Read.Shared` for the shared calendar
  230. tools
  231. 3. **Exchange permissions**: The signed-in user must have been granted access to the shared mailbox
  232. 4. **Usage**: Use the shared mailbox's email address as the `user-id` parameter in the shared mailbox tools
  233. **Finding shared mailboxes**: Use the `list-users` tool to discover available users and shared mailboxes in your
  234. organization.
  235. Example: `list-shared-mailbox-messages` with `user-id` set to `shared-mailbox@company.com`
  236. ## Quick Start Example
  237. Test login in Claude Desktop:
  238. ![Login example](https://github.com/user-attachments/assets/27f57f0e-57b8-4366-a8d1-c0bdab79900c)
  239. ## Examples
  240. ![Image](https://github.com/user-attachments/assets/ed275100-72e8-4924-bcf2-cd8e1b4c6f3a)
  241. ## Integration
  242. ### Claude Desktop
  243. To add this MCP server to Claude Desktop, edit the config file under Settings > Developer.
  244. #### Personal Account (MSA)
  245. ```json
  246. {
  247. "mcpServers": {
  248. "ms365": {
  249. "command": "npx",
  250. "args": ["-y", "@softeria/ms-365-mcp-server"]
  251. }
  252. }
  253. }
  254. ```
  255. #### Work/School Account (Global)
  256. ```json
  257. {
  258. "mcpServers": {
  259. "ms365": {
  260. "command": "npx",
  261. "args": ["-y", "@softeria/ms-365-mcp-server", "--org-mode"]
  262. }
  263. }
  264. }
  265. ```
  266. #### Work/School Account (China 21Vianet)
  267. ```json
  268. {
  269. "mcpServers": {
  270. "ms365-china": {
  271. "command": "npx",
  272. "args": ["-y", "@softeria/ms-365-mcp-server", "--org-mode", "--cloud", "china"]
  273. }
  274. }
  275. }
  276. ```
  277. ### Claude Code CLI
  278. #### Personal Account (MSA)
  279. ```bash
  280. claude mcp add ms365 -- npx -y @softeria/ms-365-mcp-server
  281. ```
  282. #### Work/School Account (Global)
  283. ```bash
  284. # macOS/Linux
  285. claude mcp add ms365 -- npx -y @softeria/ms-365-mcp-server --org-mode
  286. # Windows (use cmd /c wrapper)
  287. claude mcp add ms365 -s user -- cmd /c "npx -y @softeria/ms-365-mcp-server --org-mode"
  288. ```
  289. #### Work/School Account (China 21Vianet)
  290. ```bash
  291. # macOS/Linux
  292. claude mcp add ms365-china -- npx -y @softeria/ms-365-mcp-server --org-mode --cloud china
  293. # Windows (use cmd /c wrapper)
  294. claude mcp add ms365-china -s user -- cmd /c "npx -y @softeria/ms-365-mcp-server --org-mode --cloud china"
  295. ```
  296. For other interfaces that support MCPs, please refer to their respective documentation for the correct
  297. integration method.
  298. ### Open WebUI
  299. Open WebUI supports MCP servers via HTTP transport with OAuth 2.1.
  300. 1. Start the server with HTTP mode and Dynamic Client Registration on (Open WebUI needs it):
  301. ```bash
  302. npx @softeria/ms-365-mcp-server --http --enable-dynamic-registration
  303. ```
  304. 2. In Open WebUI, go to **Admin Settings → Tools** (`/admin/settings/tools`) → **Add Connection**:
  305. - **Type**: MCP Streamable HTTP
  306. - **URL**: Your MCP server URL with `/mcp` path
  307. - **Auth**: OAuth 2.1
  308. 3. Click **Register Client**.
  309. > **Note**: In HTTP mode clients identify themselves with [Client ID Metadata Documents](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents), which is on by default (`--no-client-metadata-documents` turns it off for servers without direct outbound HTTPS). Dynamic Client Registration is deprecated by the MCP spec and off by default; turn it on with `--enable-dynamic-registration` (or `MS365_MCP_ENABLE_DCR=true`) for clients that only support DCR, such as Open WebUI. If using a custom Azure Entra app, the platform type for your redirect URI depends on whether the app has a client secret: with a secret use "Web", without one use "Mobile and desktop applications" (never "Single-page application").
  310. **Quick test setup** using the default Azure app (ID `ms-365` and `localhost:8080` are pre-configured):
  311. ```bash
  312. docker run -d -p 8080:8080 \
  313. -e WEBUI_AUTH=false \
  314. -e OPENAI_API_KEY \
  315. ghcr.io/open-webui/open-webui:main
  316. npx @softeria/ms-365-mcp-server --http --enable-dynamic-registration
  317. ```
  318. Then add connection with URL `http://localhost:3000/mcp` and ID `ms-365`.
  319. ![Open WebUI MCP Connection](https://github.com/user-attachments/assets/dcab71dd-cf02-4bcb-b7db-5725d6be4064)
  320. > **Running in Docker behind a reverse proxy?** Set `--public-url https://your-domain.com` so the OAuth authorize URL handed to the user's browser is reachable from outside the container network. See [docs/deployment.md](docs/deployment.md) for the full guide.
  321. ### Local Development
  322. For local development or testing:
  323. ```bash
  324. # From the project directory
  325. claude mcp add ms -- npx tsx src/index.ts --org-mode
  326. ```
  327. Or configure Claude Desktop manually:
  328. ```json
  329. {
  330. "mcpServers": {
  331. "ms365": {
  332. "command": "node",
  333. "args": ["/absolute/path/to/ms-365-mcp-server/dist/index.js", "--org-mode"]
  334. }
  335. }
  336. }
  337. ```
  338. > **Note**: Run `npm run build` after code changes to update the `dist/` folder.
  339. ### Authentication
  340. > ⚠️ You must authenticate before using tools.
  341. The server supports three authentication methods:
  342. #### 1. Device Code Flow (Default)
  343. For interactive authentication via device code:
  344. - **MCP client login**:
  345. - Call the `login` tool (auto-checks existing token)
  346. - If needed, get URL+code, visit in browser
  347. - Use `verify-login` tool to confirm
  348. - **CLI login**:
  349. ```bash
  350. npx @softeria/ms-365-mcp-server --login
  351. ```
  352. Follow the URL and code prompt in the terminal.
  353. Tokens are cached securely in your OS credential store (fallback to file).
  354. #### 2. OAuth Authorization Code Flow (HTTP mode only)
  355. When running with `--http`, the server **requires** OAuth authentication:
  356. ```bash
  357. npx @softeria/ms-365-mcp-server --http 3000
  358. ```
  359. This mode:
  360. - Advertises OAuth capabilities to MCP clients
  361. - Provides OAuth endpoints at `/auth/*` (authorize, token, metadata)
  362. - **Requires** `Authorization: Bearer <token>` for all MCP requests
  363. - Validates tokens with Microsoft Graph API
  364. - **Disables** login/logout tools by default (use `--enable-auth-tools` to enable them)
  365. MCP clients will automatically handle the OAuth flow when they see the advertised capabilities.
  366. ##### Setting up Azure AD for OAuth Testing
  367. To use OAuth mode with custom Azure credentials (recommended for production), you'll need to set up an Azure AD app
  368. registration:
  369. 1. **Create Azure AD App Registration**:
  370. - Go to [Azure Portal](https://portal.azure.com)
  371. - Navigate to Azure Active Directory → App registrations → New registration
  372. - Set name: "MS365 MCP Server"
  373. 2. **Configure Redirect URIs**:
  374. - **Configure the OAuth callback URI**: Go to your app registration and on the left side, go to Authentication.
  375. - Under Platform configurations:
  376. - Click Add a platform (if you don’t already see one for "Mobile and desktop applications" / "Public client").
  377. - Choose Mobile and desktop applications or Public client/native (mobile & desktop) (label depends on portal version).
  378. 3. **Testing with MCP Inspector (`npm run inspector`)**:
  379. - Go to your app registration and on the left side, go to Authentication.
  380. - Under Platform configurations:
  381. - Click Add a platform (if you don’t already see one for "Web").
  382. - Choose Web.
  383. - Configure the following redirect URIs
  384. - `http://localhost:6274/oauth/callback`
  385. - `http://localhost:6274/oauth/callback/debug`
  386. - `http://localhost:3000/callback` (optional, for server callback)
  387. 4. **Get Credentials**:
  388. - Copy the **Application (client) ID** from Overview page
  389. - Go to Certificates & secrets → New client secret → Copy the secret value (optional for public apps)
  390. 5. **Configure Environment Variables**:
  391. Create a `.env` file in your project root:
  392. ```env
  393. MS365_MCP_CLIENT_ID=your-azure-ad-app-client-id-here
  394. MS365_MCP_CLIENT_SECRET=your-secret-here # Optional for public apps
  395. MS365_MCP_TENANT_ID=common
  396. ```
  397. With these configured, the server will use your custom Azure app instead of the built-in one.
  398. > **Note**: `.env` is read from the directory the server is started in, and the MCP client decides what
  399. > that is. Only `MS365_MCP_CLIENT_ID`, `MS365_MCP_CLIENT_SECRET`, `MS365_MCP_TENANT_ID` and
  400. > `MS365_MCP_CLOUD_TYPE` are read from it. Every other variable listed above must be set in your shell
  401. > or MCP client config - `READ_ONLY`, `ENABLED_TOOLS` and `ENABLED_TOOLS_FILE` included, so a `.env`
  402. > cannot restrict the tools either. Any of them found in a `.env` is ignored with a warning on stderr.
  403. #### 3. Bring Your Own Token (BYOT)
  404. If you are running ms-365-mcp-server as part of a larger system that manages Microsoft OAuth tokens externally, you can
  405. provide an access token directly to this MCP server:
  406. ```bash
  407. MS365_MCP_OAUTH_TOKEN=your_oauth_token npx @softeria/ms-365-mcp-server
  408. ```
  409. This method:
  410. - Bypasses the interactive authentication flows
  411. - Use your pre-existing OAuth token for Microsoft Graph API requests
  412. - Does not handle token refresh (token lifecycle management is your responsibility)
  413. #### 4. App Mode (application permissions, no signed-in user)
  414. > **Warning**: application permissions apply to the whole tenant. `Mail.Read` granted to the app reads every
  415. > mailbox, `Files.ReadWrite.All` writes every OneDrive and site, and whoever can call this server acts with
  416. > them. Grant the fewest permissions you can. To limit which mailboxes and calendars it reaches, grant the
  417. > mail and calendar permissions with
  418. > [RBAC for Applications in Exchange Online](https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac)
  419. > **instead of** in Microsoft Entra: the two add up, so an Entra `Mail.Read` grant left in place still reaches
  420. > every mailbox. SharePoint sites can be narrowed with `Sites.Selected`.
  421. For unattended agents that act as the app registration itself (client credentials):
  422. ```bash
  423. MS365_MCP_CLIENT_ID=<your app id> \
  424. MS365_MCP_TENANT_ID=<your tenant id or domain> \
  425. MS365_MCP_CLIENT_SECRET=<secret> \
  426. npx @softeria/ms-365-mcp-server --app-mode --read-only
  427. ```
  428. - Use your own app registration with **application** permissions and admin consent, and set exactly one
  429. credential:
  430. - `MS365_MCP_CLIENT_SECRET`
  431. - `MS365_MCP_CLIENT_CERTIFICATE_PATH`: a PEM file with the certificate and its unencrypted private key
  432. - `MS365_MCP_FEDERATED_TOKEN_FILE`: a token from an identity provider the app trusts through
  433. [workload identity federation](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation),
  434. read again on every token request. On AKS set it to `$AZURE_FEDERATED_TOKEN_FILE`, which Kubernetes
  435. keeps fresh. A GitHub Actions OIDC token is valid for 5 minutes, so writing it to a file once only
  436. covers the first Graph token (about an hour) unless something rewrites the file. If Entra answers
  437. `AADSTS700213`, set the federated credential's subject to the one quoted in the error (GitHub's
  438. subject can include the owner and repo ids).
  439. `MS365_MCP_TENANT_ID` must be a real tenant, not `common`.
  440. - On an Azure host (App Service, Container Apps, VM, ...) set `MS365_MCP_MANAGED_IDENTITY=system`, or the
  441. client id of a user-assigned identity, instead. No app registration, tenant id or secret is needed, and
  442. Key Vault (`MS365_MCP_KEYVAULT_URL`) is not read. Graph
  443. application permissions for a managed identity can't be granted in the portal;
  444. [assign them with PowerShell or the Graph API](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-to-assign-app-role-managed-identity).
  445. On Azure Container Instances, give the container one kind of identity: with both a system- and a
  446. user-assigned identity, the system-assigned token request fails there.
  447. - Tokens are renewed automatically. Nothing is cached on disk.
  448. - Only tools that work with application permissions are offered: the `/users/{user-id}` mail and calendar
  449. tools (pass a UPN or object id as `user-id`), users and groups, OneDrive/SharePoint drives and lists, Planner,
  450. Teams reads, presence, places and subscriptions. `/me` tools, Excel, OneNote and sending Teams chat or channel
  451. messages are not available, because Graph does not support them with application permissions.
  452. - `--list-permissions --app-mode` lists the application permissions the offered tools use. `--allowed-scopes`,
  453. `--enabled-tools`, `--preset` and `--read-only` narrow the surface as usual.
  454. - `--verify-login --app-mode` gets a token and shows the app id, tenant and granted roles (Exchange RBAC
  455. grants do not show up there).
  456. - The `mail`, `calendar` and `outlook` presets are built from `/me` tools and leave little in app mode; the
  457. `/users/{user-id}` mail and calendar tools are in `work`.
  458. - stdio only. It refuses `--http`, `--obo`, `--extra-scopes`, `MS365_MCP_OAUTH_TOKEN` and the
  459. login/account options.
  460. - Webinar tools also need an application access policy assigned to the organizer.
  461. > **Note**: HTTP mode requires authentication. For unauthenticated testing, use stdio mode with device code flow.
  462. >
  463. > **Authentication Tools**: In HTTP mode, login/logout tools are disabled by default since OAuth handles authentication.
  464. > Use `--enable-auth-tools` if you need them available.
  465. ## Multi-Account Support
  466. Use a single server instance to serve multiple Microsoft accounts. When more than one account is logged in, an `account` parameter is automatically injected into every tool, allowing you to specify which account to use per tool call.
  467. **Login multiple accounts** (one-time per account):
  468. ```bash
  469. # Login first account (device code flow)
  470. npx @softeria/ms-365-mcp-server --login
  471. # Follow the device code prompt, sign in as personal@outlook.com
  472. # Login second account
  473. npx @softeria/ms-365-mcp-server --login
  474. # Follow the device code prompt, sign in as work@company.com
  475. ```
  476. **List configured accounts:**
  477. ```bash
  478. npx @softeria/ms-365-mcp-server --list-accounts
  479. ```
  480. **Use in tool calls:** Pass `"account": "work@company.com"` in any tool request:
  481. ```json
  482. { "tool": "list-mail-messages", "arguments": { "account": "work@company.com" } }
  483. ```
  484. **Behavior:**
  485. - With a **single account** configured, it auto-selects (no `account` parameter needed).
  486. - With **multiple accounts** and no `account` parameter, the server uses the selected default or returns a helpful error listing available accounts.
  487. - **100% backward compatible**: existing single-account setups work unchanged.
  488. - The `account` parameter accepts email address (e.g. `user@outlook.com`) or MSAL `homeAccountId`.
  489. ### Strict Account Pinning
  490. Headless stdio deployments can pin the local MSAL cache to one expected Microsoft account:
  491. ```bash
  492. # Username matching is case-insensitive
  493. MS365_MCP_EXPECTED_USERNAME=work@company.com npx @softeria/ms-365-mcp-server --login
  494. # Or pin the exact MSAL homeAccountId shown by --list-accounts
  495. npx @softeria/ms-365-mcp-server --expected-home-account-id <homeAccountId> --login
  496. ```
  497. Use `--list-accounts` to discover `homeAccountId` values. The MCP `list-accounts` tool intentionally hides account IDs, so use the CLI for exact ID pinning.
  498. Pinning is opt-in and local-MSAL only:
  499. - CLI values (`--expected-username`, `--expected-home-account-id`) take precedence over `MS365_MCP_EXPECTED_USERNAME` and `MS365_MCP_EXPECTED_HOME_ACCOUNT_ID`.
  500. - Supplying an empty pin value fails at startup instead of being ignored.
  501. - Username pins are compared case-insensitively; `homeAccountId` pins are exact.
  502. - If both pins are set, they must resolve to the same cached account.
  503. - Local stdio startup fails fast when the expected account is not in the token cache. Bootstrap by setting the pin, running `--login`, then starting the headless server.
  504. - Device-code and browser logins reject a missing or mismatched account before persisting the selected account or token cache.
  505. - Pinning collapses the effective MCP mode to single-account: the server does not advertise an `account` parameter and MCP instructions do not suggest account switching.
  506. - `--http`, `--obo`, and `MS365_MCP_OAUTH_TOKEN` use request-provided tokens for Graph calls, so account pins are warning-only in those modes. If HTTP auth tools are enabled, the pin still applies to those local MSAL helper flows.
  507. - `--logout` clears all cached accounts, including the pinned account. For surgical cleanup, prefer `--remove-account <id>`.
  508. > **For MCP multiplexers (Legate, Governor):** Multi-account mode replaces the N-process pattern. Instead of spawning one server per account, a single instance handles all accounts via the `account` parameter, reducing tool duplication from N×110 to 110.
  509. ## Tool Presets
  510. To reduce initial connection overhead and token usage, use preset tool categories instead of loading the full tool set:
  511. ```bash
  512. npx @softeria/ms-365-mcp-server --preset mail
  513. npx @softeria/ms-365-mcp-server --list-presets # See all available presets
  514. ```
  515. Available presets: `mail`, `calendar`, `files`, `personal`, `work`, `excel`, `contacts`, `tasks`, `onenote`, `search`, `users`, `outlook`, `onedrive`, `teams`, `teams-write`, `all`
  516. See **[PRESETS.md](PRESETS.md)** for the full list of tools each preset unlocks (regenerated on `npm run generate`).
  517. Each endpoint in `endpoints.json` declares which presets it belongs to via a `presets` array, so every preset is an exact tool-name allow-list that never over-matches across apps (e.g. `mail` does not include shared-mailbox tools; those are in `work`). The universal binary reader `download-bytes` is included in every preset except `teams-write`, so whatever an app returns (a file, an attachment, a photo, a recording) can always be fetched; `get-download-url` (a pre-authenticated URL for drive/SharePoint files) rides with the drive-backed presets, and joins every other preset (bar `teams-write`) when HTTP mode runs with `--enable-attachment-urls`. So a preset that can find a file can always read its bytes.
  518. The `outlook`, `onedrive` and `teams` presets are app-scoped: they expose exactly one Microsoft app. Use these for "expose exactly one app" deployments:
  519. ```bash
  520. # Outlook only (mail + calendar + contacts; no shared mailboxes, no files)
  521. npx @softeria/ms-365-mcp-server --preset outlook
  522. # Teams only (requires --org-mode)
  523. npx @softeria/ms-365-mcp-server --org-mode --preset teams
  524. ```
  525. The `teams-write` preset is the send-only counterpart to `--read-only`: send in chats, send/reply in channels, list chats/teams/channels by name, and activity notifications - no message reading and no byte downloaders. The requested token is minimal by construction (`Chat.ReadBasic`, the `*.Send` scopes, and basic team/channel listing - nothing that can read message content):
  526. ```bash
  527. npx @softeria/ms-365-mcp-server --org-mode --preset teams-write
  528. ```
  529. ## Dynamic Tool Discovery
  530. Instead of loading every tool upfront, use dynamic discovery so the LLM finds and loads tools only when it needs them:
  531. ```bash
  532. npx @softeria/ms-365-mcp-server --discovery
  533. ```
  534. For hosts that eagerly load every advertised schema, combine `--discovery` with the smallest
  535. useful presets or tool filter. Hosts with native deferred tool loading can use that with
  536. direct registration; measure before adding a second discovery layer.
  537. Other existing ways to keep reads bounded:
  538. - Use `read-mail-text` for mail triage, honor `truncated`, and retrieve the full or exact body when needed.
  539. - Query small calendar windows with modest `top` and `select`; follow continuation only when the task needs more.
  540. - Treat experimental TOON output as a measured alternative after narrowing tools and reads.
  541. Bounded collection reads with `fetchAllPages: true` retain an outstanding `@odata.nextLink`
  542. when a page/item cap stops the merge; `_meta.result_has_more` then remains true. Exhausted
  543. collections have neither a next link nor more results. Where a tool advertises `skiptoken`,
  544. pass back the returned link containing `$skip` or `$skiptoken` and retain the original
  545. query/selection to continue without restarting. That parameter cannot replay drive/sites
  546. delta links carrying `token=`; those links are still returned, but manual resume through
  547. `skiptoken` is unsupported. The item cap is page-granular, not a byte or token budget.
  548. ### Hybrid discovery with direct tools
  549. Keep the full enabled catalogue discoverable while exposing frequent operations directly:
  550. ```bash
  551. npx @softeria/ms-365-mcp-server --org-mode --discovery \
  552. --eager-tools list-mail-messages,get-calendar-view,download-bytes
  553. ```
  554. `--eager-tools` accepts comma-separated **exact** Graph or utility tool names,
  555. not a regular expression or preset. `MS365_MCP_EAGER_TOOLS` is the environment
  556. fallback; the CLI wins. An empty or whitespace-only environment value is treated
  557. as unset, including without discovery; an explicitly empty CLI option is still
  558. invalid. The option requires `--discovery`. Empty entries and
  559. unknown names fail startup, including in HTTP mode. Duplicate names are registered once.
  560. Direct tools use the same schemas, annotations and execution handlers as normal
  561. mode. They also remain searchable and executable through discovery. Existing
  562. `--preset`, `--enabled-tools`, `--allowed-scopes`, `--read-only`, organization-mode
  563. and transport restrictions apply first: an eager selection cannot enable a
  564. filtered-out tool or add permissions. Recognized but unavailable tools are
  565. omitted with a diagnostic logged once per server instance. HTTP still excludes
  566. server-local file tools.
  567. Select a small set: exposing many generated Graph schemas can consume substantial
  568. model context. This option does not shrink individual schemas. Without
  569. `--eager-tools`, discovery and normal registration behave as before.
  570. ## MCP Apps (experimental)
  571. With `--enable-mcp-apps` (or `MS365_MCP_ENABLE_MCP_APPS=true`), tools that have an
  572. [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) view show it in hosts that
  573. support MCP Apps, such as Claude, ChatGPT and VS Code. Other hosts ignore it and get the
  574. same tool results as before.
  575. The first view is a OneDrive/SharePoint file browser for `list-folder-files`: open
  576. folders, go back through the folder path, load more items and open files in the browser.
  577. The view gets its data through the host, which calls `list-folder-files` on this server
  578. again, so it needs no network access of its own.
  579. - It has no effect with `--toon`, since the view reads JSON results.
  580. - With `--discovery`, only tools published directly with `--eager-tools` show a view,
  581. e.g. `--discovery --eager-tools list-folder-files`.
  582. ## CLI Options
  583. The following options can be used when running ms-365-mcp-server directly from the command line:
  584. ```
  585. --login Login using device code flow
  586. --logout Log out and clear saved credentials
  587. --verify-login Verify login without starting the server
  588. --list-permissions List required Graph API permissions and exit (respects --org-mode, --preset, --enabled-tools, --enabled-tools-file, --allowed-scopes)
  589. --org-mode Enable organization/work mode from start (includes Teams, SharePoint, etc.)
  590. --work-mode Alias for --org-mode
  591. --force-work-scopes Backwards compatibility alias for --org-mode (deprecated)
  592. --cloud <type> Microsoft cloud environment: global (default), china (21Vianet) or gcc-high
  593. --allowed-scopes <scopes> Limit exposed tools to Graph scopes covered by this allowlist
  594. --extra-scopes <scopes> Append additional Graph scopes to the token request (for use with your own app registration + graph-batch)
  595. --expected-username <username> Require local MSAL auth to use this account username
  596. --expected-home-account-id <id> Require local MSAL auth to use this exact homeAccountId
  597. ```
  598. ### Server Options
  599. When running as an MCP server, the following options can be used:
  600. ```
  601. -v Enable verbose logging
  602. --read-only Start server in read-only mode, disabling write operations
  603. --http [port] Use Streamable HTTP transport instead of stdio (optionally specify port, default: 3000)
  604. Starts Express.js server with MCP endpoint at /mcp. Bound to a loopback host
  605. (e.g. --http 127.0.0.1:3000 or --http [::1]:3000) with no --public-url, it
  606. rejects requests whose Host or Origin is not localhost (not applied to the
  607. --attachment-port listener)
  608. --http-local-file-tools Register download-bytes-to-file over HTTP. Anyone who can reach the port
  609. can write files as the server's user (without a valid token, only an empty
  610. file that is removed again), so enable it only on a single-user machine.
  611. With MS365_MCP_UPLOAD_DIRS set it also registers upload-attachment-from-file,
  612. which reads files from those directories.
  613. Refused unless --http binds a loopback host with no --public-url and no
  614. --trust-proxy-auth
  615. --app-mode Use application permissions (client credentials) with no signed-in user. stdio only
  616. (see "App Mode" under Authentication)
  617. --enable-auth-tools Enable login/logout tools when using HTTP mode (disabled by default in HTTP mode)
  618. --enable-attachment-urls Let get-download-url mint a server-served URL for byte resources Graph
  619. exposes no pre-authenticated URL for (see "Server-Minted Attachment URLs").
  620. Also adds get-download-url to any --preset that lacks it (except teams-write)
  621. --attachment-port <port> Serve /attachment on its own listener on this port instead of on the
  622. MCP app, so a fetcher that can read attachments cannot also reach /mcp
  623. (requires --enable-attachment-urls; see "Splitting the attachment listener")
  624. --attachment-host <host> Interface the --attachment-port listener binds. Defaults to whatever
  625. --http bound, which with a wildcard --http leaves BOTH ports on every
  626. interface and so isolates nothing — set this to make the split real
  627. (requires --attachment-port; see "Splitting the attachment listener")
  628. --enable-dynamic-registration Turn on OAuth Dynamic Client Registration in HTTP mode (off by default; needed by
  629. DCR-only clients such as Open WebUI). Equivalent env var: MS365_MCP_ENABLE_DCR=true
  630. --no-dynamic-registration Keep Dynamic Client Registration off even if it is turned on elsewhere.
  631. Equivalent env var: MS365_MCP_DISABLE_DCR=true
  632. --no-client-metadata-documents Turn off Client ID Metadata Documents in HTTP mode, for servers that cannot
  633. reach the client's host directly; turn on DCR too so Claude can fall back to it.
  634. Equivalent env var: MS365_MCP_DISABLE_CIMD=true
  635. --enabled-tools <pattern> Filter tools using regex pattern (e.g., "excel|contact" to enable Excel and Contact tools)
  636. --enabled-tools-file <path> Filter tools using a file with one regex per line (same as --enabled-tools;
  637. blank lines and whole-line # comments ignored). Overrides --enabled-tools;
  638. overridden by --preset. Equivalent env var: ENABLED_TOOLS_FILE
  639. --preset <names> Use preset tool categories (comma-separated). See "Tool Presets" section above
  640. --list-presets List all available presets and exit
  641. --toon (experimental) Enable TOON output format for 30-60% token reduction
  642. --blob-output File download tools answer an MCP EmbeddedResource with the file instead of
  643. base64 JSON in a text block (see MS365_MCP_BLOB_OUTPUT below)
  644. --discovery Dynamic tool discovery: loads tools on demand to reduce initial token usage (see "Dynamic Tool Discovery" above)
  645. --enable-mcp-apps (experimental) Show the interactive MCP Apps views, starting with a OneDrive/SharePoint
  646. file browser, in hosts that support them (see "MCP Apps" above)
  647. --public-url <url> Public base URL for OAuth when behind a reverse proxy (see Open WebUI section and docs/deployment.md)
  648. ```
  649. The account tools (`login`, `logout`, `verify-login`, `list-accounts`, `select-account`, `remove-account`) follow the same filters: `--enabled-tools` applies to them, every `--preset` includes them, and `--read-only` or `MS365_MCP_OAUTH_TOKEN` keeps only `verify-login` and `list-accounts`.
  650. Environment variables:
  651. - `READ_ONLY=true|1`: Alternative to --read-only flag
  652. - `ENABLED_TOOLS`: Filter tools using a regex pattern (alternative to --enabled-tools flag)
  653. - `ENABLED_TOOLS_FILE`: Path to a file with one regex per line (alternative to --enabled-tools-file). Blank lines and whole-line `#` comments are dropped, then lines are joined with `|` (same as `ENABLED_TOOLS=line1|line2|…`). Layering (later wins): `--enabled-tools` → `--enabled-tools-file` → `--preset` → `ENABLED_TOOLS` → `ENABLED_TOOLS_FILE`
  654. - `MS365_MCP_ORG_MODE=true|1`: Enable organization/work mode (alternative to --org-mode flag)
  655. - `MS365_MCP_FORCE_WORK_SCOPES=true|1`: Backwards compatibility for MS365_MCP_ORG_MODE
  656. - `MS365_MCP_APP_MODE=true|1`: Enable app mode (alternative to --app-mode flag)
  657. - `MS365_MCP_CLIENT_CERTIFICATE_PATH=<path>`: PEM file with a certificate and its unencrypted private key, used instead of `MS365_MCP_CLIENT_SECRET` in app mode
  658. - `MS365_MCP_FEDERATED_TOKEN_FILE=<path>`: Federated token (workload identity federation), used instead of a secret or certificate in app mode
  659. - `MS365_MCP_MANAGED_IDENTITY=system|<client id>`: Use the host's managed identity in app mode, instead of an app registration
  660. - `MS365_MCP_OUTPUT_FORMAT=toon`: Enable TOON output format (alternative to --toon flag)
  661. - `MS365_MCP_ENABLE_MCP_APPS=true|1`: Show the MCP Apps views (alternative to --enable-mcp-apps; see "MCP Apps" above)
  662. - `MS365_MCP_MAX_TOP=<n>`: Hard cap for Graph `$top` / `top` on list requests (positive integer). When the model passes a larger value, the server clamps it to `n` so responses stay smaller. Example: `MS365_MCP_MAX_TOP=15`
  663. - `MS365_MCP_MAX_PAGES=<n>`: Maximum number of pages followed when a tool is called with `fetchAllPages: true` (positive integer, default `100`). Bounds memory and latency for large result sets.
  664. - `MS365_MCP_MAX_ITEMS=<n>`: Maximum number of items accumulated when `fetchAllPages: true` (positive integer, default `10000`). Pagination stops after a whole page reaches this count, so the result can exceed the cap.
  665. - `MS365_MCP_TOOL_DEFINITION_BUDGET=<bytes>`: Opt in to trimming oversized request-body schemas so every tool fits a hosted connector's tool-definition budget (1 048 576 bytes of input schema per connector, admitted alphabetically — a tool that no longer fits is silently skipped). `4096` keeps a full org surface at ~78 % of that budget. Only bodies above the ration are trimmed, nested descriptions before structure, field names last. Unset (default): nothing is trimmed; the server still logs the total input-schema bytes served and, in HTTP mode, warns when the surface exceeds the connector budget.
  666. - `MS365_MCP_ALLOW_PAGINATION=0|false|no`: Disable multi-page following entirely. When set, the `fetchAllPages` parameter is not advertised on tools, and any request that still passes it returns only the first page (default: pagination enabled).
  667. - `MS365_MCP_BLOB_OUTPUT=true|1`: File download tools (`download-bytes`, `get-mail-message-mime`, `get-shared-mailbox-message-mime`, `get-mail-attachment-content`, `get-shared-mailbox-attachment-content`) answer a short JSON text block (`name`, `contentType`, `size`) and an MCP `EmbeddedResource` with `BlobResourceContents` (`uri`, `mimeType`, `blob`) instead of base64 JSON in text. The `uri`'s last segment is the optional `fileName` argument. Default: off. Alternative to the --blob-output flag.
  668. - `MS365_MCP_BLOB_MAX_BYTES=<n>`: With blob output on, the largest file a download tool reads (positive integer, default `5242880`). The server stops reading past it and answers an error naming the limit.
  669. - `MS365_MCP_BODY_FORMAT=html`: Return email bodies as HTML instead of plain text (default: text)
  670. - `MS365_MCP_OBO_ALLOWED_TENANTS=<ids>` / `MS365_MCP_OBO_ALLOWED_USERS=<ids>`: With `--obo`, only callers whose token `tid` (tenant id) / `oid` (user object id) is listed may use the server; others get 403 before any On-Behalf-Of exchange. Comma or space separated; unset = everyone. The claims are read without verifying the signature, which Entra verifies during the exchange, so a token that lies about them still gets no Graph token. A token Entra rejects at the exchange (bad signature, expired, wrong audience, consent needed) gets 401 with a `WWW-Authenticate` challenge so the client signs in again
  671. - `MS365_MCP_READ_MAIL_TEXT_MAX_CHARS=<n>`: Largest result `read-mail-text` returns, in characters (default `80000`). A larger result is refused whole, naming the largest messages, rather than cut (see Reading Mail as Clean Text below)
  672. - `MS365_MCP_MESSAGE_SIGNOFF_PREFIX=<text>`: Signoff prepended to outgoing messages so recipients can tell they were agent-sent, e.g. `🤖`. Default: none. CLI equivalent: `--message-signoff-prefix <text>` (see Message Signoff below)
  673. - `MS365_MCP_MESSAGE_SIGNOFF_SUFFIX=<text>`: Signoff appended to outgoing messages. Default: none. CLI equivalent: `--message-signoff-suffix <text>`. `--no-message-signoff` disables both (see Message Signoff below)
  674. - `MS365_MCP_RATE_LIMIT_DISABLED=true|1`: Disable per-IP rate limiting in HTTP mode (default: enabled — 30 req/min on `/authorize`, `/token`, `/register`; 120 req/min on `/mcp`)
  675. - `MS365_MCP_PKCE_SECRET=<32+ random characters>`: For HTTP mode with more than one instance (replicas, serverless, a restart between sign-in steps). The server derives its side of the two-leg PKCE flow from this secret instead of keeping it in process memory, so `/token` works on any instance that has the same secret. Without it, `/token` must reach the instance that served `/authorize`, or sign-in fails with `AADSTS501481`. A shorter secret fails startup
  676. - `MS365_MCP_TRUST_PROXY_HOPS=<n>`: Number of trusted reverse-proxy hops in HTTP mode (default `1`). Accurate per-IP rate limiting depends on this matching your deployment — set to the number of proxies in front of the server, `0` to use the raw socket peer IP, or a comma-separated subnet list
  677. - `MS365_MCP_ATTACHMENT_PORT=<port>`: Serve the attachment route on its own listener on this port (alternative to --attachment-port; requires `--enable-attachment-urls`)
  678. - `MS365_MCP_ATTACHMENT_HOST=<host>`: Interface the `MS365_MCP_ATTACHMENT_PORT` listener binds (alternative to --attachment-host; requires `--attachment-port`). Defaults to the host `--http` bound — which for a wildcard `--http` means both ports answer everywhere and the port split isolates nothing. See "Splitting the attachment listener"
  679. - `MS365_MCP_HTTP_LOCAL_FILE_TOOLS=true|1`: Register download-bytes-to-file, and upload-attachment-from-file when `MS365_MCP_UPLOAD_DIRS` is set, over HTTP (alternative to --http-local-file-tools; same restrictions)
  680. - `MS365_MCP_UPLOAD_DIRS=<dirs>`: Directories `upload-attachment-from-file` may read from, as absolute paths separated like `PATH`. Unset (the default) leaves the tool unregistered. See "Attaching a local file in stdio mode"
  681. - `MS365_MCP_CLOUD_TYPE=global|china|gcc-high`: Microsoft cloud environment (alternative to --cloud flag)
  682. - `MS365_MCP_GRAPH_BASE_URL=<url>`: Send Graph API requests to this base URL instead of the cloud's `graph.microsoft.com` (e.g. `http://127.0.0.1:10255/tenant-a/graph` for an egress proxy that originates TLS itself). Absolute http(s) URL without query or fragment; a path prefix is kept, so requests go to `<url>/v1.0/...`. The login authority and the On-Behalf-Of token resource are unchanged. Two things bypass it: `get-download-url` returns Graph's pre-authenticated SharePoint URL, and the `302` from `/content` points straight at SharePoint, so whoever follows either connects to SharePoint directly; if you control egress, allow those SharePoint hosts or disable those tools. Not read from `.env`
  683. - `LOG_LEVEL`: Set logging level (default: 'info')
  684. - `SILENT=true|1`: Disable console output
  685. - `MS365_MCP_REDACT_PII=false|0`: Disable scrubbing of JWTs, Bearer headers, OAuth token fields, and email addresses from log messages, and log tool parameters, request bodies, URLs, error messages and crash dumps in full instead of by shape only (default: enabled). The server handles live Graph bearer tokens, so redaction is on unless you opt out for fully verbose local debugging.
  686. - `MS365_MCP_CLIENT_ID`: Custom Azure app client ID (defaults to built-in app)
  687. - `MS365_MCP_TENANT_ID`: Custom tenant ID (defaults to 'common' for multi-tenant). **Personal Microsoft accounts should set this to `consumers`** - as of June 2026, refresh tokens issued via the default 'common' authority are rejected at the first refresh, so sessions die roughly an hour after login
  688. - `MS365_MCP_OAUTH_TOKEN`: Pre-existing OAuth token for Microsoft Graph API (BYOT method)
  689. - `MS365_MCP_KEYVAULT_URL`: Azure Key Vault URL for secrets management (see Azure Key Vault section)
  690. - `MS365_MCP_TOKEN_CACHE_PATH`: Custom file path for MSAL token cache (see Token Storage below)
  691. - `MS365_MCP_SELECTED_ACCOUNT_PATH`: Custom file path for selected account metadata (see Token Storage below)
  692. - `MS365_MCP_AUTH_CACHE_COMMAND`: External executable wrapper for provider-neutral auth-cache storage (see Token Storage below)
  693. - `MS365_MCP_AUTH_CACHE_COMMAND_TIMEOUT_MS`: Per-invocation timeout for `MS365_MCP_AUTH_CACHE_COMMAND` (default: `10000`)
  694. - `MS365_MCP_EXPECTED_USERNAME`: Require local MSAL auth to use this Microsoft account username (case-insensitive; CLI flag takes precedence)
  695. - `MS365_MCP_EXPECTED_HOME_ACCOUNT_ID`: Require local MSAL auth to use this exact MSAL homeAccountId (CLI flag takes precedence)
  696. ## Reading Mail as Clean Text
  697. `read-mail-text` returns messages as text with the bulk junk removed. Graph's
  698. plain-text body is still mostly not the message: links are wrapped in Safe Links
  699. or tracking redirects several hundred characters long, marketing mail pads its
  700. preheader with invisible characters, images become `[https://…png]` lines, and
  701. replies carry the whole quoted thread. On a real mailbox, 20 inbox messages came
  702. to about 280,000 characters through `list-mail-messages` and 70,000 through
  703. `read-mail-text`.
  704. The rule is: remove obvious junk, never cut or rewrite the message; anything
  705. ambiguous is kept. It removes runs of invisible padding characters, image
  706. placeholders (a bracketed address of an image file), and quoted reply history
  707. from its header down (a dated `On … wrote:`, also `>`-quoted, an Outlook
  708. `From:/Sent:` block, `-----Original Message-----`). Forwards keep the forwarded
  709. content: a subject starting `FW:` / `Fwd:` or a localised prefix (`VS:`, `WG:`,
  710. `TR:`, `RV:`, `I:`, `ENC:`, …, also after tags such as `[EXTERNAL]`), or history
  711. directly under a `Forwarded message` / `Begin forwarded message:` marker. Links are kept:
  712. Safe Links, Proofpoint URL Defense and Google redirects are unwrapped to the real
  713. address, tracking parameters (`utm_*` and similar) are dropped, and only an
  714. address still longer than 300 characters (a tracking redirect) is shortened to
  715. `⟦link: domain⟧`. Line endings become `\n`, and the marker brackets are
  716. reserved: a body's own `⟦ ⟧` appear as `[ ]`, so text cannot pose as a marker.
  717. Everything else — signatures, footers, whitespace, repeated links — is left as
  718. the message has it. `get-mail-message` returns the raw body.
  719. - `messageIds` (up to 20, one `$batch`), or `folderId` with optional `top`
  720. (max 20), `filter` or `search`.
  721. - Each message is cut to `maxChars` characters, default 3,000 (marked
  722. `truncated`): a page of 20 then fits the result limit, and a typical message
  723. is whole. Ticket systems that repeat their history in every update put the
  724. newest entry first, so the cut keeps it. Pass a larger `maxChars` (up to
  725. 300,000; a raw body beyond that is cleaned only that far) for the whole of a
  726. long message; `get-mail-message` has the raw body.
  727. - Returns `[{ id, from, to, cc, subject, received, hasAttachments, text, chars, truncated }]`;
  728. an unknown id comes back as `{ id, error }`.
  729. - A result over `MS365_MCP_READ_MAIL_TEXT_MAX_CHARS` (default 80,000) is refused
  730. whole with the largest messages listed, so the agent narrows the query instead
  731. of silently getting part of it.
  732. ## Server-Minted Attachment URLs
  733. `get-download-url` returns Microsoft's own pre-authenticated `@microsoft.graph.downloadUrl`
  734. for OneDrive and SharePoint items. Graph publishes no such URL for **mail and calendar
  735. attachments, meeting recordings, or any other `/$value` byte endpoint** — for those, the
  736. byte tools such as `download-bytes` return base64 into the agent's context unless blob
  737. output is enabled. A synthetic 75,000-byte file becomes 100,000 base64 characters before
  738. JSON overhead; this is character arithmetic, not a tokenizer-specific measurement.
  739. `download-bytes-to-file` can instead save bytes locally in stdio mode or HTTP with
  740. `--http-local-file-tools`.
  741. `--enable-attachment-urls` (HTTP mode, off by default) closes that gap. When Graph has no
  742. URL of its own, `get-download-url` mints one this server serves. With it on,
  743. `get-download-url` is registered under every `--preset` (except the send-only `teams-write`),
  744. so a `--preset mail` agent that lists an attachment can mint a URL for it. OneDrive and
  745. SharePoint files get a minted URL too, instead of Graph's own: that one is about 1,300
  746. characters, too long for an agent that has to type it into a command, such as `curl` in a
  747. sandbox that cannot see tool results. A minted URL only
  748. works if the preset's scopes cover the resource: a contacts, tasks or excel preset has no Mail
  749. scopes, so it cannot read a mail attachment. For a mail or calendar attachment addressed by
  750. its message or event id (such as `/me/messages/{id}/attachments/{id}/$value`),
  751. `get-download-url` asks Graph about the attachment first. When Graph rejects the ids, finds no
  752. such attachment or denies access, it returns Graph's error instead of a URL; otherwise the URL
  753. comes with the attachment's `name`, `size` and `contentType`, when Graph reports them.
  754. The minted URL looks like:
  755. ```
  756. GET /attachment?t=<ticket>&dgk=<key-id>&dgx=<expiry>&dgs=<signature>
  757. ```
  758. The ticket is 32 bytes of CSPRNG output, **single-use**, memory-only, and expires after
  759. `MS365_MCP_ATTACHMENT_URL_TTL_S` seconds. Redeeming it streams the Graph bytes as the
  760. identity that minted it; the fetcher sends no Authorization header and holds no Microsoft
  761. credential.
  762. **This grants no authority the calling agent did not already have.** Every target that can
  763. be minted is one `download-bytes` would fetch for the same caller on the same account. The
  764. ticket only moves those bytes out of the context window and into a direct transfer.
  765. When attachment URLs are enabled, prefer `get-download-url` for document reading and
  766. downloads; reserve byte tools for callers that explicitly need bytes. This is a preference,
  767. not enforcement: `--enable-attachment-urls` does not scrub arbitrary response bodies.
  768. Use existing `--enabled-tools` / `--enabled-tools-file` filtering to restrict the tool
  769. surface when a client requires text-only results, and select metadata fields on listings.
  770. ### Example: attachment metadata to an external reader
  771. In HTTP attachment-URL mode, these synthetic model-facing calls contain metadata and a
  772. URL handoff only:
  773. ```json
  774. {"tool":"list-mail-attachments","arguments":{"messageId":"example-message","select":"id,name,contentType,size,isInline"}}
  775. {"value":[{"id":"example-attachment","name":"example.pdf","contentType":"application/pdf","size":75000,"isInline":false}]}
  776. {"tool":"get-download-url","arguments":{"target":"/me/messages/example-message/attachments/example-attachment/$value"}}
  777. {"downloadUrl":"<fresh single-use URL>","name":"example.pdf","size":75000,"contentType":"application/pdf"}
  778. ```
  779. The client gives the returned URL to any external downloader or document-processing MCP
  780. server that can fetch it, using that server's advertised tool names and parameter schemas.
  781. MS365 requires no particular processor or conversion result format; the binary document
  782. never enters this trace. In discovery mode, obtain the
  783. schemas with `get-tool-schema` and invoke these names through `execute-tool`. Keep the
  784. same identity/account for listing and minting. HTTP bearer/OBO mode binds the caller's
  785. identity and does not accept account switching; where an `account` parameter is advertised,
  786. use the same account throughout.
  787. Mint a **fresh server URL for every fetch**, including a probe, conversion, continuation,
  788. or retry. Keep the target, account and document selection (such as selected pages) the
  789. same when continuing a read. Do not automatically fetch every continuation: retrieve more
  790. only when relevant. Microsoft's drive-provider URLs can have different lifecycle semantics.
  791. ### Uploading attachments the same way
  792. The same ticket store works in the other direction. `get-upload-url` mints a URL for
  793. attaching a file to a draft message or an event, so the bytes go straight from the caller
  794. to Graph instead of passing as base64 `contentBytes` through the agent context:
  795. ```
  796. PUT /attachment?t=<ticket>&dgk=<key-id>&dgx=<expiry>&dgs=<signature>
  797. Content-Length: <file size>
  798. <raw file bytes>
  799. ```
  800. `target` is the item's attachments collection (`/me/messages/{id}/attachments` for a draft,
  801. `/me/events/{id}/attachments` for an event); `name` and `contentType` are recorded on the
  802. attachment. Files under 3 MB are attached inline; larger ones, up to Graph's 150 MB, stream
  803. through an upload session in 3.75 MiB chunks, so the server never holds more than one chunk.
  804. `Content-Length` is required.
  805. `target` can also be a OneDrive or SharePoint folder (`/me/drive/root`,
  806. `/me/drive/items/{folder-id}`, `/drives/{drive-id}/items/{folder-id}`,
  807. `/sites/{site-id}/drive/items/{folder-id}`); the file is then created there as `name`,
  808. always through a Graph upload session, with the same 150 MB cap. `conflictBehavior` decides
  809. what happens when the name is taken: `fail` (the default, answered with 409), `replace` or
  810. `rename`. `contentType` and `contentId` do not apply to drive files.
  811. The ticket is single-use and burnt on first presentation
  812. whatever the outcome, and the upload is attached as the identity that minted it, exactly as
  813. downloads are fetched. An upload ticket presented to `GET` (or a download ticket to `PUT`)
  814. is refused with the same 404 as any other bad ticket.
  815. ### Attaching a local file in stdio mode
  816. In stdio mode the server and the files are on the same machine, so no URL is needed.
  817. `upload-attachment-from-file` takes the same `target` and an absolute `filePath`, reads the
  818. file from disk and attaches it, with the same 3 MB and 150 MB limits. It is the upload
  819. counterpart of `download-bytes-to-file`.
  820. The tool is off until you list the directories it may read from:
  821. ```
  822. MS365_MCP_UPLOAD_DIRS=/Users/me/Documents/invitations:/Users/me/Scans
  823. ```
  824. Entries are absolute paths, separated like `PATH` (`:` on macOS and Linux, `;` on Windows).
  825. A file outside them is refused, and symlinks are resolved first, so a link inside an allowed
  826. directory cannot point the read somewhere else. The variable is not read from `.env`.
  827. Over HTTP the tool is registered only with `--http-local-file-tools`, like
  828. `download-bytes-to-file`.
  829. ### Configuration
  830. ```
  831. MS365_MCP_ATTACHMENT_URL_BASE=http://m365-mcp:3000 # required
  832. MS365_MCP_ATTACHMENT_URL_KEY=... # optional (or _KEY_FILE=/path), see below
  833. MS365_MCP_ATTACHMENT_URL_KEY_ID=1 # optional, default 1; needs a key
  834. MS365_MCP_ATTACHMENT_URL_TTL_S=120 # optional, default 120, max 300
  835. ```
  836. `MS365_MCP_ATTACHMENT_URL_BASE` is deliberately **not** `MS365_MCP_PUBLIC_URL`: that one is
  837. browser-facing, for OAuth redirects, while this is fetched server-to-server and is
  838. commonly a container address. A missing or malformed setting fails at startup rather than
  839. per-request.
  840. The signing key is optional. Without one, minted URLs are just `/attachment?t=<ticket>` and
  841. any HTTP client can fetch them; the ticket alone authorises redemption. Set a key only if
  842. the fetcher verifies the `dgk`/`dgx`/`dgs` signature (see below) and will refuse an
  843. unsigned URL. Setting `_KEY_ID` without a key, or a `_KEY_FILE` that is
  844. empty or unreadable, fails at startup.
  845. ### Splitting the attachment listener
  846. By default `/attachment` is served by the same Express app, on the same port, as `/mcp`.
  847. That is fine when callers are authenticated by a bearer token, and it is a problem when
  848. they are not. Under `--trust-proxy-auth` the MCP endpoint reads no `Authorization` header
  849. at all — **reachability is the authentication** — so one shared port means the sidecar you
  850. allowed through in order to fetch a PDF can also call every tool on the server.
  851. `--attachment-port <port>` (or `MS365_MCP_ATTACHMENT_PORT`) moves the route onto a listener
  852. of its own, and `--attachment-host <host>` (or `MS365_MCP_ATTACHMENT_HOST`) says which
  853. interface that listener binds:
  854. ```
  855. ms-365-mcp-server --http 10.89.0.2:3000 --trust-proxy-auth \
  856. --enable-attachment-urls \
  857. --attachment-port 3001 --attachment-host 10.89.1.2
  858. MS365_MCP_ATTACHMENT_URL_BASE=http://m365-mcp:3001 # note: the attachment port
  859. ```
  860. - `GET /attachment` on **3001** works; on 3000 it is **404** — the MCP app never mounts it.
  861. - `/mcp` on **3001** is **404**, as is everything else: the second app has the attachment
  862. route and nothing more. No OAuth router, no body parsers, no CORS, no health check.
  863. - The 60 req/min limiter that guards the route follows it onto the new listener.
  864. - `trust proxy` is **off** on the attachment listener (and `MS365_MCP_TRUST_PROXY_HOPS` is
  865. not read for it), unlike the MCP listener, which trusts one hop. This port is meant to be
  866. dialled directly on a container network; honouring `X-Forwarded-For` on the server's one
  867. uncredentialed surface would let a caller choose its own rate-limit bucket.
  868. The flag requires `--enable-attachment-urls` and refuses to start without it — on its own
  869. it would open a port with nothing on it while the operator believed the surfaces were
  870. separated. In stdio mode it warns and is ignored, like the flag it depends on.
  871. `--attachment-host` likewise requires `--attachment-port`: alone it would name an interface
  872. for a listener that does not exist.
  873. #### Two ports are not two surfaces unless they bind two interfaces
  874. **This is the part that decides whether any of the above is worth anything.** Read it
  875. before you deploy the split.
  876. `--attachment-port` on its own separates the two surfaces _inside the process_. It does not
  877. separate them _on the network_. Without `--attachment-host` the attachment listener inherits
  878. whatever host `--http` bound — and `--http 3000`, the common form, names no host at all, so
  879. Node binds the wildcard and **both** ports answer on **every** interface:
  880. ```
  881. ms-365-mcp-server --http 3000 --trust-proxy-auth \
  882. --enable-attachment-urls --attachment-port 3001 # NOT isolated
  883. ```
  884. Container networks grant a peer every port on a container, not one port. Put a
  885. document-conversion sidecar on a shared bridge so it can fetch `/attachment` on 3001, and
  886. that same sidecar can dial `:3000/mcp` — which under `--trust-proxy-auth` reads no
  887. `Authorization` header at all and hands back the full tool catalogue. Nothing fails, nothing
  888. is logged as an error, and the config looks exactly like the isolated one.
  889. To make it real, give the two listeners **different addresses**, and put only the attachment
  890. address on the network the fetcher is on:
  891. ```yaml
  892. # docker compose — the MCP port on the agent's own bridge, the attachment port on the
  893. # bridge shared with the converter. The converter can reach 3001 and cannot route to 3000.
  894. services:
  895. m365-mcp:
  896. networks: { agent-net: { ipv4_address: 10.89.0.2 }, convert-net: { ipv4_address: 10.89.1.2 } }
  897. command: >
  898. --http 10.89.0.2:3000 --trust-proxy-auth
  899. --enable-attachment-urls
  900. --attachment-port 3001 --attachment-host 10.89.1.2
  901. converter:
  902. networks: [convert-net]
  903. ```
  904. The MCP port is then unreachable from `convert-net` **by binding** — there is no socket
  905. listening on that interface — rather than by a firewall rule that has to keep matching.
  906. The server warns at startup if you run `--trust-proxy-auth` with `--attachment-port` while
  907. both listeners still answer on a common interface (either sharing an address, or either one
  908. on the wildcard). Both bound addresses are logged, read back from the socket rather than
  909. from the flags, so `Server listening on …` and `Attachment listener on …` can be compared
  910. directly.
  911. `--attachment-host` takes a bare IPv4 address, IPv6 address (bracketed `[::1]` or bare
  912. `::1`) or hostname. It is refused rather than coerced — `--attachment-host 10.0.0.5:3001`
  913. is an error naming `--attachment-port`, not a bind to something else. Note that
  914. with a signing key set, `MS365_MCP_ATTACHMENT_URL_BASE` must not be an IPv6 literal (the URL
  915. signature covers the host and the two implementations normalise IPv6 differently); if you
  916. bind the listener to an IPv6 address, name it in the base by hostname. Without a key there
  917. is no such restriction.
  918. Point `MS365_MCP_ATTACHMENT_URL_BASE` at the attachment port. The server cannot check this
  919. for you: the base is usually a container name on a network this process cannot resolve, so
  920. a wrong port here shows up as a fetch failure in the sidecar, not an error here. Both the
  921. base and the bound port are logged at startup, one line apart, for exactly that comparison.
  922. ### The signature, and who checks what
  923. This server never checks `dgk`/`dgx`/`dgs` on redemption, and that is deliberate.
  924. They exist for the fetcher: a document-conversion sidecar that refuses to dial a private
  925. address unless the URL carries a valid HMAC from an origin it has been configured to trust.
  926. What authorises redemption _here_ is the ticket. Verifying the signature on the way back in
  927. would prove only that we minted the URL — which the ticket already proves — while coupling
  928. redemption to the sidecar's clock and to the key surviving a restart.
  929. The wire format is a `v1` canonical-string HMAC over the minted URL, implemented in
  930. `src/lib/url-signing.ts`. The canonical string is `\n`-joined: `v1`, lowercased scheme,
  931. lowercased host, the port always explicit, the path, the remaining query with `dgk`/`dgx`/`dgs`
  932. removed and the rest sorted and re-encoded, and the expiry. The test vectors in
  933. `test/attachment-url-signing.test.ts` pin the format byte for byte — including the three
  934. places where the obvious JavaScript encoding is wrong (`!*'()` escaping, `+` decoding as a
  935. space, and code-point vs UTF-16 sort order) — so the check exists rather than being assumed.
  936. The ticket travels in the **query, not the path**, because the verifying sidecar keeps a
  937. fetched URL's path in its error messages and strips the query.
  938. ### Whose identity the bytes are read as
  939. Under `--trust-proxy-auth` the server reads with its own cached account, and redemption
  940. looks that account up again.
  941. In plain `--http` and `--obo`, identity arrives per request on the caller's
  942. `Authorization` header, and a ticket is redeemed later by a fetcher that sends none. So
  943. the ticket keeps the Graph token the minting request used (the exchanged one, under
  944. `--obo`) and redemption reads with that token and nothing else. It stays in server memory
  945. and is never part of the URL.
  946. With `MS365_MCP_OAUTH_TOKEN` set, the ticket keeps that token instead, `--trust-proxy-auth`
  947. or not.
  948. A token kept this way cannot be refreshed. If it expires before the URL is fetched,
  949. redemption answers 502. The agent can mint again once its client has a fresh token; an
  950. expired `MS365_MCP_OAUTH_TOKEN` has to be replaced by the operator.
  951. Tickets live in the memory of the process that minted them, so a URL has to be redeemed
  952. on the same instance. Behind a load balancer that means one replica or sticky routing.
  953. ## Token Storage
  954. Authentication tokens are stored in an encrypted file (AES-256-GCM). Only the 32-byte encryption key goes to the OS credential store via keytar.
  955. The cache itself is too big for some credential stores to hold - a Windows Credential Manager blob caps out at 2560 bytes and a real token cache is several times that, so on Windows the write could never succeed. A key is 32 bytes regardless of how many accounts are signed in, so this works the same way on every platform.
  956. **Default paths** are in the per-user config directory:
  957. | Platform | Location |
  958. | -------- | ------------------------------------------------------------------------- |
  959. | Windows | `%APPDATA%\ms-365-mcp-server\` |
  960. | macOS | `~/Library/Application Support/ms-365-mcp-server/` |
  961. | Linux | `$XDG_CONFIG_HOME/ms-365-mcp-server/` (or `~/.config/ms-365-mcp-server/`) |
  962. Earlier versions defaulted to a path inside the installed package, which under `npx` resolves to a content-hashed cache directory that `npm cache clean` or a version bump throws away. A cache still sitting in the package directory is moved to the new location on first run.
  963. That covers global and local installs, and `npx` when the hash has not changed. It cannot reach a cache left behind in a _previous_ `npx` hash directory, so upgrading an `npx` install one last time means signing in again. Adopting a cache from another directory would mean trusting a directory this package cannot prove it wrote, which is not worth one saved sign-in.
  964. Override the paths if you need to:
  965. ```bash
  966. export MS365_MCP_TOKEN_CACHE_PATH="$HOME/.config/ms365-mcp/.token-cache.json"
  967. export MS365_MCP_SELECTED_ACCOUNT_PATH="$HOME/.config/ms365-mcp/.selected-account.json"
  968. ```
  969. Parent directories are created automatically. Files are written with `0600` permissions.
  970. **Without a credential store** (headless Linux, most containers) the key is written to `.cache-key` next to the cache file, with `0600` permissions. That stops the tokens showing up in a stray `cat`, a backup or an accidental commit. It does not protect against anyone who can already read the directory - the key is right there. Use `MS365_MCP_AUTH_CACHE_COMMAND` below if you need the cache in a real secret store.
  971. **Skipping the credential store on purpose:**
  972. ```bash
  973. export MS365_MCP_USE_KEYTAR=0 # also accepts false, no or off
  974. ```
  975. The key then goes to `.cache-key` on every platform, exactly as it does where no credential store exists, and nothing in the server calls keytar. Useful when the credential store prompts on each start - macOS re-asks whenever the calling binary changes, which under `npx` is every version bump - or when the native module misbehaves on your platform rather than simply failing to load. Any other value leaves the credential store in use, and an unrecognised one is warned about rather than passed over silently.
  976. Switching it off strands a cache that was encrypted under a key already in the credential store, since nothing can reach that key any more. The server says so and replaces that cache on the next sign-in, which signs out **every** account it held, not just the one you sign back in as. Unset the variable first if that cache is worth keeping.
  977. Only a cache that nothing on the machine can open is replaced. One that fails to decrypt while a usable key is sitting right there - a truncated file, a downgrade to an older build, a cache from somewhere else - is damage rather than a stranded cache, and is left alone exactly as it is by default.
  978. Two things it deliberately does not do. It never deletes what this server already put in the credential store, on logout or otherwise, because reaching the store is the thing you just asked it to stop doing - clear the `ms-365-mcp-server` entries by hand if you want them gone. And a `.cache-key` that exists but cannot be read (wrong owner on a bind-mounted config directory, say) is treated as recoverable rather than missing: the server refuses both to overwrite a cache and to mint a replacement key, and says so, rather than deleting a key that would work again once the permissions are fixed. Fix the permissions, or delete `.cache-key` yourself to start over - which does mean signing in again.
  979. If the cache cannot be decrypted - key lost, keychain locked, file modified - you are asked to sign in again rather than the server failing to start. The cache file is left exactly as it was: not deleted, and not overwritten by that new sign-in either. A keychain that is merely locked usually reads fine on the next start, and the cache is still there when it does.
  980. The cost is that the new session is not saved while this lasts, so each start asks you to sign in again. If the key is genuinely gone and the cache will never open, delete `.token-cache.json` to start over - the log says so, and names the path.
  981. > **Hosted/sandboxed environments** (e.g. Anthropic Cowork): Set `MS365_MCP_TOKEN_CACHE_PATH` and `MS365_MCP_SELECTED_ACCOUNT_PATH` to a persistent mount so tokens survive between sessions.
  982. ### External auth-cache command
  983. Headless local-MSAL deployments can replace the built-in keytar/file storage with a provider-neutral external command:
  984. ```bash
  985. export MS365_MCP_AUTH_CACHE_COMMAND="/path/to/ms365-auth-cache-store"
  986. export MS365_MCP_AUTH_CACHE_COMMAND_TIMEOUT_MS=10000
  987. ```
  988. When `MS365_MCP_AUTH_CACHE_COMMAND` is set for a local auth flow, the server uses only that command for the MSAL token cache and selected-account metadata. It does not fall back to keytar or local files. If the command path is missing, not executable on POSIX, exits non-zero, times out, or returns malformed data, auth-cache operations fail closed with a sanitized error message.
  989. The value must be a real executable wrapper path. It is not a shell command string, and there is no companion args environment variable. Put any interpreter, region, profile, or provider-specific settings inside the wrapper. Windows users should point the variable at a wrapper executable or script that can be launched directly by Node without shell parsing.
  990. The server invokes the wrapper with:
  991. ```text
  992. $MS365_MCP_AUTH_CACHE_COMMAND load token-cache
  993. $MS365_MCP_AUTH_CACHE_COMMAND save token-cache
  994. $MS365_MCP_AUTH_CACHE_COMMAND delete token-cache
  995. $MS365_MCP_AUTH_CACHE_COMMAND load selected-account
  996. $MS365_MCP_AUTH_CACHE_COMMAND save selected-account
  997. $MS365_MCP_AUTH_CACHE_COMMAND delete selected-account
  998. ```
  999. Protocol v1:
  1000. - `load <key>` reads no stdin. Exit `0` with `{"found":true,"value":"<stored envelope string>"}` when present. A miss is exit `0` with `{"found":false}` or empty stdout.
  1001. - `save <key>` receives `{"value":"<stamped envelope string>"}` on stdin and must exit `0` only after the value is durably committed. There are no fire-and-forget or coalesced saves in v1.
  1002. - `delete <key>` reads no stdin and exits `0` whether the key existed or not.
  1003. - `<key>` is `token-cache` or `selected-account`.
  1004. - Any non-zero exit is a storage error. Do not use exit code `2` for cache misses.
  1005. - Stderr is captured and truncated in sanitized errors. Stdin and stdout payloads are never logged by the server.
  1006. - Token-cache payloads can be large; wrappers should handle at least 256 KB values.
  1007. Normal stateless HTTP Graph requests do not use local auth-cache storage. In HTTP mode, command storage is skipped at startup and per request unless local auth tools are explicitly enabled or a local account command such as `--login`, `--verify-login`, `--list-accounts`, `--select-account`, or `--logout` is used.
  1008. ## Azure Key Vault Integration
  1009. For production deployments, you can store secrets in Azure Key Vault instead of environment variables. This is particularly useful for Azure Container Apps with managed identity.
  1010. ### Setup
  1011. 1. **Create a Key Vault** (if you don't have one):
  1012. ```bash
  1013. az keyvault create --name your-keyvault-name --resource-group your-rg --location eastus
  1014. ```
  1015. 2. **Add secrets to Key Vault**:
  1016. ```bash
  1017. az keyvault secret set --vault-name your-keyvault-name --name ms365-mcp-client-id --value "your-client-id"
  1018. az keyvault secret set --vault-name your-keyvault-name --name ms365-mcp-tenant-id --value "your-tenant-id"
  1019. # Optional: if using confidential client flow
  1020. az keyvault secret set --vault-name your-keyvault-name --name ms365-mcp-client-secret --value "your-secret"
  1021. ```
  1022. 3. **Grant access to Key Vault**:
  1023. For Azure Container Apps with managed identity:
  1024. ```bash
  1025. # Get the managed identity principal ID
  1026. PRINCIPAL_ID=$(az containerapp show --name your-app --resource-group your-rg --query identity.principalId -o tsv)
  1027. # Grant access to Key Vault secrets
  1028. az keyvault set-policy --name your-keyvault-name --object-id $PRINCIPAL_ID --secret-permissions get list
  1029. ```
  1030. For local development with Azure CLI:
  1031. ```bash
  1032. # Your Azure CLI identity already has access if you have appropriate RBAC roles
  1033. az login
  1034. ```
  1035. 4. **Configure the server**:
  1036. ```bash
  1037. MS365_MCP_KEYVAULT_URL=https://your-keyvault-name.vault.azure.net npx @softeria/ms-365-mcp-server
  1038. ```
  1039. ### Secret Name Mapping
  1040. | Key Vault Secret Name | Environment Variable | Required |
  1041. | ----------------------- | ----------------------- | ------------------------- |
  1042. | ms365-mcp-client-id | MS365_MCP_CLIENT_ID | Yes |
  1043. | ms365-mcp-tenant-id | MS365_MCP_TENANT_ID | No (defaults to 'common') |
  1044. | ms365-mcp-client-secret | MS365_MCP_CLIENT_SECRET | No |
  1045. ### Authentication
  1046. The Key Vault integration uses `DefaultAzureCredential` from the Azure Identity SDK, which automatically tries multiple authentication methods in order:
  1047. 1. Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
  1048. 2. Managed Identity (recommended for Azure Container Apps)
  1049. 3. Azure CLI credentials (for local development)
  1050. 4. Visual Studio Code credentials
  1051. 5. Azure PowerShell credentials
  1052. ### Optional Dependencies
  1053. The Azure Key Vault packages (`@azure/identity` and `@azure/keyvault-secrets`) are optional dependencies. They are only loaded when `MS365_MCP_KEYVAULT_URL` is configured. If you don't use Key Vault, these packages are not required.
  1054. ## Message Signoff
  1055. Outgoing messages can be wrapped in a configurable signoff (e.g. a `🤖` prefix) so recipients can tell agent-sent messages from ones you typed yourself. Off by default — enable it with `--message-signoff-prefix` / `--message-signoff-suffix` (env: `MS365_MCP_MESSAGE_SIGNOFF_PREFIX` / `MS365_MCP_MESSAGE_SIGNOFF_SUFFIX`); `--no-message-signoff` or an empty env value turns it back off.
  1056. Once configured, it applies to all Teams messages (sends, replies and edits, including via `graph-batch`), to direct mail sends (`send-mail`, reply/forward, their shared-mailbox variants, and group thread replies), and to mail drafts as their content is written — `send-draft-message` sends a draft as-is, so a draft you wrote yourself goes out untouched. A message that already carries the marker is not signed twice, and a send whose body cannot take the signoff is refused rather than sent unsigned.
  1057. Markers may contain markup (e.g. a coloured `<span>`) as long as it renders visible text. Note that the signoff is a guardrail against an agent misusing the tools it was given, not a hard security boundary — an agent with shell access on the same machine could simply restart the server without it.
  1058. ## Production Deployment
  1059. See [docs/deployment.md](docs/deployment.md) for a full guide to hosting the server for organization-wide access, including Docker, Azure Container Apps, Azure App Service, Azure AD app registration, reverse proxy setup, client configuration, and exposed endpoints.
  1060. ## Contributing
  1061. We welcome contributions! Before submitting a pull request, please ensure your changes meet our quality standards.
  1062. Run the verification script to check all code quality requirements:
  1063. ```bash
  1064. npm run verify
  1065. ```
  1066. ### For Developers
  1067. After cloning the repository, you may need to generate the client code from the Microsoft Graph OpenAPI specification:
  1068. ```bash
  1069. npm run generate
  1070. ```
  1071. ## Related Projects
  1072. - [ms-365-admin-mcp-server](https://github.com/okapi-ca/ms-365-admin-mcp-server) by [@okapi-ca](https://github.com/okapi-ca): companion server for admin/daemon scenarios using application permissions (client credentials flow), covering security alerts, audit logs, service health, and usage reports.
  1073. ## Support
  1074. If you're having problems or need help:
  1075. - Create an [issue](https://github.com/softeria/ms-365-mcp-server/issues)
  1076. - Start a [discussion](https://github.com/softeria/ms-365-mcp-server/discussions)
  1077. - Email: eirikb@eirikb.no
  1078. - Discord: https://discord.gg/WvGVNScrAZ or @eirikb
  1079. Want to talk about rolling it out in your organization? Connect with me on
  1080. [LinkedIn](https://www.linkedin.com/in/eirik-brandtz%C3%A6g-22253a286/).
  1081. ## License
  1082. MIT © 2026 Softeria

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.