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 httpx, 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

  Copy

  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: