Microsoft Graph MCP Server

A Model Context Protocol (MCP) server that provides access to Microsoft Graph API, enabling AI assistants to interact with Microsoft 365 services including users, mail, calendar, files, and more.

Features

• Microsoft Graph API Access: Execute any Graph API endpoint through a unified tool
• Multiple Authentication Modes:
  • Device Code Flow: Interactive browser-based authentication
  • Client Credentials: App-only authentication with client secret
  • Client Token: Manual token injection for flexibility
• Full API Coverage: Access Graph API v1.0 and beta endpoints
• Azure Management API: Optional support for Azure Resource Manager API

Installation

npm install microsoft-mcp-server
# or
pnpm add microsoft-mcp-server

Prerequisites

Azure App Registration

1. Go to Azure Portal > Microsoft Entra ID > App registrations
2. Click "New registration"
3. Name your app (e.g., "MCP Graph Server")
4. Select "Accounts in any organizational directory and personal Microsoft accounts"
5. Set Redirect URI to https://login.microsoftonline.com/common/oauth2/nativeclient (for device code flow)
6. Click "Register"

Configure API Permissions

1. In your app registration, go to "API permissions"
2. Click "Add a permission" > "Microsoft Graph"
3. Add the permissions you need:
   • Delegated (for device_code): User.Read, Mail.Read, Calendars.Read, etc.
   • Application (for client_credentials): User.Read.All, Mail.Read, etc.
4. Grant admin consent if required

Enable Public Client (for Device Code Flow)

1. Go to "Authentication"
2. Under "Advanced settings", set "Allow public client flows" to "Yes"
3. Save

Configuration

Create a .env file or set environment variables:

# Required: Azure App Registration
AZURE_CLIENT_ID=your-client-id
AZURE_TENANT_ID=common  # or specific tenant ID

# Authentication Mode (default: device_code)
AUTH_MODE=device_code  # device_code | client_credentials | client_token

# For client_credentials mode
AZURE_CLIENT_SECRET=your-client-secret

# For client_token mode
ACCESS_TOKEN=your-access-token

# Optional: Graph API Configuration
GRAPH_API_VERSION=v1.0  # v1.0 | beta
GRAPH_SCOPES=User.Read,Mail.Read,Calendars.Read

Usage

With Claude Code CLI

Add to your project's .mcp.json:

{
  "mcpServers": {
    "microsoft-graph": {
      "command": "npx",
      "args": ["microsoft-mcp-server"],
      "env": {
        "AZURE_CLIENT_ID": "your-client-id",
        "AZURE_TENANT_ID": "common",
        "AUTH_MODE": "device_code"
      }
    }
  }
}

With Claude Desktop

Add to your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "microsoft-graph": {
      "command": "npx",
      "args": ["microsoft-mcp-server"],
      "env": {
        "AZURE_CLIENT_ID": "your-client-id",
        "AZURE_TENANT_ID": "common",
        "AUTH_MODE": "device_code"
      }
    }
  }
}

Standalone

npx microsoft-mcp-server

Available Tools

microsoft_graph

Execute Microsoft Graph API requests.

Parameters:

| Parameter | Required | Description | | ------------- | -------- | --------------------------------------------------------- | | path | Yes | API endpoint path (e.g., /me, /users, /me/messages) | | method | No | HTTP method: GET, POST, PUT, PATCH, DELETE (default: GET) | | apiVersion | No | Graph API version: v1.0, beta (default: v1.0) | | apiType | No | API type: graph, azure (default: graph) | | queryParams | No | OData query parameters ($select, $filter, $top, etc.) | | body | No | Request body for POST/PUT/PATCH operations |

Example prompts to Claude:

• "Get my profile information from Microsoft Graph"
• "Show me my last 10 emails"
• "List all users in my organization"
• "Create a calendar event for tomorrow at 2pm titled 'Team Sync'"
• "Search for files containing 'budget' in my OneDrive"

get_auth_status

Check current authentication status. Returns authentication mode, token validity, scopes, and account info.

set_access_token

Manually set an access token for authentication.

| Parameter | Required | Description | | ------------- | -------- | ---------------------------------------------------------- | | accessToken | Yes | Bearer access token | | expiresOn | No | ISO datetime when token expires (default: 1 hour from now) |

sign_in

Initiate device code authentication flow. Displays a code and URL for browser sign-in.

sign_out

Clear all cached authentication tokens.

Authentication Modes

Device Code Flow (Recommended for Interactive Use)

1. Set AUTH_MODE=device_code
2. Ask Claude to sign in (triggers sign_in tool)
3. Visit the displayed URL and enter the code
4. Complete authentication in browser
5. Token is cached for subsequent requests

Client Credentials (App-Only)

1. Set AUTH_MODE=client_credentials
2. Set AZURE_CLIENT_SECRET
3. Requires application permissions (not delegated)
4. No user interaction required

Client Token (Manual)

1. Set AUTH_MODE=client_token
2. Either set ACCESS_TOKEN env var or ask Claude to set a token
3. Useful for testing or when tokens are obtained externally

Development

pnpm install          # Install dependencies
pnpm dev              # Development with watch
pnpm test             # Run tests
pnpm build            # Build for production
pnpm validate         # Format + lint + test + build
pnpm inspect          # Test with MCP Inspector

License

MIT