Microsoft 365 Admin

ms-365-admin-mcp-server

[CI] [npm version] [License: MIT]

A Model Context Protocol (MCP) server for Microsoft 365 administration via Graph API application permissions (client credentials).

Built on the architecture and endpoint-driven design pioneered by Softeria/ms-365-mcp-server, and complementary to it: Softeria's server uses delegated permissions for end-user productivity scenarios, while this one uses application permissions for admin operations — security monitoring, identity audits, incident response, and service health. See Acknowledgments below.

Features

• 674 tools covering security, audit, identity, app credentials, guest users, Exchange, Intune (devices, apps, MAM, reports, Settings catalog & Endpoint security (BitLocker, Antivirus, Firewall, ASR), encryption report, Windows Update profiles, BitLocker and LAPS rotation, macOS Platform Scripts, macOS custom attribute scripts, assignment filters, Remediations, Windows PowerShell scripts, custom compliance scripts), governance (PIM, access reviews, entitlement, lifecycle), compliance, threat intelligence, advanced hunting, Defender for Identity (sensors, candidates, migration, identity accounts, audit policy), Microsoft 365 Copilot admin (usage reports, interaction history audit, AI users, meeting insights, agent registrations, policy settings), custom security attributes, LAPS, policies, reports, incident response, eDiscovery v3 (cases, custodians, noncustodial data sources, review sets, queries, exports, operations), Purview DSPM (protection scopes), event-based retention triggers, Teams online meeting attendance reports (app-only with Application Access Policy), deleted chats restore (admin recovery flow), Teams chat investigation reads (Chat.Read.All for triage; eDiscovery v3 for court-admissible production), Cloud PC, call records, Universal Print, information protection, SharePoint admin, and records management
• Application permissions (client credentials) — no user interaction required
• Read-only by default — write operations require explicit --allow-writes
• Risk classification on write tools (low/medium/high/critical)
• Presets to filter tools by domain (security, audit, identity, etc.)
• Two transports: stdio (default) and HTTP (StreamableHTTP)
• Multi-cloud: Microsoft global and China (21Vianet)
• Key Vault support for secrets management

Documentation

Prerequisites

• Node.js >= 18
• An Azure AD app registration with application permissions (not delegated)
• A specific tenant ID (not "common")

Installation

npm (recommended)

npm install -g @okapi-ca/ms-365-admin-mcp-serverms-365-admin-mcp-server --help

Docker

docker pull ghcr.io/okapi-ca/ms-365-admin-mcp-server:latestdocker run --rm -i \  -e MS365_ADMIN_MCP_CLIENT_ID=... \  -e MS365_ADMIN_MCP_CLIENT_SECRET=... \  -e MS365_ADMIN_MCP_TENANT_ID=... \  ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest

From source

git clone https://github.com/okapi-ca/ms-365-admin-mcp-server.gitcd ms-365-admin-mcp-servernpm installnpm run generatenpm run build

Configuration

Environment variables

MCP client configuration (Claude Desktop, etc.)

{  "mcpServers": {    "ms365-admin": {      "command": "node",      "args": ["/path/to/ms-365-admin-mcp-server/dist/index.js"],      "env": {        "MS365_ADMIN_MCP_CLIENT_ID": "your-client-id",        "MS365_ADMIN_MCP_CLIENT_SECRET": "your-client-secret",        "MS365_ADMIN_MCP_TENANT_ID": "your-tenant-id"      }    }  }}

VS Code (1.102+)

VS Code consumes the same MCP protocol but uses a different config layout — servers instead of mcpServers, an explicit type field, and inputs for secret prompts. A ready-to-copy sample lives at .vscode/mcp.json.example; copy it to .vscode/mcp.json and VS Code will prompt for the tenant / client / secret on first start, then store them in its secret store (the real mcp.json is gitignored so resolved secrets never reach the repo).

Minimal stdio setup:

