# 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

```powershell
# 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

```bash
npm install
npm run build
```

### 3. Authenticate

```bash
npm run auth
```

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

### 4. Run

```bash
# 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

```bash
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):

```bash
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