ms-graph-mcp

Purpose

ms-graph-mcp is a Model Context Protocol (MCP) server used to let AI agents access Microsoft Graph. It provides 85 tools, covering Outlook mail and calendar, meetings (including transcripts), Teams chats, files, SharePoint, search, people, contacts, directory, tasks, and OneNote, and can run over stdio or Streamable HTTP.

Main capabilities

• Tool coverage: mail, calendar, meetings (including transcripts), Teams chats, files, SharePoint, search, people, contacts, directory, tasks, OneNote.
• Authentication method: sign in with the user's own Microsoft account, browser SSO, no pasting tokens, no client secret.
• Lean dependencies: does not use msgraph-sdk and azure-identity, the Graph client is based on raw httpx2, the dependency tree is small and network behavior is inspectable.
• Read/write separation: write tools are hidden by default and calls are rejected, unless the caller explicitly opts in.
• Authentication-agnostic design: by default tools receive an already-acquired Graph token through the request context; the server can also perform its own on-behalf-of exchange, operating as a standard OAuth resource server.
• Toolset configuration: select named profiles via GRAPH_MCP_TOOLSETS, each profile is a set of namespaces, can be combined with commas; default is core, setting all exposes all tools.
• Tool naming: named by Graph permission family rather than Microsoft product, because real problems often cross product boundaries; for example files_ covers OneDrive and SharePoint document libraries, underlying is the same driveItem resource.
• Tool annotations: each tool declares MCP annotations (readOnlyHint, destructiveHint, idempotentHint), each description states the required delegated permissions.
• Tiers: internal tiers are not part of the agent surface, the model sees 76 tools. By namespace: mail 11, tasks 11, calendar 10, files 10, chat 8, directory 7, meetings 7, people 6, notes 5, search 1.
• Version notes: tools were renamed in 0.2.0, all pre-0.2.0 tool names remain available as aliases, and will continue until 0.4.0; aliases are valid in tools/call, but are not announced in tools/list.

Usage

Installation

Requires Python 3.12+. There are two paths:

A. Use the package: no clone needed, uv can run directly from PyPI, or install into an environment. Release candidate versions are also published, pip skips them by default unless --pre is used. HTTP transport has a GHCR container image, see docs/hosting.md. Listed in the official MCP registry as io.github.nitin27may/ms-graph-mcp. TestPyPI is not a distribution channel, it is only used for release rehearsals, may be purged and does not mirror PyPI, installing from it requires --extra-index-url https://pypi.org/simple/ to resolve ordinary dependencies; it is recommended to use PyPI or --pre.

B. Run from source: suitable for modifications, forks, or running unreleased changes. uv sync is the only setup step. Before opening a PR please read CONTRIBUTING.md, tool allowlists and tier separation have enforced invariants. To point an MCP client at a clone, its absolute path is needed, because clients do not inherit the working directory, and most do not expand ~.

Set up an Entra app

Requires an Entra ID app registration, about two minutes. Do not create a client secret: register as a public client, sign in via browser using PKCE. In the Entra portal → App registrations → New registration: any name, for example ms-graph-mcp; supported account types: accounts in this organizational directory only; redirect URI: select public client/native, value http://localhost；证书和密钥留空。然后在新应用上：身份验证 → Enable allow public client flows; API permissions → Add permission → Microsoft Graph → Delegated permissions, add the permissions you want the agent to access. A reasonable read-only starting set: User.Read, Mail.Read, Calendars.Read, Files.Read.All, People.Read, Chat.Read, Tasks.Read, Notes.Read, Contacts.Read. For the full copy-paste consent set and the permissions required by each tool, see docs/permissions.md. Copy the Application (client) ID and Directory (tenant) ID from the overview page; that is all that is needed.

Configure the MCP client

Every MCP client that supports stdio accepts the same three things: command, args, and environment block. The first login opens the browser for normal Microsoft 365 SSO, including MFA and Conditional Access. The result is cached in ~/.ms-graph-mcp/token_cache.json, readable only by the owner, so it will not prompt again.

• VS Code: reload the window, VS Code will prompt once for the two IDs and remember them; this file is safe to commit. Open the Chat view, switch to Agent mode, and the tools appear in the tool picker. Confirm with MCP: List Servers.
• Claude Code: confirm with /mcp, which lists the server and its tools.
• Claude Desktop: quit completely (not just close the window), reopen it, and look for the tools icon in the editor.
• Cursor and Windsurf: use the same mcpServers shape as Claude Desktop, in the file described in the table above.

The fastest way to check the server independently of any client: Node 22.19+ is required, open the browser UI, and you can list tools and call them manually. There is also a scriptable --cli mode, see docs/testing.md. Pass variables with -e, not from the shell; Inspector does not provide your environment to the server it spawns, so GRAPH_MCP_CLIENT_ID=… npx @modelcontextprotocol/inspector … will start the server with no client ID; -e The flag is placed after the server command.

When running from source, use the same block as above, replacing the command and arguments with the absolute path to the clone. Two common problems: uv must be on the client's PATH, and GUI apps launched from Finder or Dock do not inherit the shell's PATH; if this happens, put the output of which uv into "command" instead of the bare name; --directory is not optional, and without it, uv run resolves against whatever directory the client happens to launch in, not the project.

Configuration

Two settings are enough to run it; everything else has usable defaults. See docs/configuration.md for each setting, the two deployment forms, and the hosted/OBO options. See docs/hosting.md for running it as a service.

Toolset configuration file

85 tools is a lot for a model. GRAPH_MCP_TOOLSETS selects named profiles, each of which is a set of namespaces, and they can be combined with commas. core is the default, so unless requested, some tools will not be announced. If you need Teams chat, Planner, OneNote, meeting transcripts, or directory lookup, name those profiles, or set GRAPH_MCP_TOOLSETS=all to expose everything. Over HTTP, the caller can send X-Toolsets to further narrow an individual request, but only to narrow; the startup value is the ceiling, so a client request for all will not get anything the deployment has not enabled. This filters visibility, not permissions; the write scopes and internal tier gates are the mechanisms that actually block calls.

When it applies

• Giving AI agents access to Microsoft 365 data: mail, calendar, meeting transcripts, Teams chat, files, SharePoint, OneNote, tasks, directory, people, contacts.
• Agent integrations that need read/write separation and explicit permission control.
• MCP clients that need stdio or Streamable HTTP transport, such as VS Code, Claude Code, Claude Desktop, Cursor, Windsurf.
• Deployments that want minimal dependencies and inspectable network behavior.

Limitations

• Status: early. Extracted from a production agent platform, already running in real tenants, and the code is battle-tested, but the packaging and public API surface are newer, and the configuration surfacemay change before 1.0.
• SharePoint sites and lists are the biggest gap; directory completion, file move/delete, and mail drafts follow later.
• Sovereign clouds (GCC High / 21Vianet) are not currently supported. See docs/roadmap.md for the full list and intentionally excluded scope.
• Requires Python 3.12+.
• When running from source, uv must be on the client's PATH, and --directory is not optional.
• X-Toolsets over HTTP can only narrow, not expand, the scope enabled at startup.
• Internal tiers are not part of the agent surface; the model sees 76 tools.
• Tool names before 0.2.0 are available as aliases, but will not be announced in tools/list, and will continue until 0.4.0.
• Documentation: published as a searchable site https://nitinksingh.com/ms-graph-mcp/。
• Support: setup and app registration questions → Discussions; bugs → Issues, with the output from running the server in a terminal; security vulnerabilities → never a public issue, see SECURITY.md. Never paste access tokens, client secrets, or shared secrets anywhere.
• License: MIT, see LICENSE.