intune-mcp

A read-only Model Context Protocol server for Microsoft Intune that runs on your own machine and signs in as you. Harnesses such as Claude Code, Codex CLI and Pi start it as a local process; it answers questions about devices, policies, apps, enrollment and RBAC using your own delegated Microsoft Graph access, so results reflect what you may see in Intune.

• Nothing to host. No public endpoint, no client secret, no server to patch. It speaks MCP over stdio to the harness that launched it.

• Delegated and per-user. You sign in with Microsoft (MSAL public client, browser or device code). There is no app-only or shared credential path. Intune RBAC and scope tags are enforced by Microsoft.

• Read-only by construction. Only *.Read.All Graph scopes are in a closed allowlist; there is no write tool and no ReadWrite scope. Each tool call acquires a token for exactly one scope.

• Small, typed surface. The model never writes OData. Inputs are validated before any token request; results come back through per-endpoint field allowlists (no secrets, scripts, URLs, certificates or credentials), bounded in size, with untrusted text labelled as data.

• Tokens stay encrypted. The token cache uses the OS keychain (macOS Keychain, Windows DPAPI, Linux libsecret). If encryption is unavailable it refuses to run; there is no plaintext fallback.

Status: v0.1, early. The Graph layer and tools have been exercised against a real tenant through an earlier hosted deployment of the same code, and the local sign-in path has had one live check (macOS, device-code login, Pi). Browser login, other harnesses and platforms, and restricted users are not yet verified. See docs/VERIFICATION.md for exactly what has and has not been checked. Not affiliated with or endorsed by Microsoft.

Quick start

1. Create an Entra app registration and consent the Graph permissions: docs/SETUP.md.

2. Install and sign in (pinned to a release tag):

   export INTUNE_TENANT_ID='<directory-guid>'
   export INTUNE_CLIENT_ID='<app-registration-guid>'
   uvx --from git+https://github.com/sdkamer/intune-mcp@v0.1.1 intune-mcp login

3. Point your harness at uvx --from git+https://github.com/sdkamer/intune-mcp@v0.1.1 intune-mcp serve (examples for Pi, Claude Code and Codex CLI are in the setup guide).

Requires Python 3.13 and uv.

Related MCP server: sql-server-mcp

Tools

A fresh install enables only the devices group (6 tools with whoami). Everything else is opt-in: consent the group's Graph permission, set INTUNE_ENABLED_TOOL_GROUPS (for example devices,configuration,apps,rbac,enrollment), run intune-mcp login again, and restart your harness. intune-mcp status and the whoami tool both list the groups that are on.

Whoami plus five groups; only devices is on by default. Enable more with INTUNE_ENABLED_TOOL_GROUPS (for example devices,configuration,apps). Each group needs its Graph permission consented first.

41 tools with every group enabled. Three more are opt-in because Graph returns tenant-wide data that ignores a scoped admin's Intune scope: list_detected_apps, get_detected_app and list_compliance_setting_state_summaries (INTUNE_ENABLE_TENANT_INVENTORY=true). Per-tool details, returned and excluded fields: docs/tools/.

Security

How it works and what it does not protect against: docs/SECURITY-MODEL.md. To report a vulnerability see SECURITY.md.

Updates

The server checks the public GitHub releases API about once a day (in the background, never blocking) and, if a newer release exists, shows the version number in whoami, intune-mcp status and the server instructions. Only a strictly validated version number is ever shown. Turn it off with INTUNE_UPDATE_CHECK=0. Harnesses do not notify you themselves: update by changing the pinned tag in your configuration.

License

Apache License 2.0: see LICENSE. Not affiliated with or endorsed by Microsoft.

Development

uv sync
uv run pytest -q            # all mocked; no network
uv run ruff check . && uv run ruff format --check .

Tests use an in-process harness with a stubbed Microsoft Graph and a fake local identity. Everything in the suite is mocked; it proves the policy and plumbing, not Microsoft's behaviour.