{  "inputs": [    { "type": "promptString", "id": "ms365-tenant-id", "description": "Tenant ID" },    { "type": "promptString", "id": "ms365-client-id", "description": "Client ID" },    {      "type": "promptString",      "id": "ms365-client-secret",      "description": "Client secret",      "password": true,    },  ],  "servers": {    "ms365-admin": {      "type": "stdio",      "command": "ms-365-admin-mcp-server",      "args": ["--preset", "security,audit,identity,health"],      "env": {        "MS365_ADMIN_MCP_TENANT_ID": "${input:ms365-tenant-id}",        "MS365_ADMIN_MCP_CLIENT_ID": "${input:ms365-client-id}",        "MS365_ADMIN_MCP_CLIENT_SECRET": "${input:ms365-client-secret}",      },    },  },}

For remote HTTP deployments, use "type": "http" with a url field (VS Code 1.103+ handles OAuth 2.0 Dynamic Client Registration natively) or fall back to the mcp-remote bridge when the native browser flow is unavailable — see the example file for both shapes.

Tools surface in Agent mode (GitHub Copilot Chat). VS Code asks for per-tool approval; the --preset flag above keeps the catalog manageable. Use Cmd/Ctrl+Shift+P → MCP: List Servers → Show Output to see logs.

Catalog size limit on Claude.ai surfaces

Claude.ai, Claude Desktop and cloud sessions serve each connector's tools under a fixed budget of 1 MiB of input schema (compact JSON; tool names and descriptions are not counted). Tools are admitted in alphabetical order and a tool that no longer fits is dropped silently. Claude Code CLI is not affected. The limit is not documented publicly.

In a cloud session linked to a Mac, the claude-device bridge relays every local MCP server under one connector (lcl-<server>-<tool>), so all local servers share that budget, and this server's tools sort after most of them.

Request bodies are therefore advertised shallow (src/advertised-schema.ts): the entity's own fields with their descriptions, nested objects as free-form objects, and no Read-only. fields. Graph validates the body; the server forwards it as sent. With writes enabled the catalog advertises about 595 KB of input schema, and test/advertised-schema.test.ts fails the build above 768 KiB.

If tools still go missing in a cloud session, shrink what this server advertises (read-only mode, --preset, --enabled-tools), disable unused local servers, or register this server as its own connector so it gets a budget of its own.

Remote HTTP server: device_code authentication (RFC 8628)

If the server runs in HTTP / OAuth mode on a remote host (e.g. Azure Container Apps) and the client connects via mcp-remote, the standard flow requires a browser to reach localhost:14543/oauth/callback. When that isn't possible — macOS Platform SSO hijacks the WebKit flow, Claude Code runs in a headless Docker container, the user is on a remote SSH dev env — use the ms-365-admin-mcp-auth bootstrap to pre-seed mcp-remote's token cache instead.

npx -p @okapi-ca/ms-365-admin-mcp-server@latest ms-365-admin-mcp-auth \  --server https://your-mcp-host.azurecontainerapps.io/mcp

The helper prints a URL and a user code; you sign in on any device you trust (phone, another laptop) and the tokens are written to ~/.mcp-auth/mcp-remote-<version>/. Claude Desktop / Claude Code then launches mcp-remote normally and finds the cached tokens without ever opening a browser.

See docs/TROUBLESHOOTING.md for Docker / remote-dev patterns and exit code reference.

Usage

CLI options

--read-only              Read-only mode (default)--allow-writes           Enable write operations--enabled-tools <regex>  Filter tools by regex pattern--preset <names>         Use preset categories (comma-separated)--partition <name>       Tool partition served on /mcp/<group> in HTTP mode (default: domains)--list-presets           List available presets and exit--list-tools             List available tools and exit--list-permissions       List required Graph API permissions and exit--verify-login           Test credentials against Graph API and exit--cloud <type>           Cloud environment: global (default) or china--transport <type>       Transport: stdio (default) or http--port <number>          HTTP port (default: 8080)--host <address>         HTTP bind address (default: 127.0.0.1)--allowed-clients <ids>  Comma-separated Entra app IDs (required for HTTP)-v                       Verbose logging

