ms-graph-mcp

A Model Context Protocol server that gives an AI assistant access to your own Microsoft 365 data — Outlook mail and calendar, OneDrive, SharePoint, To Do, Planner, Teams chat, Entra ID and Intune — through the Microsoft Graph API. It runs locally over stdio, signs in as you with delegated permissions, and stores its token cache encrypted on your machine. (Why an MCP server)

Published on npm as @devyhan/ms-graph-mcp.

Not affiliated with Microsoft. This is an independent community project. Microsoft, Microsoft 365, Microsoft Graph, Outlook, OneDrive, SharePoint, Teams, Entra and Intune are trademarks of the Microsoft group of companies, used here only to describe what this software connects to.

Features

• 111 tools across 14 groups — mail, calendar, files, chat, teams, tasks, contacts, search, directory and device inventory, each enabled independently
• Delegated sign-in only — acts as you, with your permissions; the token never leaves the server process or enters the conversation
• Incremental consent — a bare login asks for the minimal set, and each tool call authenticates with just the scopes it needs
• Model-shaped responses — Graph results are projected down to sender, timestamp and plain text with paging cursors, not raw markup
• Document parsing — .docx, .xlsx, .pptx and .pdf extracted as unit rows from OneDrive, SharePoint, Teams or mail attachments
• Guardrails — host-pinned generic requests, --read-only mode, opt-in generic writes, retry with Retry-After
• Discovery mode — --discovery collapses the catalogue to discover_tools + call_tool so clients pay for schemas only on use

Install with one prompt

Paste this to your AI assistant, replacing the two IDs with your Entra app registration’s values:

https://github.com/devyhan/ms-graph-mcp

Install the MCP above.
• CLIENT_ID: 
• TENANT_ID: 

Find both IDs in the Microsoft Entra admin center under App registrations → your app → Overview: Application (client) ID and Directory (tenant) ID. The app must allow public client flows with an http://localhost redirect URI (under Authentication → Mobile and desktop applications), and an administrator must grant consent for the Graph permissions it requests.

Quick start

You need Node.js 20 or later. Sign in once, in a terminal:

npx @devyhan/ms-graph-mcp login

The server is meant to sign in through a shared multi-tenant Entra application published by this project — except that the shared registration is not published yet (SHIPPED_CLIENT_ID in src/config.ts is still empty), so until it ships, register an application of your own and name it on each command:

npx @devyhan/ms-graph-mcp login --client-id 

Register your own Entra application has the steps.

Your system browser opens on the Microsoft sign-in page; approve the permissions it asks for and the terminal finishes on its own. On a machine with no browser to open (SSH, container, headless server), use login --auth-flow device and sign in from another device. Then check it worked:

npx @devyhan/ms-graph-mcp status

status prints the application in use and where it came from, the resolved account, and the scopes this configuration may request. How the flows, consent, and AADSTS errors work is in Authentication and consent.

Configuration

The fastest path is the Claude Code plugin — no config file to edit:

/plugin marketplace add devyhan/ms-graph-mcp
/plugin install ms-graph-mcp@devyhan

For other clients, add an MCP server entry (here with the work preset):

{
  "mcpServers": {
    "microsoft-graph": {
      "command": "npx",
      "args": ["-y", "@devyhan/ms-graph-mcp", "--preset", "work"]
    }
  }
}

Every setting is also an MS365_MCP_* environment variable or a command-line flag. See Configuration for the plugin settings, per-client files, and every command and flag.

Tools

111 tools across 14 groups. --read-only removes every write tool, leaving 80. Enable only the groups you need.

* Needs --org-mode: these groups request scopes only a tenant administrator can consent to.

The full reference — scopes, admin-consent flags, and every tool with its arguments — is in Tools. Under --discovery the client sees six tools instead: discover_tools and call_tool plus the session, sign-in and permission probes.

Usage examples

“Summarize the reply chain about the Q3 invoice.”

Search first, then read the whole thread in one call instead of looping mail_get_message:

{ "query": "Q3 invoice", "after": "2026-09-01" }

{ "fromMessageId": "" }

“Find a 30-minute slot with Ana and Ben next week.”

{
  "attendees": ["[email protected]", "[email protected]"],
  "durationMinutes": 30,
  "start": "2026-10-19T09:00:00",
  "end": "2026-10-23T18:00:00",
  "timeZone": "UTC"
}

More per-group examples — files, chat, search, Planner, SharePoint, Teams, directory, Intune, and the generic escape hatch — are in Usage examples.

Instructions for AI agents

If you are an AI assistant working with this server, follow Instructions for AI agents: call session_status once first, sign in with auth_begin_login plus auth_login_status when needed, orient via discover_tools, and read the Hint and Blocked-by lines on errors.

Troubleshooting

Something failing? Start with Troubleshooting — the common failures and their fixes — then Authentication and consent for AADSTS error codes.

Security

• Delegated permissions only. The server acts as you, holds no client secret, and the token never enters the conversation.
• Host pinning. graph_request paths and every @odata.nextLink are checked against the Graph hostname before the request goes out.
• Read-only mode. --read-only removes write tools from the catalogue; generic writes need --allow-generic-write on top.
• Encrypted token cache. The refresh token lives AES-256-GCM-encrypted in your config directory (--cache-dir overrides).

Details: Security. To report a vulnerability privately, see SECURITY.md.

What this is not

This is a local, delegated-permission MCP server. It acts as you, with the permissions you have, over a stdio transport on your own machine. It is not a replacement for Microsoft’s own Agent 365 MCP servers, which are remote, run inside Microsoft’s tenant boundary, use application permissions and admin-managed agent identities, and require a Microsoft 365 Copilot licence. If you need agent identity, tenant-wide governance, or auditing that a tenant administrator controls, that is the product to look at.

It is also not a general Microsoft Graph client library. The tools cover the common read and write paths for each product area and project their results down to what a model can usefully read; graph_request exists for everything else, deliberately behind a flag.

Development

Requires Node.js 20 or later.

git clone https://github.com/devyhan/ms-graph-mcp.git
cd ms-graph-mcp
npm install
npm test

The test suite needs no Microsoft account, no tenant and no network — every HTTP call is stubbed. npm run contract is separate on purpose and runs weekly in CI instead. See CONTRIBUTING.md for the code layout, the rules for adding a tool, and how to report a bug. Changes are tracked in CHANGELOG.md.

Licence

MIT — see LICENSE.