Microsoft 365 MCP 服务

Prerequisites

• Node.js >= 20 (recommended)
• Node.js 14+ may work with dependency warnings

Organization Account Tools (Requires --org-mode flag)

Teams & Chats, Online Meetings, Transcripts & Recordings, Attendance Reports, SharePoint Sites & Lists, Shared Mailboxes & Calendars, User Management, Presence, Virtual Events

Custom Teams emojis are available in organization mode through list-custom-emojis and create-custom-emoji (teams and work presets). These use the Microsoft Graph beta API and request the delegated permissions TeamworkCustomEmoji.Read and TeamworkCustomEmoji.Create, respectively. Read-only mode exposes only the list tool. Existing deployments may need consent for these new scopes and reauthentication; adding tool support does not upgrade an already-issued token.

Listing can return contentBytes: null by default. To request base64 PNG/GIF images, pass select: "displayName,contentBytes" or select: ["displayName", "contentBytes"]. Use a small top to keep image responses manageable. To create an emoji, pass body: { displayName, contentBytes } with the exact approved name and base64 PNG/GIF file bytes. See Microsoft's list and create contracts. These tools do not post messages or reactions.

Required Graph API Permissions

Permissions are requested dynamically based on which tools are enabled. Use --list-permissions to see the exact permissions for your configuration:

