@sullyman/graph-mcp

graph-mcp

MCP Server for Microsoft Graph API — multi-tenant MSP management without GDAP.

Lets Claude Code manage users, groups, licenses, devices, security, mail, calendar, Teams, SharePoint, and more across all your customer tenants through natural language. 101 tools across 19 categories covering the full Microsoft Graph API surface, plus 28 MSP workflow skills organized by certification tier (Fundamentals → Associate → Expert).

Prerequisites

• Node.js 18+
• That's it! No Azure App Registration needed for basic usage.

How? The server defaults to Microsoft Graph PowerShell SDK's well-known public client ID (14d82eec-204b-4c2f-b7e8-296a70dab67e). This is a Microsoft-published multi-tenant app with broad delegated permissions — no custom registration required. You can override with your own CLIENT_ID if needed.

Quick Start

# Clone and install
git clone https://github.com/your-org/graph-mcp.git
cd graph-mcp
npm install

# Build
npm run build

Add to Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "viyu-graph": {
      "command": "node",
      "args": ["/path/to/graph-mcp/dist/index.js"]
    }
  }
}

No CLIENT_ID env var needed. The server uses Microsoft's public client ID by default. To use your own app registration, add "env": { "CLIENT_ID": "your-app-id" } to the config above.

First Use — Onboarding a Tenant

Once the server is running in Claude Code, there's no need to manually edit tenant config files. Just say:

"Set up a new tenant called contoso"

Claude will call the onboard-tenant tool which:

• Displays a Device Code URL + code in the terminal
• You open the URL in your browser and sign in with Global Admin credentials
• The tenant ID and domain are auto-detected and saved to config/tenants.json
• You're authenticated and ready to go

Repeat for each customer tenant.

Azure App Registration (Optional)

By default, graph-mcp uses the Microsoft Graph PowerShell SDK public client ID — no app registration needed. The sections below are only relevant if you want to use your own custom app registration with CLIENT_ID env var.

Custom App Registration Setup (click to expand)

• Go to Entra ID > App registrations
• New registration
• Name: Graph MCP
• Supported account types: "Accounts in any organizational directory" (multi-tenant)
• Redirect URI: Mobile and desktop applications → https://login.microsoftonline.com/common/oauth2/nativeclient
• No client secret needed — Device Code uses PublicClientApplication

API Permissions (Delegated)

Add these delegated permissions under Microsoft Graph:

Permission	Purpose
User.ReadWrite.All	Manage users
Group.ReadWrite.All	Manage groups
Directory.ReadWrite.All	Directory roles, org info
Organization.Read.All	Tenant organization info
Domain.Read.All	Verified domains
Mail.ReadWrite	Read and send email
Mail.Send	Send email on behalf of users
Calendars.ReadWrite	Manage calendar events
DeviceManagementManagedDevices.ReadWrite.All	Intune device management
DeviceManagementConfiguration.Read.All	Intune configuration policies
SecurityEvents.ReadWrite.All	Security alerts and incidents
IdentityRiskyUser.Read.All	Risky user detection
IdentityRiskEvent.Read.All	Risk event detection
Policy.Read.All	Conditional Access and auth policies
AuditLog.Read.All	Sign-in and audit logs
Reports.Read.All	Usage reports
Team.ReadBasic.All	Teams management
Channel.ReadBasic.All	Teams channels
ChannelMessage.Send	Send Teams messages
Sites.ReadWrite.All	SharePoint sites and OneDrive
Files.ReadWrite.All	OneDrive files
Application.Read.All	App registrations
DelegatedPermissionGrant.ReadWrite.All	OAuth2 consent grants
RoleManagement.Read.Directory	Directory role memberships
UserAuthenticationMethod.Read.All	User MFA method details

Grant admin consent in your MSP tenant.

Customer Tenant Consent

For each customer tenant, have their Global Admin visit:

https://login.microsoftonline.com/{customer-tenant-id}/adminconsent?client_id={your-app-client-id}

Or use the onboard-tenant tool which handles this interactively.

Available Tools (101)

