ms-graph-mcp

Releases · Changelog

A Model Context Protocol server for Microsoft Graph — 85 tools across mail, calendar, meetings (including transcripts), Teams chat, files, SharePoint, search, people, contacts, directory, tasks and OneNote, over stdio or Streamable HTTP.

Signs you in with your own Microsoft account — browser SSO, no token to paste, no client secret.

• No msgraph-sdk, no azure-identity — the Graph client is raw httpx2, so the dependency tree stays small and the wire behaviour is inspectable.
• Read/write separation is enforced, not advisory — write tools are hidden and refused unless the caller explicitly opts in.
• Auth-agnostic by default — tools receive an already-acquired Graph token via the request context. The server can also perform its own on-behalf-of exchange when you want it to act as a proper OAuth resource server.

Status: early. Extracted from a production agent platform where it has been running against a real tenant. The code is battle-tested; the packaging and public API surface are newer. Expect the config surface to move before 1.0.

Install

Requires Python 3.12+. Two paths — pick the one that matches what you want to do.

A. Use the package

Nothing to clone. uv runs it straight from PyPI:

uvx --from ms-graph-mcp ms-graph-mcp          # stdio, for an MCP client
uvx --from ms-graph-mcp ms-graph-mcp-http     # Streamable HTTP

or install it into an environment:

pip install ms-graph-mcp

Release candidates are published too. pip skips them unless you ask:

pip install --pre ms-graph-mcp          # newest, including candidates
pip install ms-graph-mcp==0.3.0rc1      # a specific one; no --pre needed for an exact pin

A container image is on GHCR for the HTTP transport — see docs/hosting.md.

Also listed on the official MCP registry as io.github.nitin27may/ms-graph-mcp.

TestPyPI is not a distribution channel. Every release is published there first, but that is a rehearsal of the publishing process: it can be wiped without notice and does not mirror PyPI, so installing from it needs --extra-index-url https://pypi.org/simple/ just to resolve ordinary dependencies. Use PyPI, or --pre.

B. Run from source

For hacking on it, forking it, or running an unreleased change:

git clone https://github.com/nitin27may/ms-graph-mcp
cd ms-graph-mcp
uv sync                       # creates .venv and installs everything
uv run ms-graph-mcp           # check it starts

uv sync is the only setup step. See CONTRIBUTING.md before opening a pull request — the tool allowlists and the tier separation have invariants that are enforced rather than advisory.

To point an MCP client at your clone, you need its absolute path — clients do not inherit your working directory and most do not expand ~:

cd ms-graph-mcp && pwd
# /Users/you/workspace/ms-graph-mcp

Then use the source form of the config in Configure your MCP client below.

Set up the Entra app

You need an Entra ID app registration — about two minutes. Do not create a client secret: this registers as a public client, which signs you in through your browser using PKCE. A secret on a program running on your own machine would be readable by anyone with the config file, which is why the flow is designed not to need one. Nothing goes into a config file except two ids, neither of which is sensitive.

In the Entra portal → App registrations → New registration:

• Name: anything, e.g. ms-graph-mcp
• Supported account types: Accounts in this organizational directory only
• Redirect URI: select Public client/native, value http://localhost

Leave Certificates & secrets alone — you do not need anything from it.

Then, on the new app:

• Authentication → enable Allow public client flows

• API permissions → Add a permission → Microsoft Graph → Delegated permissions, and add what you want the agent to reach. A sensible read-only starting set:

  code

  User.Read  Mail.Read  Calendars.Read  Files.Read.All
  People.Read  Chat.Read  Tasks.Read  Notes.Read  Contacts.Read
  

  The complete copy-paste consent sets — and which permission each individual tool needs — are in docs/permissions.md.

Copy the Application (client) ID and Directory (tenant) ID from the Overview page. That is everything you need.

Configure your MCP client

Every MCP client that speaks stdio takes the same three things — a command, its arguments, and an environment block:

{
  "command": "uvx",
  "args": ["--from", "ms-graph-mcp", "ms-graph-mcp"],
  "env": {
    "GRAPH_MCP_CLIENT_ID": "<application-client-id>",
    "GRAPH_MCP_TENANT_ID": "<directory-tenant-id>"
  }
}

Where that block goes, and what the surrounding key is called, differs:

The first sign-in opens your browser for normal Microsoft 365 SSO — including MFA and conditional access. The result is cached in ~/.ms-graph-mcp/token_cache.json, owner-readable only, so it does not prompt again.

VS Code

{
  "inputs": [
    { "id": "clientId", "type": "promptString", "description": "Entra application (client) ID" },
    { "id": "tenantId", "type": "promptString", "description": "Entra directory (tenant) ID" }
  ],
  "servers": {
    "ms-graph": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "ms-graph-mcp", "ms-graph-mcp"],
      "env": {
        "GRAPH_MCP_CLIENT_ID": "${input:clientId}",
        "GRAPH_MCP_TENANT_ID": "${input:tenantId}"
      }
    }
  }
}