Presets

# Security alerts and incidents onlynode dist/index.js --preset security
# Identity management toolsnode dist/index.js --preset identity
# Multiple presetsnode dist/index.js --preset security,audit,identity

Verify credentials

node dist/index.js --verify-login

Available tools (674)

Security (11)

Audit logs & deleted items (5)

Service health (3)

Usage reports (8)

Users (9)

There is no general-purpose update-user. The only PATCH on /users/{id} this server exposes is disable-user-account (see Incident response), which is deliberately narrow: it sets accountEnabled and nothing else.

Devices (2)

Groups (11)

remove-group-member, add-group-owner and remove-group-owner run pre-flight guardrails: they refuse on an on-premises-synced group, a member removal on a dynamic group, and the removal of a group's only owner. See docs/ARCHITECTURE.md.

Directory roles & PIM (9)

delete-role-assignment is the one to reach for: list-role-assignments with $filter=principalId eq '{user-id}' already returns the assignment id it takes. remove-directory-role-member covers roles activated the legacy way. Both refuse unconditionally on the tenant's last active Global Administrator — an anti-lockout guardrail no parameter overrides.

Administrative units (8)

Conditional access (3)

Applications & app roles (11)

delete-oauth2-grant is the remediation for an illicit consent grant: list-oauth2-grants identifies it, this revokes it. A grant with consentType: AllPrincipals revokes the app's delegated access for every user at once — check the blast radius first, and pair with revoke-user-sessions, since revoking consent does not end existing sessions.

App credentials & owners (7)

App management policies (2)

Organization & domains (4)

Licenses (2)

Secure Score (4)

Identity Protection & risk detections (7)

Security & access policies (13)

Guest user invitations (2)

External identity providers (2)

Self-service sign-up (4)

Custom authentication extensions (2)

Exchange message traces (2)

Exchange mailboxes (7)

Threat intelligence - hosts (4)

Threat intelligence - articles & profiles (6)

Threat intelligence - vulnerabilities & WHOIS (4)

Threat intelligence - infrastructure (2)

Managed devices (8)

Compliance policies (5)

Device configurations (4)

Settings catalog & Endpoint security (6)

Settings catalog policies, including every modern Endpoint security policy (Disk encryption / BitLocker, Antivirus, Firewall, Attack surface reduction, EDR, Account protection). Targets Graph beta — configurationPolicies has no v1.0 equivalent. The two report actions are POSTs that only read; they need --allow-writes like the other Intune reports.

Endpoint security intents (legacy templates) (4)

Template-based Endpoint security policies created before the move to the Settings catalog. Targets Graph beta. An Endpoint security audit must cover these and the Settings catalog both.

Device encryption (1)

Intune encryption report: readiness, state, TPM version and the BitLocker / FileVault policies that reached each device. Targets Graph beta.

Windows Update profiles (3)

Feature and quality update profiles, which override the deferrals of a device's Windows Update for Business ring (rings themselves are device configurations). Targets Graph beta.

macOS Platform Scripts (6)

Intune shell scripts deployed to managed macOS devices. Targets Graph beta (/beta/deviceManagement/deviceShellScripts) — Microsoft has never promoted this endpoint to v1.0. Requires DeviceManagementScripts.ReadWrite.All.

Notes:

• scriptContent is strict base64 (not URL-safe) of a script with LF line endings — CRLF will break execution on Macs.
• runAsAccount=user is required for scripts that interact with the user session (e.g. osascript touching System Events).
• assign-device-shell-script REPLACES all existing assignments — it is not additive. To add a group without removing others, first GET the current assignments, append the new target, then POST the full merged list.
• By default get-device-shell-script does not return scriptContent; pass $select=id,displayName,scriptContent,... to fetch the base64 body.

