msgraph-mcp

A Model Context Protocol (MCP) server that gives AI assistants full access to Microsoft Outlook email and calendar through the Microsoft Graph API. Built on FastMCP, it supports delegated authentication via device-code flow and can run locally or in a framework-managed cloud environment.

Features

26 tools across mail, calendar, contacts, and scheduling:

Mail

• Read — list folders, messages, search (OData $search), attachments (inline base64 for files under 1.5 MB)

• Compose — send, reply, reply-all, forward with dry-run preview by default

• Drafts — create, update, attach files, then send when ready

• Organize — mark read/unread, flag, categorize, move to folder, soft- or hard-delete

• Bulk — multi-pass filtered operations (delete, mark read/unread, move) with dry-run preview, up to 1 000 messages per call

• Folders & aliases — create mail folders, list send-from addresses

Calendar

• Read — list calendars, events (default window: yesterday through 14 days out), full event details

• Write — create, update, delete/cancel events with attendees, body, location, all-day support

• Shared calendars — full read/write access to other users' calendars via user_id parameter

• Scheduling — check free/busy status for multiple users, or let Graph suggest optimal meeting times

• Responses — accept, decline, or tentatively accept meeting invitations

Contacts

• People search — resolve display names to email addresses using the People API

Authentication

• Device-code flow — interactive three-step auth (start_auth → user approves → finish_auth)

• Multi-account — cache and switch between multiple Microsoft accounts

• Framework mode — accept pre-authenticated tokens via environment variables for serverless deployments

Related MCP server: m365-mcp-server

Tool reference

Prerequisites

• Python 3.11+

• An Azure app registration with delegated Microsoft Graph permissions (see below)

• uv (recommended) or pip

Azure app registration

Create an app registration in Microsoft Entra admin center (Azure AD).

1. Supported account types

Choose one:

• Accounts in this organizational directory only — single tenant

• Accounts in any organizational directory — multi-tenant work/school accounts

2. Authentication

• Enable Allow public client flows (required for device-code flow)

3. API permissions

Add delegated Microsoft Graph permissions:

For read-only use, replace Mail.ReadWrite and Mail.Send with Mail.Read, and Calendars.ReadWrite / Calendars.ReadWrite.Shared with Calendars.Read. Write tools will return permission errors but everything else works.

4. Admin consent

Grant admin consent for the tenant if required by your organization's policies.

Configuration

Copy .env.example to .env and fill in your values:

cp .env.example .env

Recommended tenant values:

• organizations — work/school accounts only (most common for enterprise)

• A specific tenant GUID — locks authentication to a single organization

• common — any Microsoft account (work, school, or personal)

Deployment

Local (stdio)

The default transport is stdio, suitable for desktop MCP clients like Claude Code, Claude Desktop, Cursor, and VS Code.

# Install dependencies
uv sync

# Run the server
uv run msgraph-mcp

Or with pip:

pip install -e .
msgraph-mcp

MCP client configuration

Add to your MCP client's configuration (e.g. Claude Desktop claude_desktop_config.json, .mcp.json for Claude Code, etc.):

