MSGraph MCP

A Model Context Protocol (MCP) server for Microsoft Graph. It exposes Microsoft Outlook mail and calendar, plus read-only Microsoft Teams message history, to AI agents via the Microsoft Graph SDK. It acts as the signed-in user, using delegated permissions and MSAL device code flow, so it can only reach what that user can reach.

Install

You need Python ≥ 3.11 and an Entra (Azure AD) app registration. The app registration takes about ten minutes and may need an administrator, so do that first: see the Entra setup section below.

uv tool install msgraph-mcp-server   # or: pip install msgraph-mcp-server

The package is msgraph-mcp-server. It installs three commands: msgraph-mcp and its alias msgraph-mcp-server, which both start the stdio server, plus msgraph-mcp-login for the one-time sign-in.

Setup

1. Set your Entra app credentials.

export MSGRAPH_MCP_CLIENT_ID=<your app's client ID>
export MSGRAPH_MCP_TENANT_ID=<your tenant ID>   # or: common / organizations / consumers

2. Sign in once. This prints a URL and a code; visit the URL and enter the code. No client secret is involved or stored.

msgraph-mcp-login
# running via uvx instead of installing: uvx --from msgraph-mcp-server msgraph-mcp-login

A token cache is written to ~/.msgraph-mcp/token_cache.bin.

3. Wire the server into your MCP host.

Claude Code:

claude mcp add msgraph \
  --env MSGRAPH_MCP_CLIENT_ID=$MSGRAPH_MCP_CLIENT_ID \
  --env MSGRAPH_MCP_TENANT_ID=$MSGRAPH_MCP_TENANT_ID \
  -- msgraph-mcp

Any other host, over stdio:

{
  "mcpServers": {
    "msgraph": {
      "command": "msgraph-mcp",
      "args": [],
      "env": {
        "MSGRAPH_MCP_CLIENT_ID": "<your app's client ID>",
        "MSGRAPH_MCP_TENANT_ID": "<your tenant ID>"
      }
    }
  }
}

To run without installing, use "command": "uvx" with "args": ["msgraph-mcp-server"]. Note that uvx does not put msgraph-mcp-login on your PATH, so sign in with the uvx --from form shown in step 2.

MSGRAPH_MCP_TOKEN_CACHE_PATH optionally overrides the cache location. All three variables can also come from a .env file in the working directory; the process environment wins over it.

Entra setup

The app registration requires:

• Account type: single tenant (multi-tenant works too; set MSGRAPH_MCP_TENANT_ID to common, organizations, or consumers)
• Redirect URI (public client): https://login.microsoftonline.com/common/oauth2/nativeclient
• Allow public client flows: Yes, under Authentication → Advanced settings. Device code flow fails without it.
• Delegated permissions (Microsoft Graph):
  • Mail: Mail.ReadWrite, Mail.ReadWrite.Shared, Mail.Send
  • Rules: MailboxSettings.ReadWrite (Graph requires this for the messageRules endpoints)
  • Calendar: Calendars.ReadWrite, Calendars.ReadWrite.Shared
  • Identity: User.Read
  • Teams: Chat.Read, Team.ReadBasic.All, Channel.ReadBasic.All, ChannelMessage.Read.All

ChannelMessage.Read.All always needs tenant admin consent, and the *.Shared permissions may need it depending on your tenant.

The scope list is all-or-nothing. Sign-in requests every scope at once, so without admin consent for ChannelMessage.Read.All the login fails outright and mail and calendar are unavailable too. For the same reason, adding scopes lat

... View full README on GitHub