Intune Remediations / Proactive Remediations (8)

Paired detection + remediation PowerShell scripts for Windows 10/11 Azure AD joined devices. Targets Graph beta (/beta/deviceManagement/deviceHealthScripts). Requires DeviceManagementScripts.ReadWrite.All.

Notes:

• Both detectionScriptContent and remediationScriptContent are base64-encoded PowerShell — UTF-8 encoded scripts before base64.
• Detection script returns exit code 0 (compliant) or 1 (needs remediation). The remediation script only runs when detection returns 1.
• assign-device-health-script REPLACES all existing assignments — schedules can be daily / hourly / run-once. Set runRemediationScript: false for detect-only deployments.
• By default get-device-health-script does not return the script bodies; pass $select=id,displayName,detectionScriptContent,remediationScriptContent,....
• Modern replacement for deviceShellScripts for Windows "verify + fix" use cases (CIS hardening, agent install verification, service state).

Assignment filters (5)

Dynamic membership filters that scope policy/app assignments to a sub-set of an Entra group. Targets Graph beta (/beta/deviceManagement/assignmentFilters). Requires DeviceManagementConfiguration.ReadWrite.All.

Notes:

• Rule syntax is KQL-like on device properties — example: (device.osVersion -startsWith "14") for macOS Sonoma only, (device.deviceOwnership -eq "Corporate") for corporate-owned devices.
• Operators: -eq, -ne, -startsWith, -contains, -in, -matches, joined by -and / -or.
• Filters are referenced by deviceConfigurations / mobileApps / deviceCompliancePolicies assignments (not by users — you target the assignment to a group, then add a filter to narrow it).
• assignmentFilterManagementType: devices for device-scoped assignments, apps for app-scoped (some properties differ).
• Deleting a filter that is in use will silently fall the dependent assignments back to "all members of the group" — audit assignments before deleting.

macOS custom attribute shell scripts (6)

Intune shell scripts whose STDOUT is stored as a named custom attribute on each device — useful for surfacing inventory data (FileVault, Gatekeeper, encryption flags, custom markers) and driving dynamic group filters. Targets Graph beta (/beta/deviceManagement/deviceCustomAttributeShellScripts). Requires DeviceManagementScripts.ReadWrite.All.

Notes:

• The script's STDOUT becomes the value stored under customAttributeName on each device.
• customAttributeType controls how Intune parses STDOUT: integer, string, or dateTime (ISO 8601).
• scriptContent is strict base64 of a script with LF line endings — CRLF breaks execution on Macs.
• Changing customAttributeName or customAttributeType after deployment breaks downstream dynamic groups and assignment filters that reference the previous key — audit references first.
• Deleting a script does NOT clear previously-collected attribute values from device records.

Windows PowerShell scripts (deviceManagementScripts) (6)

One-shot PowerShell scripts deployed to managed Windows 10/11 devices. Runs once per device per assignment, retries on failure. For detect-and-fix patterns use deviceHealthScripts (Remediations) instead. Targets Graph beta (/beta/deviceManagement/deviceManagementScripts). Requires DeviceManagementScripts.ReadWrite.All.

Notes:

• scriptContent is base64-encoded UTF-8 PowerShell.
• Runs ONCE per device on the next Intune Management Extension sync after assignment — does NOT re-run after successful execution (use deviceHealthScripts for repeating patterns).
• Updating scriptContent does NOT re-run on devices that already succeeded; delete + recreate to force re-execution.
• enforceSignatureCheck=true requires code-signed scripts (recommended for prod).
• runAs32Bit=true forces 32-bit PowerShell on 64-bit Windows (rarely needed).

Windows custom compliance scripts (deviceComplianceScripts) (6)

PowerShell scripts that emit a JSON object on STDOUT evaluated against rules declared on an associated windows10CustomComplianceConfiguration policy — for organization-specific compliance signals beyond the built-in BitLocker / Defender / firewall checks. Targets Graph beta (/beta/deviceManagement/deviceComplianceScripts). Requires DeviceManagementScripts.ReadWrite.All.

