ms-365-admin-mcp-server

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

• 515 tools covering security, audit, identity, app credentials, guest users, Exchange, Intune (devices, apps, MAM, reports), governance (PIM, access reviews, entitlement, lifecycle), compliance, threat intelligence, advanced hunting, Defender for Identity, Copilot admin, custom security attributes, LAPS, policies, reports, incident response, eDiscovery, 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

Document	Purpose
docs/USE_CASES.md	15 typical admin scenarios with sample prompts and tool lists
docs/playbooks/	End-to-end security incident response playbooks
docs/APP_REGISTRATION.md	Step-by-step Azure AD app registration and permission consent
docs/HTTP_DEPLOYMENT.md	HTTP transport, JWT validation, Docker, Azure Container Apps
docs/AZURE_DEPLOYMENT_SECURITY.md	Threat model, required controls, and checklist for Azure production deploys
docs/TROUBLESHOOTING.md	Common errors and how to diagnose them
docs/ARCHITECTURE.md	Internal architecture and code generation pipeline
docs/RISK_MODEL.md	Risk classification rubric for write tools
CONTRIBUTING.md	How to contribute new tools, presets, and fixes
SECURITY.md	Vulnerability reporting and operator hardening checklist
CHANGELOG.md	Release history

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-server
ms-365-admin-mcp-server --help

Docker

docker pull ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest
docker 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.git
cd ms-365-admin-mcp-server
npm install
npm run generate
npm run build

Configuration

Environment variables

Variable	Required	Description
MS365_ADMIN_MCP_CLIENT_ID	Yes	App registration client ID
MS365_ADMIN_MCP_CLIENT_SECRET	Yes	App registration client secret
MS365_ADMIN_MCP_TENANT_ID	Yes	Azure AD tenant ID (must be specific)
MS365_ADMIN_MCP_CLOUD_TYPE	No	global (default) or china
MS365_ADMIN_MCP_KEYVAULT_URL	No	Azure Key Vault URL (overrides env vars)
MS365_ADMIN_MCP_MAX_TOP	No	Cap $top query param to limit result size
READ_ONLY	No	true/1 to force read-only (default behavior)
ENABLED_TOOLS	No	Regex to filter available tools

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"
      }
    }
  }
}

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 @okapi-ca/ms-365-admin-mcp-server@latest 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)
--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 only
node dist/index.js --preset security

# Identity management tools
node dist/index.js --preset identity

# Multiple presets
node dist/index.js --preset security,audit,identity

Preset	Description
security	Security alerts, incidents, attack simulations, and threat intelligence
audit	Directory audits, sign-ins, provisioning logs, deleted items
health	Service health and Message Center
reports	Usage reports (Teams, Email, SharePoint, OneDrive, Mailbox, M365 Apps)
identity	Users, groups, roles, devices, PIM, guest users, external identities
exchange	Exchange administration (message traces, mailboxes)
intune	Managed devices, compliance, configurations, Autopilot, apps, RBAC
governance	Access reviews, entitlement management, lifecycle workflows, terms of use
compliance	Licenses, Secure Score, Identity Protection, risk detections, policies
response	Incident response write operations (disable, revoke, confirm, dismiss)
ediscovery	eDiscovery cases (Microsoft Purview)
cloudpc	Cloud PC / Windows 365 (provisioning, images, connections, settings, audit)
callrecords	Teams call records
print	Universal Print (printers, shares, connectors, services, operations, tasks)
infoprotection	Information Protection (BitLocker recovery keys, threat assessment)
sharepointadmin	SharePoint tenant administration settings
retention	Records Management (retention labels, file plan metadata)
all	All available tools

Verify credentials

node dist/index.js --verify-login

Available tools (515)

Security (11)

Tool	Method	Risk
list-security-alerts	GET
get-security-alert	GET
update-security-alert	PATCH	medium
list-security-incidents	GET
get-security-incident	GET
update-security-incident	PATCH	medium
list-attack-simulations	GET
get-attack-simulation	GET
create-attack-simulation	POST	high
update-attack-simulation	PATCH	medium
delete-attack-simulation	DELETE	medium

Audit logs & deleted items (5)

Tool	Method
list-directory-audits	GET
list-sign-ins	GET
list-provisioning-logs	GET
list-deleted-users	GET
list-deleted-groups	GET

Service health (3)