Tenant Management (6 tools)

Tool	Description
list-tenants	List all configured tenants
switch-tenant	Switch active tenant context
current-tenant	Show current tenant
add-tenant	Register a new tenant manually
onboard-tenant	Interactive setup: Device Code login + auto-detect + save config
remove-tenant	Remove a tenant from config

Authentication (3 tools)

Tool	Description
login	Device Code auth (URL + code shown in terminal)
logout	Clear cached tokens
auth-status	Check token status and expiry

Users (5 tools)

Tool	Description
list-users	List users with OData filtering ($filter, $select, $top)
get-user	Get user by ID or UPN
create-user	Create new user
update-user	Update user properties
reset-password	Reset user password

Groups (6 tools)

Tool	Description
list-groups	List groups with filtering
get-group	Get group details
create-group	Create security or M365 group
list-group-members	List group members
add-group-member	Add user to group
remove-group-member	Remove user from group

Directory (4 tools)

Tool	Description
get-organization	Tenant/org info
list-domains	Verified domains
list-directory-roles	Directory roles
list-role-members	Members of a role

Applications (6 tools)

Tool	Description
list-applications	App registrations
get-application	App registration details
list-service-principals	Enterprise applications
get-service-principal	Enterprise app details
list-app-role-assignments	User's app access
list-oauth2-permission-grants	Consent grants audit

Mail (5 tools)

Tool	Description
list-messages	List emails for a user
get-message	Get specific email
send-mail	Send email on behalf of user
list-mail-folders	List mail folders
reply-to-message	Reply / reply-all

Calendar (6 tools)

Tool	Description
list-events	List calendar events
get-event	Get event details
create-event	Create event (with Teams meeting option)
update-event	Update event
delete-event	Delete event
get-schedule	Free/busy availability check

Teams (6 tools)

Tool	Description
list-teams	List all teams
get-team	Get team details
list-channels	List channels in a team
create-channel	Create channel (standard/private/shared)
send-channel-message	Post message to channel
list-team-members	List team members

SharePoint & OneDrive (7 tools)

Tool	Description
list-sites	List/search SharePoint sites
get-site	Get site details
list-site-lists	Lists in a site
list-drives	Document libraries for site or user
list-drive-items	Files and folders in a drive
search-drive-content	Search files across SP/OneDrive
create-sharing-link	Create sharing link for a file

Devices & Intune (8 tools)

Tool	Description
list-managed-devices	Intune managed devices
get-managed-device	Device details
sync-device	Trigger device sync
reboot-device	Remote reboot
wipe-device	Remote wipe (destructive)
list-compliance-policies	Compliance policies
list-device-configurations	Configuration profiles
list-detected-apps	Apps detected on devices

Security (8 tools)

Tool	Description
list-security-alerts	Security alerts (Defender)
get-security-alert	Alert details
update-security-alert	Update alert status/classification
get-secure-scores	Microsoft Secure Score
list-secure-score-profiles	Recommended security actions
list-incidents	Security incidents
list-risky-users	Risky users (ID Protection)
list-risk-detections	Risk detections

Policies (7 tools)

Tool	Description
list-conditional-access-policies	CA policies
get-conditional-access-policy	CA policy details
list-named-locations	Named locations (IP/country)
list-authentication-methods-policy	MFA methods policy
list-user-auth-methods	User's registered auth methods
list-authorization-policy	Guest access settings
list-permission-grant-policies	App consent policies

Licenses (4 tools)

Tool	Description
list-subscribed-skus	All licenses in tenant
assign-license	Assign license to user
remove-license	Remove license from user
license-usage-report	Utilization summary

Reports & Audit (5 tools)

Tool	Description
list-sign-in-logs	Sign-in logs (AAD P1/P2)
list-audit-logs	Directory audit logs
list-provisioning-logs	App provisioning logs
get-credential-user-registration	MFA/SSPR registration report
get-m365-usage-reports	M365 usage reports (email, Teams, OneDrive, etc.)

Contacts (4 tools)