Notes:

• detectionScriptContent must emit a JSON object on STDOUT (e.g. ConvertTo-Json -Compress @{BitLockerEnabled=$true;TpmReady=$true}).
• The script alone has no compliance effect — you must also author a windows10CustomComplianceConfiguration policy with matching rules.
• Changing the JSON keys without updating the linked policy's rules silently breaks compliance evaluation.
• Deleting a script in use causes referencing compliance policies to fail evaluation on next device check-in.
• Assignment shape reuses deviceHealthScriptAssignment (set runRemediationScript: false since compliance scripts have no remediation pairing).

Enrollment & Autopilot (10)

Detected apps (3)

Intune RBAC & config (7)

Intune connectors & updates (3)

Device categories (1)

Access reviews (5)

Entitlement management (7)

Lifecycle workflows (3)

PIM for Groups (2)

Terms of use (3)

App consent requests (3)

Incident response (17) -- requires --allow-writes

One deletion tool per authentication-method collection, since the ids are collection-scoped and not interchangeable. Run list-user-auth-methods first and match on @odata.type to pick the right tool and id. Graph refuses the deletion when the method is the user's only remaining MFA factor and MFA is required.

Intune device remote actions (18) -- requires --allow-writes

Conditional Access CRUD (7) -- requires --allow-writes

Intune policies CRUD (8) -- requires --allow-writes

Settings catalog & Endpoint security CRUD (4) -- requires --allow-writes

Targets Graph beta. Requires DeviceManagementConfiguration.ReadWrite.All. assign-configuration-policy replaces the whole assignment list.

Endpoint security intents CRUD (4) -- requires --allow-writes

Targets Graph beta. Requires DeviceManagementConfiguration.ReadWrite.All. assign-intent replaces the whole assignment list.

OneDrive / user drive (DSAR enumeration) (4)

Read-only traversal of a user's personal drive, for subject-access requests. Content bytes are not exposed; these return metadata and download URLs.

Purview DSPM (protection scopes) (2)

compute-protection-scopes is a POST but computes rather than mutates — hence the low tier. It still needs --allow-writes.

Teams online meeting attendance (4)

Attendance reporting for a specific user's meetings. App-only access requires an Application Access Policy on the tenant, granted per service principal with Set-CsApplicationAccessPolicy; without it Graph answers 403 regardless of the Graph permission.

Teams deleted chats (3)

Administrative recovery flow for a chat a user deleted. The retention window is Microsoft's, not configurable here.

Teams chat investigation reads (5)

Triage reads over a user's chats, on Chat.Read.All. For court-admissible production use the eDiscovery tools instead — these reads carry no chain of custody.

Teams call records (11)

Cloud PC / Windows 365 (10)

Universal Print (6)

Information Protection & Sensitivity Labels (7)

SharePoint administration (25)

Records Management (9)

Listing or reading retentionLabels themselves is not exposed: Microsoft Graph does not support it with application permissions. Use delegated access or Security & Compliance PowerShell for that. list-retention-events is under Security advanced.

Teams administration (33)

Intune reports (18) -- requires --allow-writes (POST endpoints)

Intune partners & infrastructure (10)

Intune app management (11)

Advanced policies (15)

Identity Governance+ (11)

PIM role management (6)

Identity Protection+ (1)

Security advanced (9)

Defender for Identity (24)

Full surface coverage of Microsoft Defender for Identity (DfI) administration via Graph: sensors, sensor candidates (auto-discovery), sensor migration to unified Defender XDR architecture, identity accounts (with break-glass invokeAction for AD on-prem / Okta), audit policy enforcement, and health alerts. Most endpoints are Graph v1.0; sensorMigration is beta-only.

Notes:

