Graph MCP

An MCP server that connects Claude to Microsoft Teams, Outlook Calendar, and Mail through the Microsoft Graph API.

What it does

Gives Claude access to 41 tools:

Prerequisites

You need an Azure App Registration:

1. Go to Azure Portal > App registrations > New registration

2. Set platform to Mobile and desktop applications

3. Set redirect URI to http://localhost:3000/auth/callback

4. Mark as Public client (no client secret needed)

5. Under API permissions, add these delegated permissions:

   • offline_access, openid, profile, User.Read
   • User.ReadBasic.All
   • Chat.Read, Chat.ReadWrite, ChatMessage.Send
   • ChannelMessage.Read.All, ChannelMessage.Send
   • Team.ReadBasic.All, Channel.ReadBasic.All, ChannelMember.Read.All
   • Calendars.ReadWrite
   • Mail.Read, Mail.Send
   • Presence.Read, Presence.Read.All, Presence.ReadWrite
   • OnlineMeetings.Read, OnlineMeetingTranscript.Read.All, OnlineMeetingRecording.Read.All
   • Files.ReadWrite.All

Install

pip install graph-mcp

Or from a cloned repo:

pip install -e .

Setup

graph-mcp setup

This asks for your Azure Client ID and Tenant ID, then gives you the exact command:

claude mcp add graph -e AZURE_CLIENT_ID=your-id -e AZURE_TENANT_ID=your-tenant -- /path/to/graph-mcp

Paste it, start Claude Code, and ask Claude to log in. It opens your browser for OAuth sign-in — that's it.

Message and email formatting

The Teams message tools (graph_send_chat_message, graph_send_channel_message, and graph_reply_to_channel_message) and outbound mail tools (graph_send_mail, graph_reply_mail) default to HTML mode. When is_html=true, pass explicit HTML and it will be sent as-is. Markdown is not converted automatically.

Use Teams/Graph-compatible HTML for formatted messages:

<p><strong>Status update</strong></p>
<ul>
  <li>Use <code>&lt;strong&gt;</code> for bold text.</li>
  <li>Use <code>&lt;pre&gt;&lt;code&gt;</code> for multi-line code blocks.</li>
  <li>Use placeholder text like <code>YOUR_NAME</code>, not <code>&lt;your-name&gt;</code>.</li>
</ul>

Use is_html=false for plain text bodies. Plain text is sent as exact text and is not formatted.

For email, the same rule applies: use explicit HTML when is_html=true, or plain text when is_html=false.

These tools also support optional top-level Graph API mentions, either in raw Graph format or a simplified shape such as:

[
  {
    "name": "Jane Smith",
    "user_id": "ef1c916a-3135-4417-ba27-8eb7bd084193"
  }
]

Use the corresponding <at id="0">Jane Smith</at> tag in the HTML body to trigger a real Teams mention.

How it works

Claude Code  ──stdio──>  graph-mcp  ──HTTPS──>  Microsoft Graph API
                              │
                         ~/.graph-mcp/
                           tokens.enc  (encrypted)
                           .key        (auto-generated)

• Auth: OAuth2 Authorization Code flow with PKCE. Login opens your browser, a local callback server captures the token. No secrets stored in config.
• Token persistence: Tokens are encrypted with Fernet and stored in ~/.graph-mcp/tokens.enc. The encryption key is auto-generated on first use. Logins survive server restarts.
• Token refresh: Access tokens are refreshed automatically before they expire. You only need to log in again if the refresh token itself expires.
• Rate limiting: Sliding window counter with exponential backoff. Respects Retry-After headers on 429 responses.

Configuration

All configuration is passed via environment variables (set in the MCP config's env block):

Troubleshooting

"Approval required" error during login Your Azure app is requesting scopes that aren't registered or need admin consent. Check the API permissions in the Azure portal match the list above.

403 Forbidden on specific tools The endpoint needs a permission that's not in your Azure app registration, or requires admin consent.

Login works but tools say "not authenticated" Restart the MCP server (claude mcp restart graph) — it may be running an old version.

Disclaimer

This project is an independent open-source effort and is not affiliated with, endorsed by, or sponsored by Microsoft Corporation. Microsoft, Microsoft Teams, Outlook, Microsoft 365, Microsoft Graph, and Azure are trademarks of the Microsoft group of companies.

This software is provided "as is", without warranty of any kind. Use it at your own risk. The authors accept no liability for any damages, data loss, or security issues arising from the use of this software. You are responsible for complying with your organization's policies and Microsoft's API Terms of Use when using this tool.

This software accesses Microsoft services on your behalf using your own credentials and Azure app registration. Data retrieved from Microsoft Graph (emails, messages, calendar events, etc.) is passed to the LLM that invoked the tool. Be mindful of your organization's data handling policies when using this with cloud-hosted AI models.

License

MIT — see LICENSE.