Tool	Description
list-contacts	List contacts for a user
get-contact	Get contact details
create-contact	Create a new contact
delete-contact	Delete a contact

Planner & To Do (7 tools)

Tool	Description
list-user-planner-plans	User's Planner plans
get-planner-plan	Plan details
list-planner-tasks	Tasks in a plan
list-user-planner-tasks	All tasks assigned to a user
list-planner-buckets	Buckets in a plan
list-todo-lists	User's To Do lists
list-todo-tasks	Tasks in a To Do list

Subscriptions (3 tools)

Tool	Description
list-subscriptions	Active webhook subscriptions
get-subscription	Subscription details
delete-subscription	Remove a subscription

Escape Hatch (1 tool)

Tool	Description
graph-request	Raw Graph API call (any method, path, query, body, version)

Install Skills (npm users)

If you installed via npm, use the built-in skill installer:

# Install skills to ~/.claude/skills/ (global)
npx graph-mcp --install-skills

# Install skills to a specific project
npx graph-mcp --install-skills /path/to/project

Restart Claude Code after installing skills.

Slash Commands (Skills)

These are Claude Code slash commands that orchestrate multiple tools into MSP workflows. Copy the .claude/commands/ directory into your project or global config to use them.

Tier 1: Fundamentals (Helpdesk / Tier-1 Support)

Skills designed for new hires and helpdesk techs — plain language, guided steps, no Graph API knowledge needed.

Command	Description
/troubleshoot-user	Guided user issue diagnosis — "can't log in", "no email", "Teams not working" with decision tree
/who-is	Quick user lookup — one-glance card with profile, status, MFA, licenses, groups, and roles
/explain-tenant	Plain-language tenant summary for client-facing reps and new MSP staff
/password-reset-guide	Guided password reset — checks lockout, risk, MFA before resetting with helpdesk script

Tier 2: Associate (M365 Admins / Security Analysts)

Workflow automation for multi-step tasks that take 30-60 minutes in admin portals.

Command	Description
/setup-tenant	Guided walkthrough for adding a new tenant
/tenant-health-check	Security posture, MFA adoption, risky users, license utilization
/tenant-overview	Quick summary — org info, user count, domains, licenses
/security-review	Deep security audit — MFA gaps, CA analysis, admin roles, app consent
/mfa-enforcement-check	MFA enrollment status, per-user registration, CA policy gaps
/app-consent-review	Third-party app consent audit, overprivileged app detection
/license-audit	License waste detection and optimization recommendations
/stale-accounts	Find inactive, disabled, and orphaned accounts
/group-audit	Empty groups, no-owner groups, large groups, dynamic vs static
/device-compliance-report	Managed device compliance, OS breakdown, stale devices
/user-onboard	Create user, assign licenses, add to groups, send welcome email
/user-offboard	Disable account, revoke sessions, remove licenses and groups
/investigate-user	Deep dive into a user — profile, sign-ins, risk, auth methods
/conditional-access-wizard	CA policy gap analysis against Microsoft-recommended baselines
/mail-flow-check	Email delivery diagnostics — mailbox status, forwarding, license, folder sizes
/bulk-license-assign	Batch license assign/remove across department or group with dry-run preview
/sign-in-analyzer	Sign-in log deep dive — geographic anomalies, impossible travel, brute force
/tenant-health-report	Standalone HTML health report with CSS gauges and NIST CSF alignment
/sync-licensing-to-itglue	Cross-MCP sync — push licensing data and contacts to ITGlue

Tier 3: Expert (Architects / MSP Leadership)

Cross-tenant intelligence, framework alignment (NIST, CIS, ITIL), and strategic reporting for QBRs.

Command	Description
/cross-tenant-report	Portfolio-wide health report across all managed tenants
/zero-trust-assessment	NIST/CIS/Microsoft Zero Trust maturity scoring across 6 pillars
/tenant-comparison	Side-by-side tenant diff on security, MFA, CA, licenses, and admin hygiene
/change-audit	Tenant change tracking — audit logs, provisioning, sign-in anomalies, security alerts
/tenant-architecture-review	Executive-ready QBR report — governance, security, cost optimization, roadmap

