intune-mcp-write

MCP server providing read-write access to Microsoft Intune device properties and group memberships via the Microsoft Graph API. Allows Claude (or any MCP client) to manage devices, update properties, trigger syncs, and modify group membership.

Prerequisites

• Node.js >= 18

• An Azure AD (Entra ID) app registration with delegated permissions

Related MCP server: Microsoft 365 Core MCP Server

Setup

1. Register the Azure AD App

Create a public client app in Entra ID with these delegated permissions:

• DeviceManagementManagedDevices.ReadWrite.All

• DeviceManagementManagedDevices.PrivilegedOperations.All

• Device.Read.All

• GroupMember.ReadWrite.All

• Group.ReadWrite.All

• Directory.Read.All

• User.Read.All

Grant admin consent for all permissions.

Warning: PrivilegedOperations.All grants the ability to remotely wipe, retire, restart, and lock any managed device the authenticated user has Intune RBAC access to. Use Intune scope tags to limit which devices can be acted on.

Warning: Group.ReadWrite.All is required to edit dynamic-group membership rules (GroupMember.ReadWrite.All only covers adding/removing members, not group properties). It grants the token write access to all group properties tenant-wide (rename, delete, ownership), even though the curated tools only PATCH membershipRule. Only add it if you need the rule-editing tools, and note they are additionally gated behind ENABLE_DESTRUCTIVE_ACTIONS.

Then create .env:

AZURE_CLIENT_ID=<your-app-client-id>
AZURE_TENANT_ID=<your-tenant-id>

To enable destructive actions (retire, wipe, delete, and dynamic-rule editing), also set:

ENABLE_DESTRUCTIVE_ACTIONS=true

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 MCP clients like Claude Desktop):

npm start

HTTP mode (for web-based MCP clients):

npm run start:http

5. Claude Desktop Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "intune-mcp-write": {
      "command": "node",
      "args": ["F:/Repositories/Intune MCP Write/dist/index.js"],
      "env": {
        "AZURE_CLIENT_ID": "<your-client-id>",
        "AZURE_TENANT_ID": "<your-tenant-id>"
      }
    }
  }
}

Tools

Device Read Operations

Device Write Operations

User Operations

Remote Device Actions

retire_device, wipe_device, and delete_device require ENABLE_DESTRUCTIVE_ACTIONS=true and a confirmDeviceName parameter that must match the device's actual display name. The dynamic-rule editors (update_group_membership_rule, modify_membership_rule_value) are likewise gated behind ENABLE_DESTRUCTIVE_ACTIONS=true and take a matching confirmGroupName.

Group Read Operations

Group Write Operations

Dynamic Membership Rule Editing

Gated behind ENABLE_DESTRUCTIVE_ACTIONS=true. Both require Group.ReadWrite.All + admin consent, take a confirmGroupName that must match the group's display name, and default to dryRun=true (preview only — set dryRun=false to apply). A rule change triggers an async, tenant-wide membership recompute.

Bulk Operations

Bulk operations run sequentially with a configurable delay (default 200ms) between API calls to avoid Graph API rate limits. Each returns per-item success/failure status.

Compound Tools

list_devices, search_devices, list_device_categories, search_groups, list_group_members, list_device_groups, search_users, and the compound tools above all accept an optional format: "compact"|"full" parameter — "compact" returns one line per item, "full" returns every field. Compound tools default to "compact"; the rest default to "full" (list_group_members defaults to "compact").

Architecture

• Dual transport: Supports stdio (for direct MCP client integration) and HTTP/Streamable (Express-based with session management)

• GraphClient: Typed HTTP abstraction over Microsoft Graph with retry logic (3 retries for 401/429/5xx), exponential backoff, cursor-based pagination, and PUT support for $ref assignments

• Auth: MSAL device-code flow with token cache at ~/.intune-mcp-write/token-cache.json

• Logging: JSON structured logs to ~/.intune-mcp-write/logs/ with rotation (10MB max, 5 files)

Project Structure

src/
  index.ts              Entry point (stdio or HTTP transport)
  server.ts             MCP server factory, registers all tool modules
  graph.ts              GraphClient (GET/POST/PATCH/PUT/DELETE with retries, pagination)
  auth.ts               AuthManager (MSAL device-code flow, token cache)
  auth-cli.ts           CLI for interactive sign-in
  http.ts               Express-based HTTP/Streamable transport
  logger.ts             JSON file logger with rotation
  tools/
    device-properties.ts  Device read/write tools
    group-membership.ts   Group membership tools
    remote-actions.ts     Remote device actions (restart, lock, wipe, retire)
    user-operations.ts    User search and primary user management
    bulk-operations.ts    Bulk sync, rename, and group add tools
    compound.ts           Compound overview tools (device/group overview + search-and-expand)
    shared.ts             Error formatting, compact/full formatting, and shared helpers
  __tests__/
    graph.test.ts         GraphClient unit tests
    shared.test.ts        Shared helper unit tests (errors, format, sanitization)
    device-properties.test.ts  list_devices/search_devices tool tests
    device-properties-extended.test.ts  Category, delete tool tests
    group-membership.test.ts  Group read/write tool tests
    remote-actions.test.ts  Remote action tool tests
    user-operations.test.ts  User operation tool tests
    bulk-operations.test.ts   Bulk operation tool tests
    compound.test.ts      Compound overview tool tests
scripts/
  validate-live.mjs       Read-only live validation against a real tenant
  validate-mcp-client.mjs End-to-end MCP client test (spawns the server over stdio)

Known Limitations

• Dynamic groups cannot have members added/removed (Graph API constraint)

• No policy/profile assignment management

• No conditional access visibility

• Bulk operations use sequential calls — not Graph API $batch; optimize later if throughput becomes an issue