intune-mcp

MCP server providing read-only access to Microsoft Intune via the Microsoft Graph API. Allows Claude (or any MCP client) to query managed devices, apps, compliance policies, and configuration profiles.

Prerequisites

• Node.js >= 18
• An Azure AD (Entra ID) app registration with delegated permissions
• Azure CLI (az) for automated app registration (optional)

Quick Start

1. Register the Azure AD App

# Automated (requires Azure CLI + admin consent permissions)
.\scripts\register-app.ps1 -WriteEnv

# Or manually: create a public client app in Entra ID with these delegated permissions:
#   - DeviceManagementManagedDevices.Read.All
#   - DeviceManagementApps.Read.All
#   - DeviceManagementConfiguration.Read.All
# Then create .env:
#   AZURE_CLIENT_ID=<your-app-client-id>
#   AZURE_TENANT_ID=<your-tenant-id>

2. Install and Build

npm install
npm run build

3. Authenticate

npm run auth

Follow the device code prompt to sign in with your Microsoft account.

4. Run

# Stdio mode (for local MCP clients like Claude Code)
npm start

# HTTP mode (for shared/remote deployment)
npm run start:http

Transport Modes

Mode	Flag	Use Case
Stdio	(default)	Local, single-user, pre-authenticated
HTTP	--http or TRANSPORT=http	Shared deployment, multi-session, per-session auth

HTTP mode starts an Express server on port 3000 (configurable via --port or PORT env var) with endpoints:

Path	Method	Purpose
/mcp	POST	MCP JSON-RPC (Streamable HTTP)
/mcp	GET	SSE stream for server notifications
/mcp	DELETE	Session termination
/health	GET	Health check (status, version, session count)

Available Tools

Category	Tool	Description
Auth	authenticate	Device code sign-in (HTTP mode only)
Devices	list_devices	List managed devices with OData filter
Devices	get_device	Get device details by ID
Devices	search_devices	Search by name, UPN, or serial number
Apps	get_device_installed_apps	Detected apps on a device (beta API)
Apps	list_managed_apps	LOB/store/web apps in Intune
Compliance	list_compliance_policies	All compliance policies
Compliance	get_device_compliance_status	Per-device compliance state
Compliance	get_noncompliant_devices	Devices with noncompliant state
Compliance	get_policy_device_statuses	Per-device status for a policy
Config Profiles	list_configuration_profiles	Device configuration profiles
Config Profiles	get_profile_device_statuses	Per-device status for a profile
Config Profiles	get_device_configuration_status	Profile states on a device

Required Permissions (Delegated)

• DeviceManagementManagedDevices.Read.All
• DeviceManagementApps.Read.All
• DeviceManagementConfiguration.Read.All

Development

npm run dev          # TypeScript watch mode
npm test             # Run unit tests
npm run build        # Compile to dist/

Live Validation

Test all 12 endpoints against a real Intune tenant (requires prior authentication):

node scripts/validate-tools.mjs

Architecture

MCP Client -> Transport (stdio | HTTP) -> McpServer -> Tool Handlers -> GraphClient -> Microsoft Graph API

• Auth: MSAL device code flow, file-based token cache at ~/.intune-mcp/token-cache.json
• Logging: Structured JSON-lines at ~/.intune-mcp/logs/intune-mcp.log (10 MB rotation, 5 files)
• Graph client: Automatic retry with exponential backoff (429, 401, 5xx), Retry-After support, 30s request timeout, auto-pagination up to 10 pages
• HTTP mode: Per-session auth, 30-minute session TTL, 100-session cap