Ms 365 Admin Mcp Server

ms-365-admin-mcp-server

[](https://github.com/okapi-ca/ms-365-admin-mcp-server/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@okapi-ca/ms-365-admin-mcp-server) [](LICENSE)

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](#acknowledgments) below.

Features

• 622 tools covering security, audit, identity, app credentials, guest users, Exchange, Intune (devices, apps, MAM, reports, 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

| Document | Purpose | | ---------------------------------------------------------------------- | --------------------------------------------------------------------------- | | [docs/USECASES.md](docs/USECASES.md) | 18 typical admin scenarios with sample prompts and tool lists | | [docs/playbooks/](docs/playbooks/README.md) | End-to-end security incident response playbooks | | [agent-skills/](agent-skills/README.md) | Drop-in skills for LLM agents (Claude Code et al.) with safety patterns | | [docs/APPREGISTRATION.md](docs/APPREGISTRATION.md) | Step-by-step Azure AD app registration and permission consent | | [docs/HTTPDEPLOYMENT.md](docs/HTTPDEPLOYMENT.md) | HTTP transport, JWT validation, Docker, Azure Container Apps | | [docs/AZUREDEPLOYMENTSECURITY.md](docs/AZUREDEPLOYMENTSECURITY.md) | Threat model, required controls, and checklist for Azure production deploys | | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common errors and how to diagnose them | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Internal architecture and code generation pipeline | | [docs/RISKMODEL.md](docs/RISKMODEL.md) | Risk classification rubric for write tools | | [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute new tools, presets, and fixes | | [SECURITY.md](SECURITY.md) | Vulnerability reporting and operator hardening checklist | | [CHANGELOG.md](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"
      }
    }
  }
}

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](.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.

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-/. Claude Desktop / Claude Code then launches mcp-remote normally and finds the cached tokens without ever opening a browser.

See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md#oauth--browser-authentication-problems) 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   Filter tools by regex pattern
--preset          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            Cloud environment: global (default) or china
--transport        Transport: stdio (default) or http
--port           HTTP port (default: 8080)
--host          HTTP bind address (default: 127.0.0.1)
--allowed-clients   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 |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: okapi-ca
• Source: okapi-ca/ms-365-admin-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.