Tool	Method
list-service-health	GET
list-service-issues	GET
list-service-messages	GET

Usage reports (8)

Tool	Method
get-teams-activity-report	GET
get-email-activity-report	GET
get-active-users-report	GET
get-sharepoint-usage-report	GET
get-onedrive-usage-report	GET
get-active-user-counts-report	GET
get-mailbox-usage-report	GET
get-m365-apps-usage-report	GET

Users (10)

Tool	Method	Risk
list-users	GET
get-user	GET
list-user-memberships	GET
list-user-auth-methods	GET
list-user-devices	GET
create-user	POST	high
update-user	PATCH	medium
delete-user	DELETE	critical
assign-user-license	POST	medium
reprocess-user-license	POST	low

Devices (2)

Tool	Method
list-devices	GET
get-device	GET

Groups (8)

Tool	Method	Risk
list-groups	GET
get-group	GET
list-group-members	GET
list-group-owners	GET
create-group	POST	medium
update-group	PATCH	medium
delete-group	DELETE	critical
add-group-member	POST	medium

Directory roles & PIM (7)

Tool	Method	Risk
list-directory-roles	GET
list-role-members	GET
list-role-assignments	GET
list-role-definitions	GET
list-pim-eligible-assignments	GET
list-pim-active-assignments	GET
add-directory-role-member	POST	critical

Administrative units (7)

Tool	Method	Risk
list-administrative-units	GET
get-administrative-unit	GET
list-administrative-unit-members	GET
create-administrative-unit	POST	medium
update-administrative-unit	PATCH	medium
delete-administrative-unit	DELETE	high
add-administrative-unit-member	POST	medium

Conditional access (3)

Tool	Method
list-conditional-access-policies	GET
get-conditional-access-policy	GET
list-named-locations	GET

Applications & app roles (8)

Tool	Method	Risk
list-applications	GET
list-service-principals	GET
list-oauth2-grants	GET
list-user-app-role-assignments	GET
list-sp-app-role-assignments	GET
update-application	PATCH	high
delete-application	DELETE	critical
update-service-principal	PATCH	high

App credentials & owners (7)

Tool	Method
get-application	GET
list-application-owners	GET
list-app-federated-credentials	GET
get-app-federated-credential	GET
get-service-principal	GET
list-service-principal-owners	GET
list-sp-delegated-permissions	GET

App management policies (2)

Tool	Method
list-app-management-policies	GET
get-app-management-policy	GET

Organization & domains (4)

Tool	Method	Risk
get-organization	GET
list-domains	GET
create-domain	POST	high
verify-domain	POST	medium

Licenses (2)

Tool	Method
list-subscribed-skus	GET
get-subscribed-sku	GET

Secure Score (4)

Tool	Method
list-secure-scores	GET
get-secure-score	GET
list-secure-score-controls	GET
get-secure-score-control	GET

Identity Protection & risk detections (7)

Tool	Method
list-risky-users	GET
get-risky-user	GET
list-risky-user-history	GET
list-risky-service-principals	GET
get-risky-service-principal	GET
list-risk-detections	GET
get-risk-detection	GET

Security & access policies (13)

Tool	Method	Risk
get-auth-methods-policy	GET
list-auth-method-configs	GET
get-auth-method-config	GET
get-security-defaults	GET
get-admin-consent-policy	GET
list-auth-strength-policies	GET
get-auth-strength-policy	GET
create-auth-strength-policy	POST	high
update-auth-strength-policy	PATCH	high
delete-auth-strength-policy	DELETE	high
get-cross-tenant-access-policy	GET
list-cross-tenant-partners	GET
change-user-password	POST	high

Guest user invitations (2)

Tool	Method	Risk
list-invitations	GET
create-invitation	POST	medium

External identity providers (2)

Tool	Method
list-identity-providers	GET
get-identity-provider	GET

Self-service sign-up (4)

Tool	Method
list-b2x-user-flows	GET
get-b2x-user-flow	GET
list-api-connectors	GET
get-api-connector	GET

Custom authentication extensions (2)

Tool	Method
list-custom-auth-extensions	GET
get-custom-auth-extension	GET

Exchange message traces (2)

Tool	Method
list-message-traces	GET
get-message-trace	GET

Exchange mailboxes (7)