{
  "mcpServers": {
    "msgraph-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "msgraph-mcp"],
      "env": {
        "MICROSOFT_CLIENT_ID": "your-client-id",
        "MICROSOFT_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

If you use a .env file in the project directory, the env block can be omitted.

Cloud — AWS Lambda with mcp-lambda-wrappers (ChatGPT, Claude.ai)

For use with remote MCP clients like ChatGPT and Claude.ai, this server can be deployed as a serverless AWS Lambda function using mcp-cloud-wrappers. That framework wraps any stdio-based MCP server behind Amazon Bedrock AgentCore Gateway with full OAuth 2.0 and Dynamic Client Registration (RFC 7591) support — no code changes required in this project.

What the framework provides:

• Serverless deployment — runs this MCP server as a Lambda subprocess behind AgentCore Gateway

• Per-user OAuth — each user authenticates with their own Microsoft account; tokens are stored in AWS Secrets Manager with automatic refresh

• Caller authentication — Cognito JWT validation for all inbound requests

• Dynamic Client Registration — MCP clients (ChatGPT, Claude.ai) self-register via a standard /register endpoint

• Zero idle cost — Lambda functions spin up on demand

How it works:

1. An MCP client sends a tool call to the AgentCore Gateway endpoint

2. The framework validates the caller's JWT, extracts their identity, and loads their Microsoft Graph OAuth token from Secrets Manager

3. The token is injected as GRAPH_ACCESS_TOKEN into this server's environment

4. This server runs as a subprocess, reads the token, and executes the tool against Microsoft Graph

5. If the user hasn't authenticated yet, start_auth returns the framework's OAuth URL instead of a device code

This project is used as the reference example service in mcp-lambda-wrappers — see infra/lambda/services/msgraph/ in that repo for the full configuration.

Quick deploy (from the mcp-lambda-wrappers repo):

# One-time: deploy shared infrastructure (Cognito, DCR, OAuth callback)
make deploy-shared

# Create the Azure app secret
aws secretsmanager create-secret \
  --name mcp-wrappers-msgraph-service-secrets \
  --secret-string '{"MICROSOFT_CLIENT_ID": "your-client-id"}'

# Generate tool definitions and deploy
make gen-tools SERVICE=msgraph
make deploy-service SERVICE=msgraph

Framework environment variables

When running inside the framework, this server auto-detects Lambda mode via these injected environment variables:

In this mode:

• The MSAL device-code flow is bypassed — tokens are injected by the framework

• No local token cache is used (compatible with read-only filesystems like Lambda's /var/task)

• auth_status reports the framework-managed token state

• start_auth / finish_auth return guidance to authenticate through the framework's OAuth flow instead

Docker

While no Dockerfile is included, the server can be containerized:

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir .
ENV MICROSOFT_CLIENT_ID=""
ENV MICROSOFT_TENANT_ID="organizations"
EXPOSE 8000
CMD ["msgraph-mcp"]

For persistent authentication, mount a volume for the token cache:

docker run -v msgraph-data:/app/.data \
  -e MICROSOFT_CLIENT_ID=your-id \
  -e MICROSOFT_TENANT_ID=your-tenant \
  msgraph-mcp

Safety defaults

Write operations default to safe behavior:

Security

• Path segment validation — all user-supplied IDs are validated against a safe-character pattern before URL interpolation, blocking path traversal

• Next-link hardening — pagination only follows HTTPS URLs on the configured Graph host

• Search sanitization — double-quotes stripped from OData $search queries

• Retry with backoff — automatic retry for HTTP 429 and transient 5xx errors (3 attempts, respects Retry-After)

• Error translation — raw Graph API payloads are never exposed to callers

• Token cache permissions — cache file 0600, parent directory 0700, symlinks rejected

See SECURITY_REVIEW.md for the full threat model and remaining risks.

Development

# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Or with pip
pip install -e '.[dev]'
pytest

Smoke test harness

A CLI harness for manual testing without a full MCP client:

# Auth
python3 scripts/smoke_test.py status
python3 scripts/smoke_test.py start-auth
python3 scripts/smoke_test.py finish-auth
python3 scripts/smoke_test.py list-accounts

# Mail
python3 scripts/smoke_test.py list-folders
python3 scripts/smoke_test.py list-messages --folder inbox --limit 5
python3 scripts/smoke_test.py get-message MESSAGE_ID
python3 scripts/smoke_test.py search-messages "search term"
python3 scripts/smoke_test.py mark-message-read MESSAGE_ID
python3 scripts/smoke_test.py move-message MESSAGE_ID archive
python3 scripts/smoke_test.py delete-message MESSAGE_ID
python3 scripts/smoke_test.py bulk-manage-messages --sender-contains "newsletters" --limit 50

# Calendar
python3 scripts/smoke_test.py list-calendars
python3 scripts/smoke_test.py list-events --limit 10
python3 scripts/smoke_test.py get-event EVENT_ID

License

See LICENSE for details.