• invoke-identity-account-action is the highest-impact write — performs identity-response actions (disable, enable, forcePasswordReset, revokeAllSessions, requireUserToSignInAgain, markUserAsCompromised) on accounts in their source system (AD on-prem, Okta). Action / provider compatibility: disable/enable for AD + Okta, forcePasswordReset for AD only, revokeAllSessions for Okta only.
• regenerate-sensor-deployment-access-key invalidates the previous key immediately — coordinate with anyone rolling out new sensors before calling.
• migrate-sensors restarts the sensor service on the target DC during migration to unified Defender XDR — brief capture gap (~minutes). Schedule maintenance windows for production DCs. Beta-only.
• activate-sensor-candidates triggers sensor installation on detected hosts using the deployment access key flow. Verify with get-sensor-candidate first — wrong serverId installs on the wrong host.
• update-auto-auditing-config with enabled=true makes DfI enforce the recommended Windows advanced audit policies on every sensor host (revert local admin overrides on next heartbeat) — recommended for production.

New Graph permissions required since v0.10.0 / 0.11.1 (must be consented on the app registration):

• SecurityIdentitiesSensors.Read.All + SecurityIdentitiesSensors.ReadWrite.All (sensors mgmt)
• SecurityIdentitiesAutoConfig.Read.All + SecurityIdentitiesAutoConfig.ReadWrite.All (autoAuditingConfiguration)
• SecurityIdentitiesAccount.Read.All (identityAccounts list/get)
• SecurityIdentitiesActions.ReadWrite.All (identityAccounts invokeAction — break-glass)
• SecurityIdentitiesMigration.Read.All + SecurityIdentitiesMigration.ReadWrite.All (sensorMigration, beta)

Threat intelligence+ (6)

Reports+ (5)

Copilot admin (15)

Settings and policy:

Usage reports:

Interaction history audit, AI users and meeting insights:

Agent registrations:

get-all-copilot-interactions returns every enterprise Copilot interaction in the tenant — prompts and responses. Treat the output as regulated personal data.

Directory+ (5)

Application credentials & owners CRUD (11) -- requires --allow-writes

Service Principals CRUD & credentials (10) -- requires --allow-writes

PIM activation & requests (10) -- requires --allow-writes

Entitlement Management CRUD (12) -- requires --allow-writes

Lifecycle Workflows CRUD & execution (8) -- requires --allow-writes

Access Reviews CRUD & actions (8) -- requires --allow-writes

eDiscovery (Purview) (33) -- writes require --allow-writes

Cases and searches:

Custodians:

Non-custodial data sources:

Review sets, queries and exports:

Operations:

export-review-set is the court-admissible production path. Its exportOptions / exportStructure fields are Graph flagged enums and must be sent as comma-separated strings, not objects.

Azure AD permissions

Read-only (default)