Security

Tool Annotations

All 101 tools have structured annotations that Claude Code uses to determine confirmation behavior:

Annotation	Tools	Behavior
readOnlyHint: true	GET operations (list-users, get-organization, etc.)	No confirmation needed
destructiveHint: true	wipe-device, delete-event, delete-subscription, remove-group-member	Confirmation required
idempotentHint: true	update-user, assign-license, update-security-alert	Safe to retry

Audit Logging

Two layers of audit logging provide defense in depth:

• Shell-based PostToolUse hook — captures every MCP tool invocation from any agent, writes to ~/.graph-mcp/audit.log
• Structured TypeScript audit logger — captures Graph API HTTP mutations (POST/PATCH/DELETE) with severity levels and structured JSON on stderr

Audit log entries include:

• Timestamp, severity (INFO/HIGH/CRITICAL), operation type
• Tenant ID and resource path
• Automatic sanitization of sensitive fields (tokens, passwords, secrets → [REDACTED])

Write Guard Hook

A PreToolUse hook gates destructive operations. The following tools require explicit user confirmation before execution:

• wipe-device — remote wipe (data loss)
• reset-password — credential change
• delete-event, delete-subscription, delete-contact — permanent deletion
• remove-group-member, remove-license — access revocation

Sensitive Data Sanitization

The audit logger automatically redacts values for keys containing: password, token, secret, authorization, client_id, api_key, refresh_token, access_token.

Environment Variables

Variable	Required	Default	Description
CLIENT_ID	No	MS Graph PowerShell SDK	Azure App Registration client ID (uses Microsoft's public client by default)
TENANTS_CONFIG_PATH	No	./config/tenants.json	Path to tenants config
GRAPH_API_VERSION	No	v1.0	Graph API version
LOG_LEVEL	No	info	error, warn, info, debug

Development

npm run dev         # Run with tsx (hot reload)
npm run build       # Build for production
npm run typecheck   # Type check without emitting
npm run lint        # ESLint
npm run inspector   # Test with MCP Inspector

Architecture

src/
├── index.ts              # Entry: stdio transport bootstrap
├── server.ts             # McpServer creation + tool registration
├── constants.ts          # Scopes, URLs, defaults
├── auth/                 # MSAL Device Code flow + token caching
│   ├── auth-manager.ts   # Per-tenant PCA instances, loginWithDiscovery
│   └── token-cache.ts    # ICachePlugin for file-based MSAL cache
├── tenants/              # Multi-tenant registry + switching
│   ├── tenant-manager.ts # Registry, resolve, add/remove, persist
│   └── tenant-config.ts  # JSON file I/O
├── graph/                # Authenticated Graph client + pagination
│   ├── graph-client.ts   # fetch wrapper, 429 retry, error parsing
│   └── pagination.ts     # OData @odata.nextLink follower
├── tools/                # MCP tool modules (one per category)
│   ├── tenant-tools.ts   # list/switch/add/onboard/remove tenant
│   ├── auth-tools.ts     # login/logout/status
│   ├── user-tools.ts     # CRUD users, reset password
│   ├── group-tools.ts    # CRUD groups, members
│   ├── directory-tools.ts
│   ├── application-tools.ts
│   ├── mail-tools.ts
│   ├── calendar-tools.ts
│   ├── teams-tools.ts
│   ├── sharepoint-tools.ts
│   ├── device-tools.ts
│   ├── security-tools.ts
│   ├── policy-tools.ts
│   ├── license-tools.ts
│   ├── reports-tools.ts
│   └── graph-explorer-tool.ts
├── types/                # TypeScript interfaces
└── utils/                # Logger (stderr), config, error classes

Key patterns:

• Stderr-only logging — stdout is the MCP JSON-RPC channel
• Per-tenant MSAL instances — lazily created, cached in memory
• File-based token cache — ~/.graph-mcp/cache/{tenantId}.json
• Auto-discovery onboarding — onboard-tenant detects tenant ID from Device Code auth
• Modular tools — each category in its own file, easy to extend