MSGraph MCP server

MSGraph MCP

<!-- mcp-name: io.github.timfurlong/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.

MSGRAPHMCPTOKENCACHEPATH 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 MSGRAPHMCPTENANT_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.

Shortened. The full README is on GitHub.