Tool	Method	Risk
list-exchange-mailboxes	GET
get-exchange-mailbox	GET
list-exchange-mailbox-folders	GET
get-exchange-mailbox-folder	GET
export-exchange-mailbox-items	POST	medium
update-exchange-mailbox	PATCH	medium
delete-exchange-mailbox	DELETE	critical

Threat intelligence - hosts (4)

Tool	Method
list-threat-intel-hosts	GET
get-threat-intel-host	GET
get-threat-intel-host-whois	GET
list-threat-intel-host-pairs	GET

Threat intelligence - articles & profiles (6)

Tool	Method
list-threat-intel-articles	GET
get-threat-intel-article	GET
list-threat-intel-article-indicators	GET
list-threat-intel-profiles	GET
get-threat-intel-profile	GET
list-threat-intel-profile-indicators	GET

Threat intelligence - vulnerabilities & WHOIS (4)

Tool	Method
list-threat-intel-vulnerabilities	GET
get-threat-intel-vulnerability	GET
list-threat-intel-whois-records	GET
get-threat-intel-whois-record	GET

Threat intelligence - infrastructure (2)

Tool	Method
list-threat-intel-host-components	GET
list-threat-intel-ssl-certs	GET

Managed devices (6)

Tool	Method	Risk
list-managed-devices	GET
get-managed-device	GET
list-device-compliance-states	GET
list-device-configuration-states	GET
get-managed-device-overview	GET
delete-managed-device	DELETE	critical

Compliance policies (5)

Tool	Method
list-compliance-policies	GET
get-compliance-policy	GET
list-compliance-policy-device-statuses	GET
get-compliance-policy-status-overview	GET
get-compliance-state-summary	GET

Device configurations (3)

Tool	Method
list-device-configurations	GET
get-device-configuration	GET
get-device-configuration-status-overview	GET

Enrollment & Autopilot (10)

Tool	Method	Risk
list-enrollment-configurations	GET
get-enrollment-configuration	GET
list-autopilot-devices	GET
get-autopilot-device	GET
create-enrollment-configuration	POST	medium
update-enrollment-configuration	PATCH	medium
delete-enrollment-configuration	DELETE	high
update-autopilot-device	PATCH	medium
delete-autopilot-device	DELETE	high
import-autopilot-device	POST	medium

Detected apps (3)

Tool	Method
list-detected-apps	GET
get-detected-app	GET
list-detected-app-devices	GET

Intune RBAC & config (7)

Tool	Method
list-intune-audit-events	GET
get-software-update-summary	GET
get-apple-push-certificate	GET
list-intune-role-definitions	GET
list-intune-role-assignments	GET
list-intune-terms-and-conditions	GET
list-intune-terms-acceptances	GET

Intune connectors & updates (3)

Tool	Method
get-intune-conditional-access-settings	GET
list-mtd-connectors	GET
list-ios-update-statuses	GET

Device categories (1)

Tool	Method
list-device-categories	GET

Access reviews (5)

Tool	Method
list-access-review-definitions	GET
get-access-review-definition	GET
list-access-review-instances	GET
get-access-review-instance	GET
list-access-review-decisions	GET

Entitlement management (7)

Tool	Method
list-access-packages	GET
get-access-package	GET
list-access-package-assignments	GET
list-access-package-requests	GET
list-access-package-catalogs	GET
list-connected-organizations	GET
get-entitlement-management-settings	GET

Lifecycle workflows (3)

Tool	Method
list-lifecycle-workflows	GET
get-lifecycle-workflow	GET
list-lifecycle-task-definitions	GET

PIM for Groups (2)

Tool	Method
list-pim-group-assignment-schedules	GET
list-pim-group-eligibility-schedules	GET

Terms of use (3)

Tool	Method
list-terms-of-use-agreements	GET
get-terms-of-use-agreement	GET
list-terms-of-use-acceptances	GET

App consent requests (3)

Tool	Method
list-app-consent-requests	GET
get-app-consent-request	GET
list-user-consent-requests	GET

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

Tool	Method	Risk
disable-user-account	PATCH	critical
revoke-user-sessions	POST	high
add-security-alert-comment	POST	low
update-device	PATCH	high
confirm-compromised-users	POST	high
dismiss-risky-users	POST	high
delete-user-phone-auth-method	DELETE	high
confirm-compromised-service-principals	POST	high
dismiss-risky-service-principals	POST	high
confirm-safe-users	POST	high
run-hunting-query	POST	low

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

