Softeria/ms-365-mcp-server

What it is

ms‑365‑mcp‑server is a Node‑JS server that implements the Model Context Protocol (MCP) for Microsoft 365. It talks to the Microsoft Graph API and exposes the Graph’s functionality as a set of “tools” that can be called by LLM‑powered assistants (Claude Desktop, Open WebUI, etc.). In practice you run the package with npx @softeria/ms-365-mcp-server and the server translates a simple JSON (or the experimental TOON) request into a Graph call, then returns the Graph response in the same lightweight format.

Who might use it

• LLM‑based assistants that need to read or act on a user’s Outlook mail, calendar, OneDrive files, Teams chats, SharePoint sites, etc.
• Enterprises that want to expose a controlled subset of Microsoft 365 capabilities to AI agents while limiting the OAuth scopes that are granted.
• Developers building custom agents or bots that need a stable, declarative interface to the Graph without writing the low‑level HTTP code themselves.

Core features (as described in the README)

Feature	What it does
Authentication	Uses Microsoft Authentication Library (MSAL) to obtain OAuth tokens. Scopes are derived automatically from the enabled tools, but can be narrowed with --allowed‑scopes or widened with --extra‑scopes.
Tool surface	Over 300 tools, each mapping 1‑to‑1 to a Graph endpoint. Tools are defined in src/endpoints.json. Personal‑account tools (mail, calendar, OneDrive, etc.) are on by default; organization‑mode tools (Teams, SharePoint, user management, etc.) are enabled with --org‑mode.
Presets & dynamic discovery	Presets (e.g., mail) and regex‑based --enabled‑tools let you shrink the tool set, reducing token usage and improving privacy.
Read‑only mode	Prevents any write‑operations, useful for safe sandboxed deployments.
Output formats	Default JSON; experimental TOON (Token‑Oriented Object Notation) reduces token count by 30‑60 % for uniform list data.
Scope filtering	--allowed‑scopes (or MS365_MCP_ALLOWED_SCOPES) acts as a whitelist; tools whose required Graph scopes are not covered are hidden.
User‑field filtering	--user‑fields limits which user profile properties are returned, providing an extra layer of data minimisation.
Proxy support	Set MS365_MCP_GRAPH_BASE_URL to route Graph traffic through a custom proxy.
Deployment options	Run locally via CLI, as an HTTP server (--http), in Docker, or behind a reverse proxy (--public‑url). Supports dynamic client registration for OAuth.
Integration examples	Detailed snippets for Claude Desktop, Claude Code CLI, and Open WebUI, showing how to add the MCP server as a tool source.

How it works (high‑level flow)

1. Start the server – npx @softeria/ms-365-mcp-server (optionally with flags like --org-mode, --http, --toon).
2. Authentication – MSAL opens a browser (or uses OBO) to obtain an access token for the scopes required by the enabled tools.
3. Tool request – An LLM client sends a request specifying a tool name and parameters (e.g., list-mail-messages).
4. Server translates – The server looks up the corresponding Graph endpoint in endpoints.json, builds the HTTP request, applies any $select/$filter rules (including user‑field limits), and forwards it to Microsoft Graph.
5. Response – Graph’s JSON is optionally projected/filtered, then returned to the client in JSON or TOON.

When you might not need it

• If you only need a few Graph calls, writing them directly with an SDK may be simpler.
• Projects that require full‑blown Graph SDK features (batching, delta queries, etc.) beyond the pre‑bundled tools.
• Environments where you cannot install Node 20 or run a separate MCP process.

Quick start checklist

1. Install Node 20+.
2. Run npx @softeria/ms-365-mcp-server (add --org-mode for work‑school features).
3. Follow the Claude Desktop or Open WebUI integration steps to point the assistant at http://localhost:3000/mcp (or the Docker‑exposed port).
4. Use --list-permissions to see which Graph scopes will be requested and adjust with --allowed-scopes if needed.
5. (Optional) Enable TOON with --toon for token‑efficient output.

---

All information above is taken directly from the repository’s README; no additional features have been inferred.