AccessReview.Read.AllAdministrativeUnit.Read.AllAgentRegistration.Read.AllAgreement.Read.AllAiEnterpriseInteraction.Read.AllAPIConnectors.Read.AllAppCatalog.Read.AllApplication.Read.AllAppRoleAssignment.Read.AllAttackSimulation.Read.AllAuditLog.Read.AllBitlockerKey.Read.AllCallRecords.Read.AllChat.ManageDeletion.AllChannel.ReadBasic.AllChat.Read.AllChatMember.Read.AllChatMessage.Read.AllCloudPC.Read.AllConsentRequest.Read.AllCopilotPolicySettings.ReadCopilotSettings-Internal.ReadWrite.AllCustomAuthenticationExtension.Read.AllCustomSecAttributeDefinition.Read.AllDevice.Read.AllDeviceLocalCredential.Read.AllDeviceManagementApps.Read.AllDeviceManagementConfiguration.Read.AllDeviceManagementManagedDevices.Read.AllDeviceManagementRBAC.Read.AllDeviceManagementServiceConfig.Read.AllDirectory.Read.AllDomain.Read.AlleDiscovery.Read.AllEntitlementManagement.Read.AllExchange.ManageAsAppGroup.Read.AllGroupMember.Read.AllIdentityProvider.Read.AllIdentityRiskEvent.Read.AllIdentityRiskyServicePrincipal.Read.AllIdentityRiskyUser.Read.AllIdentityUserFlow.Read.AllInformationProtectionPolicy.Read.AllLifecycleWorkflows.Read.AllMailboxSettings.ReadOnlineMeetingArtifact.Read.AllOnlineMeetings.Read.AllOnPremDirectorySynchronization.Read.AllOrganization.Read.AllPolicy.Read.AllPrinter.Read.AllProtectionScopes.Compute.AllPrintConnector.Read.AllPrintJob.Read.AllPrivilegedAccess.Read.AzureADGroupRecordsManagement.Read.AllReports.Read.AllRoleAssignmentSchedule.Read.DirectoryRoleEligibilitySchedule.Read.DirectoryRoleManagement.Read.DirectoryRoleManagementPolicy.Read.DirectorySecurityAlert.Read.AllSecurityEvents.Read.AllSecurityIdentitiesAccount.Read.AllSecurityIdentitiesAutoConfig.Read.AllSecurityIdentitiesHealth.Read.AllSecurityIdentitiesMigration.Read.AllSecurityIdentitiesSensors.Read.AllSecurityIncident.Read.AllServiceHealth.Read.AllServiceMessage.Read.AllSharePointTenantSettings.Read.AllSites.Read.AllSites.FullControl.AllSubjectRightsRequest.Read.AllTeam.ReadBasic.AllTeamMember.Read.AllTeamsAppInstallation.ReadForTeam.AllTeamsTelephoneNumber.Read.AllTeamsUserConfiguration.Read.AllTeamworkAppSettings.Read.AllTeamworkDevice.Read.AllThreatAssessment.Read.AllThreatHunting.Read.AllThreatIntelligence.Read.AllUser.Invite.AllUser.Read.AllUserAuthenticationMethod.Read.All

Write (incident response, device actions, CA policies, Teams, SharePoint, identity management)

AccessReview.ReadWrite.AllAdministrativeUnit.ReadWrite.AllApplication.ReadWrite.AllApplication.ReadWrite.OwnedByAppRoleAssignment.ReadWrite.AllAttackSimulation.ReadWrite.AllChannel.CreateChannel.Delete.AllCloudPC.ReadWrite.AllDevice.ReadWrite.AllDeviceManagementConfiguration.ReadWrite.AllDeviceManagementManagedDevices.PrivilegedOperations.AllDeviceManagementManagedDevices.ReadWrite.AllDeviceManagementServiceConfig.ReadWrite.AllDirectory.AccessAsUser.AllDomain.ReadWrite.AlleDiscovery.ReadWrite.AllEntitlementManagement.ReadWrite.AllGroup.ReadWrite.AllGroupMember.ReadWrite.AllIdentityRiskyServicePrincipal.ReadWrite.AllIdentityRiskyUser.ReadWrite.AllLifecycleWorkflows.ReadWrite.AllPolicy.ReadWrite.AuthenticationMethodPolicy.ReadWrite.ConditionalAccessPrivilegedAccess.ReadWrite.AzureADGroupRecordsManagement.ReadWrite.AllRoleAssignmentSchedule.ReadWrite.DirectoryRoleEligibilitySchedule.ReadWrite.DirectoryRoleManagement.ReadWrite.DirectoryRoleManagementPolicy.ReadWrite.DirectorySecurityAlert.ReadWrite.AllSecurityIdentitiesActions.ReadWrite.AllSecurityIdentitiesAutoConfig.ReadWrite.AllSecurityIdentitiesMigration.ReadWrite.AllSecurityIdentitiesSensors.ReadWrite.AllSecurityIncident.ReadWrite.AllSites.ReadWrite.AllTeam.CreateTeam.ReadWrite.AllTeamMember.ReadWrite.AllTeamsTelephoneNumber.ReadWrite.AllTeamworkAppSettings.ReadWrite.AllUser.ReadWrite.AllUserAuthenticationMethod.ReadWrite.All