Tool	Method	Risk
wipe-managed-device	POST	critical
retire-managed-device	POST	high
sync-managed-device	POST	low
reboot-managed-device	POST	high
remote-lock-device	POST	medium
reset-device-passcode	POST	high
shutdown-managed-device	POST	high
disable-lost-mode	POST	low
locate-managed-device	POST	low
bypass-activation-lock	POST	high
trigger-defender-scan	POST	low
update-defender-signatures	POST	low
clean-windows-device	POST	critical
logout-shared-apple-user	POST	medium
delete-shared-apple-user	POST	high
update-windows-device-account	POST	medium

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

Tool	Method	Risk
list-conditional-access-templates	GET
get-conditional-access-policy	GET
create-conditional-access-policy	POST	high
update-conditional-access-policy	PATCH	high
delete-conditional-access-policy	DELETE	critical
create-named-location	POST	medium
update-named-location	PATCH	medium
delete-named-location	DELETE	high

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

Tool	Method	Risk
create-compliance-policy	POST	medium
update-compliance-policy	PATCH	medium
delete-compliance-policy	DELETE	high
create-device-configuration	POST	medium
update-device-configuration	PATCH	medium
delete-device-configuration	DELETE	high

eDiscovery (1)

Tool	Method	Risk
list-ediscovery-cases	GET

Teams call records (11)

Tool	Method
list-call-records	GET
get-call-record	GET
list-call-record-sessions	GET
get-call-record-session	GET
list-call-session-segments	GET
get-call-session-segment	GET
list-call-record-participants	GET
get-call-record-participant	GET
get-call-record-organizer	GET
get-pstn-calls	GET
get-direct-routing-calls	GET

Cloud PC / Windows 365 (10)

Tool	Method	Risk
list-cloud-pcs	GET
list-cloud-pc-provisioning-policies	GET
list-cloud-pc-device-images	GET
list-cloud-pc-gallery-images	GET
list-cloud-pc-on-premises-connections	GET
list-cloud-pc-user-settings	GET
list-cloud-pc-audit-events	GET
create-cloud-pc-provisioning-policy	POST	medium
update-cloud-pc-provisioning-policy	PATCH	medium
delete-cloud-pc-provisioning-policy	DELETE	high

Universal Print (6)

Tool	Method	Risk
list-printers	GET
list-print-shares	GET
list-print-connectors	GET
list-print-services	GET
list-print-operations	GET
list-print-task-definitions	GET

Information Protection & Sensitivity Labels (7)

Tool	Method
list-bitlocker-recovery-keys	GET
list-threat-assessment-requests	GET
list-sensitivity-labels	GET
get-sensitivity-label	GET
list-sensitivity-sublabels	GET
get-sensitivity-label-rights	GET
get-protection-scopes	GET

SharePoint administration (25)

Tool	Method	Risk
get-sharepoint-settings	GET
list-sharepoint-sites	GET
get-sharepoint-site	GET
update-sharepoint-site	PATCH	medium
list-site-drives	GET
get-site-default-drive	GET
list-site-lists	GET
get-site-list	GET
create-site-list	POST	low
update-site-list	PATCH	low
delete-site-list	DELETE	high
list-site-list-items	GET
create-site-list-item	POST	low
update-site-list-item	PATCH	low
delete-site-list-item	DELETE	medium
list-site-list-columns	GET
list-site-columns	GET
list-site-content-types	GET
list-site-permissions	GET
get-site-permission	GET
create-site-permission	POST	medium
update-site-permission	PATCH	medium
delete-site-permission	DELETE	high
get-site-analytics	GET
list-site-subsites	GET

Records Management (6)

Tool	Method	Risk
list-retention-labels	GET
list-file-plan-authorities	GET
list-file-plan-categories	GET
list-file-plan-citations	GET
list-file-plan-departments	GET
list-file-plan-references	GET

Teams administration (30)

