Skip to content

jspv/msgraph-email-calendar-mcp

BranchesTags

Repository files navigation

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

Tool reference

Area Tool Description
Auth auth_status Show configuration and cached accounts
Auth start_auth Begin device-code flow (returns URL + code)
Auth finish_auth Complete device-code flow after user approval
Mail list_folders List mail folders with item/unread counts
Mail list_messages List messages in a folder (limit 50)
Mail get_message Full message details including body
Mail search_messages Search via OData $search (limit 50)
Mail list_attachments List attachment metadata for a message
Mail get_attachments Download a single attachment
Mail send_message Send a new email (dry-run by default)
Mail reply_to_message Reply or reply-all (dry-run by default)
Mail forward_message Forward a message (dry-run by default)
Mail create_draft Create a draft without sending
Mail manage_draft Update or send an existing draft
Mail add_attachment_to_draft Attach a file to a draft
Mail update_message Mark read/unread, flag, or categorize
Mail move_message Move to a folder (supports well-known names)
Mail delete_message Soft-delete or permanently delete
Mail bulk_manage_messages Bulk filtered actions with dry-run (limit 1 000)
Mail create_folder Create a new mail folder
Mail list_aliases List email aliases / send-from addresses
Calendar list_calendars List calendars (own or shared via user_id)
Calendar list_events List events in a time range (limit 100)
Calendar get_event Full event details with attendees
Calendar create_event Create a calendar event
Calendar update_event Update an existing event
Calendar delete_event Delete or cancel an event
Calendar respond_to_event Accept, decline, or tentatively accept
Calendar check_availability Free/busy lookup or meeting time suggestions
Contacts search_people Search contacts by name (limit 50)

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:

Permission Purpose
User.Read Read signed-in user profile
Mail.ReadWrite Read, move, flag, categorize, delete mail
Mail.Send Send mail, reply, forward
Calendars.ReadWrite Read and write calendar events
Calendars.ReadWrite.Shared Access shared / delegated calendars
People.Read Search contacts by name

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
Variable Default Description
MICROSOFT_CLIENT_ID (required) Azure app registration client ID
MICROSOFT_TENANT_ID common organizations (work/school only), common (any), or a specific tenant GUID
MICROSOFT_SCOPES User.Read Mail.ReadWrite Mail.Send Calendars.ReadWrite Calendars.ReadWrite.Shared People.Read Space-separated delegated permissions
MICROSOFT_TOKEN_CACHE_PATH .data/msal_token_cache.json Path to the local MSAL token cache
MAX_ATTACHMENT_INLINE_SIZE 1572864 Max attachment size (bytes) for inline base64 (default 1.5 MB)

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:

Variable Description
GRAPH_ACCESS_TOKEN Pre-authenticated Microsoft Graph access token (per-user)
OAUTH_AUTHENTICATED Set to true when auth is complete
OAUTH_USER_ID Authenticated user identifier
OAUTH_AUTH_URL OAuth authorization URL (shown when user needs to authenticate)
SERVICE_NAME Service identifier for the framework

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:

Feature Default Notes
send_message dry_run=True Creates a temporary draft for preview, then deletes it
reply_to_message dry_run=True Preview before sending
forward_message dry_run=True Preview before sending
bulk_manage_messages dry_run=True Shows matches without executing
delete_message permanent=False Moves to Deleted Items (recoverable)

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.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages