Softeria/ms-365-mcp-server

📦 What is ms‑365‑mcp‑server?

A Node‑JS server that exposes Microsoft 365 (Graph) functionality as Model‑Context‑Protocol (MCP) tools. Each tool maps one Graph API endpoint (e.g. list‑mail‑messages, get‑drive‑item) and can be called by LLM‑powered assistants such as Claude Desktop, Claude Code CLI, or any other MCP‑compatible front‑end.

---

🎯 Core purpose

• Turn the massive Microsoft 365 Graph surface into a stable, declarative tool set that LLMs can invoke without writing custom HTTP code.
• Provide two output encodings – regular JSON (default) and the experimental TOON format, which reduces token count by 30‑60 % for list‑style data.
• Support personal and organization (work/school) accounts, multiple clouds (global & China), and multi‑account usage from a single server instance.

---

⚙️ Main features (as described in the README)

Feature	What it gives you
Authentication	MSAL‑based device‑code flow (default), OAuth 2.1 when run in --http mode, or bring‑your‑own‑token via MS365_MCP_OAUTH_TOKEN.
Tool surface	300 + auto‑generated tools covering the full Graph API (mail, calendar, OneDrive, Teams, SharePoint, Planner, etc.).
Presets & filtering	--preset, --enabled-tools regex, or --allowed‑scopes let you shrink the tool set to only what you need, reducing token usage and required permissions.
Read‑only mode	Safe‑guard against accidental writes (--read-only).
Dynamic permission discovery	--list-permissions shows the exact Graph scopes the current configuration will request, helping admins pre‑approve consent.
Output formats	JSON (pretty‑printed) or experimental TOON (Token‑Oriented Object Notation) for cheaper LLM calls.
Multi‑account support	Log in several Microsoft accounts; each tool call can specify an account argument (email or MSAL homeAccountId).
Enterprise controls	--allowed‑scopes narrows token requests; --extra‑scopes adds custom scopes; SharePoint can be limited to Sites.Selected.
Deployable via CLI or Docker	Run with npx @softeria/ms-365-mcp-server … or containerise; HTTP mode works behind reverse proxies with --public‑url.

---

🛠️ Typical workflow

1. Install – npm i -g @softeria/ms-365-mcp-server (or run via npx).
2. Authenticate – npx @softeria/ms-365-mcp-server --login (device code) or start in --http mode for OAuth.
3. Configure – add the server to your LLM client (Claude Desktop, Claude Code CLI, Open WebUI, etc.) using the JSON snippets in the README.
4. Select mode – default is personal; add --org-mode to unlock Teams, SharePoint, shared mailboxes, etc.
5. Call tools – LLM sends a request like { "tool": "list-mail-messages", "arguments": { "account": "work@company.com" } }; the server talks to Graph and returns JSON or TOON.

---

📦 Installation & quick start

# Run directly (no global install needed)
npx @softeria/ms-365-mcp-server --login   # device‑code flow
# Test a tool
npx @softeria/ms-365-mcp-server --tool list-mail-messages

For Docker:

docker run -p 3000:3000 ghcr.io/softeria/ms-365-mcp-server:latest --http

Then point your MCP‑compatible client to http://localhost:3000/mcp.

---

🔗 Integration points mentioned

• Claude Desktop – add under Settings → Developer.
• Claude Code CLI – claude mcp add ms365 -- npx -y @softeria/ms-365-mcp-server ….
• Open WebUI – HTTP mode, OAuth 2.1, register client in the UI.
• Custom clients – any tool that can speak MCP (JSON over stdio or HTTP).

---

📚 When would you use it?

• Building an AI assistant that needs to read/write a user’s Outlook mail, calendar, or OneDrive files.
• Enterprise bots that must interact with Teams chats, SharePoint lists, or Planner tasks while respecting strict permission boundaries.
• Any LLM‑driven workflow where token efficiency matters – switch to TOON to cut cost on large list responses.
• Multi‑tenant SaaS where a single server instance manages many users’ Microsoft accounts.

---

⚠️ Limitations / notes from the README

• TOON is marked experimental – may change.
• In HTTP mode, authentication tools are disabled by default; enable with --enable-auth-tools if needed.
• The default Softeria Azure app has a limited permission set; to request additional scopes you must supply your own Azure AD app (MS365_MCP_CLIENT_ID etc.).
• --allowed‑scopes can only narrow permissions; to broaden you need --extra‑scopes.
• Pinning (MS365_MCP_EXPECTED_USERNAME / --expected-home-account-id) is optional but useful for headless deployments.

---

📖 Where to learn more

• Source code – src/endpoints.json lists every generated tool.
• Deployment guide – docs/deployment.md (referenced for reverse‑proxy setup).
• TOON format – see the linked GitHub repo github.com/toon-format/toon.

---

TL;DR

ms-365-mcp-server is a ready‑made bridge that turns Microsoft 365 Graph APIs into a large, permission‑aware toolbox that LLMs can call via the Model‑Context‑Protocol. It handles authentication, permission scoping, multi‑account management, and even offers a token‑saving output format, making it a practical component for building AI assistants that need real‑world Microsoft 365 data.