Remote HTTP deployment

Local HTTP mode

node dist/index.js \  --transport http \  --port 8080 \  --allowed-clients "app-id-1,app-id-2"

The --allowed-clients flag is mandatory in HTTP mode. It validates incoming bearer tokens against Microsoft's JWKS endpoint (signature verification, audience, tenant, and client ID checks).

Docker

docker build -t ms365-admin-mcp .docker run -p 8080:8080 \  -e MS365_ADMIN_MCP_CLIENT_ID=... \  -e MS365_ADMIN_MCP_CLIENT_SECRET=... \  -e MS365_ADMIN_MCP_TENANT_ID=... \  ms365-admin-mcp --allowed-clients "your-app-id"

Azure Container Apps

A Bicep template is provided in infra/main.bicep. It deploys:

• User-Assigned Managed Identity (UAMI)
• Key Vault (RBAC, purge protection, 90-day soft-delete)
• Log Analytics workspace + Application Insights
• Container App Environment
• Container App using the UAMI, with MS365_ADMIN_MCP_KEYVAULT_URL wired to the vault

MY_OID=$(az ad signed-in-user show --query id -o tsv)
az deployment group create \  --resource-group rg-mcp-admin \  --template-file infra/main.bicep \  --parameters baseName=ms365mcpprod \               containerImage=your-acr.azurecr.io/ms365-admin-mcp:latest \               kvAdminObjectIds="['$MY_OID']"

Seed the vault with ms365-admin-mcp-{client-id,tenant-id,client-secret} after deploy — see docs/HTTP_DEPLOYMENT.md.

Development

npm run dev              # Run with tsx (hot reload)npm run generate         # Download OpenAPI spec + generate clientnpm run build            # Build with tsupnpm run test             # Run vitestnpm run lint             # ESLintnpm run format           # Prettiernpm run verify           # Full pipeline (generate + lint + format + build + test)npm run inspector        # MCP Inspector for interactive testing

Adding a new tool

1. Add the endpoint entry in src/endpoints.json, with its section (the README inventory section its row goes under) and, for a write, its riskLevel. If that section is new, place it in every table of src/tool-partitions.ts
2. Run npm run generate to regenerate the client
3. The tool is automatically registered at startup by registerGraphTools()
4. Run npm run verify to validate

Security

• Read-only by default -- mutations require --allow-writes
• Risk levels on write tools (critical/high/medium/low) with LLM-visible warnings
• JWT signature verification via Microsoft JWKS (RS256) in HTTP mode
• Mandatory authentication in HTTP mode (--allowed-clients required)
• Rate limiting (100 req/min) on the MCP endpoint
• Security headers (nosniff, DENY, no-store, CSP)
• Non-root Docker user
• Sensitive data redacted from logs

Acknowledgments

This project would not exist without Softeria/ms-365-mcp-server. Their work served as the foundation and inspiration for this server — in particular:

• The endpoint-driven architecture (endpoints.json + auto-registration via graph-tools.ts)
• The OpenAPI-based code generation pipeline (npm run generate → trimmed Graph spec + Zodios client)
• The CLI ergonomics (presets, --list-tools, --list-permissions, --verify-login, MCP Inspector integration)
• The read-only-by-default + --allow-writes safety model

This server diverges from Softeria's by targeting application permissions (client credentials via MSAL ConfidentialClientApplication) rather than delegated permissions, and by adding admin-specific capabilities — risk classification on write tools, JWT validation via Microsoft JWKS for HTTP mode, Azure Key Vault integration, and incident-response tooling.

Sincere thanks to the Softeria team and contributors for making their work available under an open license, and for setting a high bar for MCP server design in the Microsoft 365 ecosystem.

License

MIT — see LICENSE.