Tool	Method	Risk
list-teams	GET
create-team	POST	medium
get-team	GET
update-team	PATCH	medium
delete-team	DELETE	critical
list-team-admin-channels	GET
create-team-admin-channel	POST	low
get-team-admin-channel	GET
delete-team-admin-channel	DELETE	high
list-team-admin-members	GET
add-team-admin-members	POST	medium
remove-team-admin-members	POST	medium
get-team-admin-member	GET
list-team-installed-apps	GET
archive-team	POST	medium
unarchive-team	POST	low
clone-team	POST	medium
list-team-operations	GET
list-team-permission-grants	GET
get-teams-app-settings	GET
update-teams-app-settings	PATCH	high
list-deleted-teams	GET
list-teams-catalog-apps	GET
get-teams-catalog-app	GET
list-teams-app-definitions	GET
get-teams-admin-settings	GET
list-teams-user-configurations	GET
get-teams-admin-policy	GET
list-teams-policy-assignments	GET
list-teams-phone-assignments	GET

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

Tool	Method	Risk
intune-device-noncompliance-report	POST	low
intune-compliance-policy-noncompliance-report	POST	low
intune-compliance-policy-noncompliance-summary	POST	low
intune-compliance-setting-noncompliance-report	POST	low
intune-config-policy-noncompliance-report	POST	low
intune-config-policy-noncompliance-summary	POST	low
intune-config-setting-noncompliance-report	POST	low
intune-devices-without-compliance-report	POST	low
intune-noncompliant-devices-settings-report	POST	low
intune-policy-noncompliance-report	POST	low
intune-policy-noncompliance-summary	POST	low
intune-policy-noncompliance-metadata	POST	low
intune-setting-noncompliance-report	POST	low
intune-report-filters	POST	low
intune-historical-report	POST	low
intune-cached-report	POST	low
list-intune-report-export-jobs	GET
intune-device-app-install-status-report	POST	low

Intune partners & infrastructure (10)

Tool	Method	Risk
list-compliance-management-partners	GET
list-device-management-partners	GET
list-exchange-connectors	GET
list-remote-assistance-partners	GET
list-notification-message-templates	GET
list-intune-resource-operations	GET
list-imported-autopilot-devices	GET
list-windows-malware-info	GET
list-intune-mobile-apps	GET
list-intune-app-categories	GET

Intune app management (11)

Tool	Method	Risk
list-intune-app-configurations	GET
list-managed-app-policies	GET
list-managed-app-registrations	GET
list-managed-app-statuses	GET
list-android-app-protections	GET
list-ios-app-protections	GET
list-default-app-protections	GET
list-targeted-app-configurations	GET
list-mdm-wip-policies	GET
list-mam-wip-policies	GET
list-vpp-tokens	GET

Advanced policies (15)

Tool	Method	Risk
list-activity-timeout-policies	GET
get-authorization-policy	GET
get-auth-flows-policy	GET
list-claims-mapping-policies	GET
list-conditional-access-policies-v2	GET
get-default-app-management-policy	GET
get-device-registration-policy	GET
list-feature-rollout-policies	GET
list-home-realm-discovery-policies	GET
list-permission-grant-policies	GET
list-role-management-policies	GET
list-role-management-policy-assignments	GET
list-token-issuance-policies	GET
list-token-lifetime-policies	GET
get-cross-tenant-default-policy	GET

Identity Governance+ (11)

Tool	Method	Risk
list-entitlement-assignment-policies	GET
list-entitlement-resources	GET
list-entitlement-resource-environments	GET
list-lifecycle-workflow-templates	GET
get-lifecycle-workflow-settings	GET
list-lifecycle-custom-task-extensions	GET
list-deleted-lifecycle-workflows	GET
list-pim-group-assignment-requests	GET
list-pim-group-assignment-instances	GET
list-pim-group-eligibility-requests	GET
list-pim-group-eligibility-instances	GET

PIM role management (6)

Tool	Method	Risk
list-access-review-history	GET
list-pim-role-assignment-requests	GET
list-pim-role-assignment-schedules	GET
list-pim-role-eligibility-requests	GET
list-pim-role-eligibility-schedules	GET
list-role-resource-namespaces	GET

Identity Protection+ (2)

Tool	Method	Risk
list-service-principal-risk-detections	GET

Security advanced (14)

Tool	Method	Risk
list-identity-health-issues	GET
list-identity-sensors	GET
get-identity-security-settings	GET
list-retention-events	GET
list-retention-event-types	GET
list-subject-rights-requests	GET
list-simulation-automations	GET
list-simulation-trainings	GET
list-simulation-payloads	GET
list-simulation-end-user-notifications	GET
list-simulation-landing-pages	GET
list-simulation-login-pages	GET