```bash

Teams only (requires --org-mode)

npx @softeria/ms-365-mcp-server --org-mode --preset teams

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):

docker compose — the MCP port on the agent's own bridge, the attachment port on the

Quick Start Example

Test login in Claude Desktop:

Examples

CLI Options

The following options can be used when running ms-365-mcp-server directly from the command line:

--login           Login using device code flow
--logout          Log out and clear saved credentials
--verify-login    Verify login without starting the server
--list-permissions List required Graph API permissions and exit (respects --org-mode, --preset, --enabled-tools, --allowed-scopes)
--org-mode        Enable organization/work mode from start (includes Teams, SharePoint, etc.)
--work-mode       Alias for --org-mode
--force-work-scopes Backwards compatibility alias for --org-mode (deprecated)
--cloud <type>    Microsoft cloud environment: global (default) or china (21Vianet)
--allowed-scopes <scopes> Limit exposed tools to Graph scopes covered by this allowlist
--extra-scopes <scopes> Append additional Graph scopes to the token request (for use with your own app registration + graph-batch)
--expected-username <username> Require local MSAL auth to use this account username
--expected-home-account-id <id> Require local MSAL auth to use this exact homeAccountId

Server Options

When running as an MCP server, the following options can be used:

-v                Enable verbose logging
--read-only       Start server in read-only mode, disabling write operations
--http [port]     Use Streamable HTTP transport instead of stdio (optionally specify port, default: 3000)
                  Starts Express.js server with MCP endpoint at /mcp. Bound to a loopback host
                  (e.g. --http 127.0.0.1:3000 or --http [::1]:3000) with no --public-url, it
                  rejects requests whose Host or Origin is not localhost (not applied to the
                  --attachment-port listener)
--http-local-file-tools Register download-bytes-to-file over HTTP. Anyone who can reach the port
                  can write files as the server's user (without a valid token, only an empty
                  file that is removed again), so enable it only on a single-user machine.
                  With MS365_MCP_UPLOAD_DIRS set it also registers upload-attachment-from-file,
                  which reads files from those directories.
                  Refused unless --http binds a loopback host with no --public-url and no
                  --trust-proxy-auth
--enable-auth-tools Enable login/logout tools when using HTTP mode (disabled by default in HTTP mode)
--enable-attachment-urls Let get-download-url mint a server-served URL for byte resources Graph
                  exposes no pre-authenticated URL for (see "Server-Minted Attachment URLs").
                  Also adds get-download-url to any --preset that lacks it (except teams-write)
--attachment-port <port> Serve /attachment on its own listener on this port instead of on the
                  MCP app, so a fetcher that can read attachments cannot also reach /mcp
                  (requires --enable-attachment-urls; see "Splitting the attachment listener")
--attachment-host <host> Interface the --attachment-port listener binds. Defaults to whatever
                  --http bound, which with a wildcard --http leaves BOTH ports on every
                  interface and so isolates nothing — set this to make the split real
                  (requires --attachment-port; see "Splitting the attachment listener")
--no-dynamic-registration Disable OAuth Dynamic Client Registration (enabled by default in HTTP mode)
--enabled-tools <pattern> Filter tools using regex pattern (e.g., "excel|contact" to enable Excel and Contact tools)
--preset <names>  Use preset tool categories (comma-separated). See "Tool Presets" section above
--list-presets    List all available presets and exit
--toon            (experimental) Enable TOON output format for 30-60% token reduction
--blob-output     File download tools answer an MCP EmbeddedResource with the file instead of
                  base64 JSON in a text block (see MS365_MCP_BLOB_OUTPUT below)
--discovery       Dynamic tool discovery: loads tools on demand to reduce initial token usage (see "Dynamic Tool Discovery" above)
--public-url <url> Public base URL for OAuth when behind a reverse proxy (see Open WebUI section and docs/deployment.md)

Environment variables:

• READ_ONLY=true|1: Alternative to --read-only flag
• ENABLED_TOOLS: Filter tools using a regex pattern (alternative to --enabled-tools flag)
• MS365_MCP_ORG_MODE=true|1: Enable organization/work mode (alternative to --org-mode flag)
• MS365_MCP_FORCE_WORK_SCOPES=true|1: Backwards compatibility for MS365_MCP_ORG_MODE
• MS365_MCP_OUTPUT_FORMAT=toon: Enable TOON output format (alternative to --toon flag)
• 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
• 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.
• MS365_MCP_MAX_ITEMS=<n>: Maximum number of items accumulated when fetchAllPages: true (positive integer, default 10000). Pagination stops and the response is truncated once this many items are collected.
• 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).
• 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.
• 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.
• MS365_MCP_BODY_FORMAT=html: Return email bodies as HTML instead of plain text (default: text)
• 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
• 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)
• 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)
• 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)
• 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
• MS365_MCP_ATTACHMENT_PORT=<port>: Serve the attachment route on its own listener on this port (alternative to --attachment-port; requires --enable-attachment-urls)
• 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"
• 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)
• 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"
• MS365_MCP_CLOUD_TYPE=global|china: Microsoft cloud environment (alternative to --cloud flag)
• 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
• LOG_LEVEL: Set logging level (default: 'info')
• SILENT=true|1: Disable console output
• MS365_MCP_REDACT_PII=false|0: Disable scrubbing of JWTs, Bearer headers, OAuth token fields, and email addresses from log messages (default: enabled). The server handles live Graph bearer tokens, so redaction is on unless you opt out for fully verbose local debugging.
• MS365_MCP_CLIENT_ID: Custom Azure app client ID (defaults to built-in app)
• 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
• MS365_MCP_OAUTH_TOKEN: Pre-existing OAuth token for Microsoft Graph API (BYOT method)
• MS365_MCP_KEYVAULT_URL: Azure Key Vault URL for secrets management (see Azure Key Vault section)
• MS365_MCP_TOKEN_CACHE_PATH: Custom file path for MSAL token cache (see Token Storage below)
• MS365_MCP_SELECTED_ACCOUNT_PATH: Custom file path for selected account metadata (see Token Storage below)
• MS365_MCP_AUTH_CACHE_COMMAND: External executable wrapper for provider-neutral auth-cache storage (see Token Storage below)
• MS365_MCP_AUTH_CACHE_COMMAND_TIMEOUT_MS: Per-invocation timeout for MS365_MCP_AUTH_CACHE_COMMAND (default: 10000)
• MS365_MCP_EXPECTED_USERNAME: Require local MSAL auth to use this Microsoft account username (case-insensitive; CLI flag takes precedence)
• MS365_MCP_EXPECTED_HOME_ACCOUNT_ID: Require local MSAL auth to use this exact MSAL homeAccountId (CLI flag takes precedence)

Configuration

MS365_MCP_ATTACHMENT_URL_BASE=http://m365-mcp:3000   # required
MS365_MCP_ATTACHMENT_URL_KEY=...                     # optional (or _KEY_FILE=/path), see below
MS365_MCP_ATTACHMENT_URL_KEY_ID=1                    # optional, default 1; needs a key
MS365_MCP_ATTACHMENT_URL_TTL_S=120                   # optional, default 120, max 300

MS365_MCP_ATTACHMENT_URL_BASE is deliberately not MS365_MCP_PUBLIC_URL: that one is browser-facing, for OAuth redirects, while this is fetched server-to-server and is commonly a container address. A missing or malformed setting fails at startup rather than per-request.

The signing key is optional. Without one, minted URLs are just /attachment?t=<ticket> and any HTTP client can fetch them; the ticket alone authorises redemption. Set a key only if the fetcher verifies the dgk/dgx/dgs signature (see below), such as a docglean-mcp sidecar, which will refuse an unsigned URL. Setting _KEY_ID without a key, or a _KEY_FILE that is empty or unreadable, fails at startup.

Integration

Output Format: JSON vs TOON

The server supports two output formats that can be configured globally: