ms-graph-mcp

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

• No msgraph-sdk, no azure-identity — the Graph client is raw httpx, so the dependency tree stays small and the wire behaviour is inspectable.

• 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.

• Read/write separation is enforced, not advisory — write tools are hidden and refused unless the caller explicitly opts in.

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

Install

Not yet on PyPI. The package name is unclaimed and the release pipeline is in place, but nothing has been published. Until the first release, install from source. The uvx --from ms-graph-mcp commands below are what will work after publication; substitute --from git+https://github.com/nitin27may/ms-graph-mcp today.

# From source (works now)
git clone https://github.com/nitin27may/ms-graph-mcp
cd ms-graph-mcp
uv sync

# After the first PyPI release
uv add ms-graph-mcp
# or
pip install ms-graph-mcp

Related MCP server: ms-teams-mcp

Run

stdio — Claude Desktop, Claude Code, any local MCP client

GRAPH_MCP_ACCESS_TOKEN=<a delegated Microsoft Graph token> \
  uvx --from ms-graph-mcp ms-graph-mcp

// claude_desktop_config.json
{
  "mcpServers": {
    "ms-graph": {
      "command": "uvx",
      "args": ["--from", "ms-graph-mcp", "ms-graph-mcp"],
      "env": {
        "GRAPH_MCP_ACCESS_TOKEN": "<delegated graph token>",
        "GRAPH_MCP_USER_EMAIL": "you@yourtenant.com"
      }
    }
  }
}

Streamable HTTP

GRAPH_MCP_PORT=8094 uvx --from ms-graph-mcp ms-graph-mcp-http
curl -s localhost:8094/health

Per-request headers:

Embed in your own app

from ms_graph_mcp.app import build_app
from ms_graph_mcp.config import GraphMcpConfig

app = build_app(GraphMcpConfig(shared_secret="…"))  # a Starlette app — mount or serve it

build_app(cfg, *, setup_telemetry=None, instrument_starlette=None) takes optional OpenTelemetry hooks. The domain modules also work as plain async functions, without MCP:

from ms_graph_mcp import calendar

events = await calendar.calendar_list_upcoming_events(params, {"access_token": tok})

Configuration

All settings are read from the environment (a .env in the working directory is picked up). GRAPH_MCP_* is canonical; the three app-registration fields also accept the conventional AZURE_AD_* names.

GRAPH_MCP_JWT_VERIFY defaults on. Turn it off only for a local run with no JWKS connectivity — with it off, token signatures are not verified. There is deliberately no setting that skips authentication altogether; see ADR 0003.

Tool surface

Three tiers, one auth seam.

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.

By namespace: files 10 · directory 7 · mail 7 · meetings 7 · tasks 6 · calendar 4 · chat 4 · people 3 · notes 3.

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.3.0. Aliases are accepted by tools/call but are not advertised in tools/list.

The lists live in ms_graph_mcp.allowlists and are resolved against the tool registry on every tools/list. A name in an allowlist with no registered tool raises rather than being skipped — the server refuses to serve a partial surface instead of silently dropping a tool.

Documentation

Development

uv sync
uv run pytest -q            # full suite
uv run ruff check .
uv run ruff format .

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

Roadmap

Tracked in more detail in the issues. The near-term programme:

• MCP SDK 2.x — done. Speaks the 2026-07-28 protocol revision while still serving 2025-era clients. Note that 2.x moves the SDK's HTTP stack to httpx2, a distribution separate from the httpx this server's Graph client uses; consolidating the two is tracked separately.

• OAuth resource server — RFC 9728 Protected Resource Metadata, WWW-Authenticate challenges, and RFC 8707 audience binding, so any spec-compliant MCP client can authenticate without client-specific configuration.

• Toolset profiles — expose a subset of the 55 tools per client, to cut the tool-definition tokens an agent pays before it does any work.

• Graph coverage — SharePoint sites and lists, unified /search/query, calendar write, and 1:1 chats are the notable gaps.

• Full documentation: app-registration setup, the delegated-permission matrix per tool, and end-to-end configuration for VS Code, Claude Code, Claude Desktop and MCP Inspector.

• Sovereign cloud support (GCC High / 21Vianet) — a few Graph and login endpoints are still hardcoded to the commercial cloud.

• Publish to PyPI, and a container image on GHCR.

Contributing

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

License

MIT — see LICENSE.