Threat intelligence+ (7)

Tool	Method	Risk
list-passive-dns-records	GET
list-ssl-certificates	GET
list-threat-intel-subdomains	GET
list-threat-intel-host-ports	GET
list-threat-intel-host-trackers	GET
list-threat-intel-host-cookies	GET
list-threat-intel-host-pairs	GET

Reports+ (5)

Tool	Method	Risk
list-user-registration-details	GET
list-daily-print-usage-by-printer	GET
list-daily-print-usage-by-user	GET
list-monthly-print-usage-by-printer	GET
list-monthly-print-usage-by-user	GET

Copilot admin (2)

Tool	Method	Risk
get-copilot-admin-settings	GET
get-copilot-limited-mode	GET

Directory+ (5)

Tool	Method	Risk
list-attribute-sets	GET
list-custom-security-attributes	GET
list-device-local-credentials	GET
list-federation-configurations	GET
list-on-premises-sync	GET

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

Tool	Method	Risk
create-application	POST	high
add-application-password	POST	high
remove-application-password	POST	high
add-application-key	POST	high
remove-application-key	POST	high
add-application-owner	POST	high
remove-application-owner	DELETE	high
create-app-federated-credential	POST	high
update-app-federated-credential	PATCH	high
delete-app-federated-credential	DELETE	high
set-application-verified-publisher	POST	medium

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

Tool	Method	Risk
create-service-principal	POST	high
delete-service-principal	DELETE	critical
add-sp-password	POST	high
remove-sp-password	POST	high
add-sp-key	POST	high
remove-sp-key	POST	high
add-sp-token-signing-certificate	POST	high
add-sp-owner	POST	high
remove-sp-owner	DELETE	high
create-sp-app-role-assignment	POST	high

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

Tool	Method	Risk
create-pim-role-assignment-request	POST	critical
cancel-pim-role-assignment-request	POST	high
create-pim-role-eligibility-request	POST	critical
cancel-pim-role-eligibility-request	POST	high
create-pim-group-assignment-request	POST	high
cancel-pim-group-assignment-request	POST	medium
create-pim-group-eligibility-request	POST	high
cancel-pim-group-eligibility-request	POST	medium
create-role-management-policy-assignment	POST	high
update-role-management-policy	PATCH	high

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

Tool	Method	Risk
create-access-package	POST	medium
update-access-package	PATCH	medium
delete-access-package	DELETE	high
create-access-package-catalog	POST	medium
update-access-package-catalog	PATCH	medium
delete-access-package-catalog	DELETE	high
create-access-package-assignment-policy	POST	medium
update-access-package-assignment-policy	PUT	medium
delete-access-package-assignment-policy	DELETE	high
create-access-package-assignment-request	POST	medium
reprocess-access-package-assignment-request	POST	low
cancel-access-package-assignment-request	POST	medium

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

Tool	Method	Risk
create-lifecycle-workflow	POST	medium
update-lifecycle-workflow	PATCH	medium
delete-lifecycle-workflow	DELETE	high
activate-lifecycle-workflow	POST	high
restore-lifecycle-workflow	POST	medium
create-lifecycle-custom-task-extension	POST	medium
update-lifecycle-custom-task-extension	PATCH	medium
delete-lifecycle-custom-task-extension	DELETE	high

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

Tool	Method	Risk
create-access-review-definition	POST	medium
update-access-review-definition	PUT	medium
delete-access-review-definition	DELETE	high
stop-access-review-instance	POST	high
send-reminder-access-review	POST	low
reset-access-review-decisions	POST	high
apply-access-review-decisions	POST	high
accept-access-review-recommendations	POST	medium

eDiscovery v2 (Purview) (12) -- writes require --allow-writes

Tool	Method	Risk
get-ediscovery-case	GET
create-ediscovery-case	POST	medium
update-ediscovery-case	PATCH	medium
delete-ediscovery-case	DELETE	critical
close-ediscovery-case	POST	medium
reopen-ediscovery-case	POST	medium
list-ediscovery-custodians	GET
create-ediscovery-custodian	POST	medium
apply-hold-ediscovery-custodian	POST	high
remove-hold-ediscovery-custodian	POST	high
list-ediscovery-searches	GET
create-ediscovery-search	POST	medium

Azure AD permissions

Read-only (default)