Reload the window. VS Code prompts once for the two ids and remembers them, so this file is safe to commit. Open the Chat view, switch to Agent mode, and the tools appear under the tools picker — that is the panel in the screenshot above. Confirm with MCP: List Servers, which shows status and output if it does not connect.

Claude Code

claude mcp add ms-graph \
  --env GRAPH_MCP_CLIENT_ID=<application-client-id> \
  --env GRAPH_MCP_TENANT_ID=<directory-tenant-id> \
  -- uvx --from ms-graph-mcp ms-graph-mcp

Confirm with /mcp inside Claude Code — it lists the server and its tools.

Claude Desktop

{
  "mcpServers": {
    "ms-graph": {
      "command": "uvx",
      "args": ["--from", "ms-graph-mcp", "ms-graph-mcp"],
      "env": {
        "GRAPH_MCP_CLIENT_ID": "<application-client-id>",
        "GRAPH_MCP_TENANT_ID": "<directory-tenant-id>"
      }
    }
  }
}

Confirm by quitting Claude Desktop fully — not just closing the window — reopening it, and looking for the tools icon in the composer.

Cursor and Windsurf

Both use the same mcpServers shape as Claude Desktop, in the file named in the table above.

MCP Inspector

The quickest way to check the server independently of any client:

npx @modelcontextprotocol/inspector \
  uvx --from ms-graph-mcp ms-graph-mcp \
  -e GRAPH_MCP_CLIENT_ID=<application-client-id> \
  -e GRAPH_MCP_TENANT_ID=<directory-tenant-id>

Needs Node 22.19+. It opens a browser UI where you can list tools and call them by hand — worth doing before blaming your client. There is a scriptable --cli mode too; see docs/testing.md.

Pass variables with -e, not from your shell. Inspector does not give the server it spawns your environment, so GRAPH_MCP_CLIENT_ID=… npx @modelcontextprotocol/inspector … starts the server with no client id. The -e flags go after the server command.

Running from source instead

Same blocks as above — swap the command and args for your clone's absolute path:

"command": "uv",
"args": ["run", "--directory", "/Users/you/workspace/ms-graph-mcp", "ms-graph-mcp"]

Two things catch people out here:

uv must be on the client's PATH. GUI apps launched from Finder or the Dock do not inherit your shell's PATH, so a client can fail to start the server with an unhelpful error. If that happens, put the output of which uv in "command" instead of the bare name.

--directory is not optional. Without it, uv run resolves against whatever directory the client happened to launch from, which will not be the project.

Something not working?

docs/troubleshooting.md covers the Entra errors, Conditional Access, corporate TLS proxies, and the "server disconnected" that is almost always a startup error your client is hiding.

Configuration

Two settings get you running; everything else has a working default.

Every setting, both deployment shapes, and the hosted/OBO options are in docs/configuration.md. For running it as a service, see docs/hosting.md.

Toolset profiles

85 tools is a lot to put in front of a model. GRAPH_MCP_TOOLSETS selects named profiles, each a group of namespaces:

Combine them with commas:

GRAPH_MCP_TOOLSETS=mail,calendar,tasks

core is the default, so some tools are not advertised unless you ask for them. If you want Teams chat, Planner, OneNote, meeting transcripts or directory lookups, name those profiles — or set GRAPH_MCP_TOOLSETS=all to expose everything.

Over HTTP a caller may send X-Toolsets to narrow further for one request. It can only narrow. The startup value is a ceiling, so a client asking for all gains nothing the deployment did not already enable. This filters visibility, not authority — the write-scope and internal-tier gates are what actually stop a call.

Tool surface

Three tiers, one auth seam.

The internal tier is not part of the agent surface. A model sees 76 agent-visible tools. By namespace: mail 11 · tasks 11 · calendar 10 · files 10 · chat 8 · directory 7 · meetings 7 · people 6 · notes 5 · search 1.

Tool names are namespaced by Graph permission family rather than by Microsoft product, because real questions cross product boundaries — files_ covers OneDrive and SharePoint document libraries, which are the same driveItem resource underneath.

Every tool declares MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so clients know what needs confirming, and every description names the delegated permission it requires.

Renamed in 0.2.0. Every pre-0.2.0 tool name still works as an alias, and will keep working until 0.4.0. Aliases are honoured by tools/call but never advertised in tools/list, so they cost no context.

Documentation

Published as a searchable site at https://nitinksingh.com/ms-graph-mcp/.

What's next

SharePoint sites and lists are the largest gap; directory completion, file move/delete, and mail drafts follow. Sovereign clouds (GCC High / 21Vianet) are unsupported today. The full list, and what is deliberately out of scope, is in docs/roadmap.md.

Getting help

• Setup and app-registration questions → Discussions
• Bugs → Issues, with the output of running the server in a terminal
• Security vulnerabilities → never a public issue; see SECURITY.md

Never paste an access token, client secret or shared secret into any of them.

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md; participation is governed by the Code of Conduct.

uv sync
uv run pytest -q            # full suite, offline, about two seconds
uv run ruff check .
uv run ruff format .

License

MIT — see LICENSE.