Microsoft Entra ID MCP Server

Implements GraphAuthManager component that handles Microsoft Entra ID OAuth 2.0 authentication flows, including token acquisition, caching, and automatic refresh before expiration. Uses a facade pattern to abstract token lifecycle from resource modules, ensuring all Graph API calls execute with valid credentials without manual token management by the caller.

Exposes 40+ tools via FastMCP server that translates MCP JSON-RPC requests into structured Graph API calls. Each tool is registered with input/output schemas that enforce type safety and parameter validation. The server layer (server.py) acts as an orchestration hub, routing client requests to appropriate resource modules and translating responses back to MCP format.

Implements device management tools that query Microsoft Graph /devices endpoint to enumerate registered and managed devices, retrieve device properties (OS, compliance status, owner), and discover device-to-user mappings. Returns structured device objects including device name, OS version, compliance state, and registered owner identity. Supports filtering by device name, owner, or compliance status for device inventory and compliance audits.

Implements a modular architecture where 11 resource modules (users.py, groups.py, applications.py, service_principals.py, signin_logs.py, audit_logs.py, mfa.py, conditional_access.py, password.py, devices.py, permissions.py) each encapsulate domain-specific tools and Graph API integration logic. Each module exposes tools via @mcp.tool() decorators and uses a shared GraphClient facade for HTTP requests. Enables clean separation of concerns and independent testing of identity management domains.

Implements GraphClient utility class that wraps HTTP requests to Microsoft Graph API with automatic error handling, response parsing, and retry logic for transient failures. Translates Graph API error responses (4xx, 5xx) into structured exceptions with meaningful error messages. Handles pagination automatically for endpoints that return large result sets, enabling seamless iteration over multi-page results.

Provides configuration patterns and deployment instructions for integrating the MCP server with Claude Desktop (via ~/.claude/mcp.json) and Cursor IDE (via uv run on-demand execution). Enables AI agents in Claude and Cursor to invoke Entra ID tools directly through the MCP protocol. Supports persistent server mode (Claude Desktop) and on-demand execution (Cursor IDE) for different deployment scenarios.

Implements search_users, get_user_by_id, get_privileged_users, get_user_roles, and get_user_groups tools that query Microsoft Graph /users endpoint with OData filters and expand parameters. Supports searching by display name, email, or user principal name; retrieving full user profiles including job title, department, and manager; and discovering assigned roles and group memberships through transitive queries.

Exposes 11 tools for group lifecycle management including create_group, update_group, delete_group, add_group_member, remove_group_member, add_group_owner, remove_group_owner, and search_groups. Implements role-based membership where owners have administrative privileges over group settings and members have basic access. Uses Microsoft Graph /groups endpoint with nested /members and /owners collections.

Implements tools for service principal CRUD (create, read, update, delete) and application registration management (list_applications, get_application_by_id, create_application, update_application, delete_application). Includes permission discovery tools that enumerate assigned Graph API permissions (delegated and application-scoped) and role assignments. Uses /servicePrincipals and /applications endpoints with appRoleAssignments and oauth2PermissionGrants expansion.

Implements get_user_sign_ins tool that queries Microsoft Graph /auditLogs/signIns endpoint with date filtering and user principal name matching. Returns structured sign-in records including timestamp, client IP, device info, authentication method, and success/failure status. Supports filtering by date range (default 7 days) and user identity to enable security investigation and anomaly detection.

Implements get_user_audit_logs tool that queries Microsoft Graph /auditLogs/directoryAudits endpoint with date filtering and activity type matching. Returns structured audit records including timestamp, activity type (user creation, group modification, role assignment), actor identity, target resource, and result status. Supports filtering by date range (default 30 days) and activity category for compliance and forensic investigation.

Implements get_user_mfa_status and get_group_mfa_status tools that query Microsoft Graph /users and /groups endpoints with authentication method expansion to determine MFA enrollment status. Returns structured MFA capability including registered authentication methods (phone, authenticator app, FIDO2 key), MFA enforcement status, and compliance with organizational MFA policies. Uses /authentication/methods endpoint for detailed method enumeration.

Implements get_conditional_access_policies and get_conditional_access_policy_by_id tools that query Microsoft Graph /identity/conditionalAccess/policies endpoint. Returns structured policy definitions including conditions (user/group/app/location/device), grant controls (MFA requirement, device compliance), session controls (sign-in frequency, persistent browser), and enabled/disabled status. Supports policy enumeration and detailed policy inspection for compliance and security analysis.

Implements reset_user_password_direct and related password management tools that invoke Microsoft Graph /users/{id}/authentication/passwordReset endpoint. Generates temporary passwords and optionally sends reset notifications via email. Supports both immediate password reset (direct) and user-initiated reset flows. Returns reset status and temporary password (if applicable) for credential provisioning workflows.