AccessReview.Read.All
AdministrativeUnit.Read.All
Agreement.Read.All
APIConnectors.Read.All
AppCatalog.Read.All
Application.Read.All
AppRoleAssignment.Read.All
AttackSimulation.Read.All
AuditLog.Read.All
BitlockerKey.Read.All
CallRecords.Read.All
Channel.ReadBasic.All
CloudPC.Read.All
ConsentRequest.Read.All
CopilotSettings-Internal.ReadWrite.All
CustomAuthenticationExtension.Read.All
CustomSecAttributeDefinition.Read.All
Device.Read.All
DeviceLocalCredential.Read.All
DeviceManagementApps.Read.All
DeviceManagementConfiguration.Read.All
DeviceManagementManagedDevices.Read.All
DeviceManagementRBAC.Read.All
DeviceManagementServiceConfig.Read.All
Directory.Read.All
Domain.Read.All
eDiscovery.Read.All
EntitlementManagement.Read.All
Exchange.ManageAsApp
Group.Read.All
GroupMember.Read.All
IdentityProvider.Read.All
IdentityRiskEvent.Read.All
IdentityRiskyServicePrincipal.Read.All
IdentityRiskyUser.Read.All
IdentityUserFlow.Read.All
InformationProtectionPolicy.Read.All
LifecycleWorkflows.Read.All
MailboxSettings.Read
OnPremDirectorySynchronization.Read.All
Organization.Read.All
Policy.Read.All
Printer.Read.All
PrintConnector.Read.All
PrintJob.Read.All
PrivilegedAccess.Read.AzureADGroup
RecordsManagement.Read.All
Reports.Read.All
RoleAssignmentSchedule.Read.Directory
RoleEligibilitySchedule.Read.Directory
RoleManagement.Read.Directory
RoleManagementPolicy.Read.Directory
SecurityAlert.Read.All
SecurityEvents.Read.All
SecurityIdentitiesHealth.Read.All
SecurityIncident.Read.All
ServiceHealth.Read.All
ServiceMessage.Read.All
SharePointTenantSettings.Read.All
Sites.Read.All
Sites.FullControl.All
SubjectRightsRequest.Read.All
Team.ReadBasic.All
TeamMember.Read.All
TeamsAppInstallation.ReadForTeam.All
TeamworkAppSettings.Read.All
TeamworkDevice.Read.All
ThreatAssessment.Read.All
ThreatHunting.Read.All
ThreatIntelligence.Read.All
User.Invite.All
User.Read.All
UserAuthenticationMethod.Read.All

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

AccessReview.ReadWrite.All
AdministrativeUnit.ReadWrite.All
Application.ReadWrite.All
Application.ReadWrite.OwnedBy
AppRoleAssignment.ReadWrite.All
AttackSimulation.ReadWrite.All
Channel.Create
Channel.Delete.All
CloudPC.ReadWrite.All
Device.ReadWrite.All
DeviceManagementConfiguration.ReadWrite.All
DeviceManagementManagedDevices.PrivilegedOperations.All
DeviceManagementManagedDevices.ReadWrite.All
DeviceManagementServiceConfig.ReadWrite.All
Directory.AccessAsUser.All
Domain.ReadWrite.All
eDiscovery.ReadWrite.All
EntitlementManagement.ReadWrite.All
Group.ReadWrite.All
GroupMember.ReadWrite.All
IdentityRiskyServicePrincipal.ReadWrite.All
IdentityRiskyUser.ReadWrite.All
LifecycleWorkflows.ReadWrite.All
Policy.ReadWrite.AuthenticationMethod
Policy.ReadWrite.ConditionalAccess
PrivilegedAccess.ReadWrite.AzureADGroup
RoleAssignmentSchedule.ReadWrite.Directory
RoleEligibilitySchedule.ReadWrite.Directory
RoleManagement.ReadWrite.Directory
RoleManagementPolicy.ReadWrite.Directory
SecurityAlert.ReadWrite.All
SecurityIncident.ReadWrite.All
Sites.ReadWrite.All
Team.Create
Team.ReadWrite.All
TeamMember.ReadWrite.All
TeamworkAppSettings.ReadWrite.All
User.ReadWrite.All
UserAuthenticationMethod.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 client
npm run build            # Build with tsup
npm run test             # Run vitest
npm run lint             # ESLint
npm run format           # Prettier
npm 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
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.